AR-020 — Backend, store and telemetry (LOCKED)

Promoted from Action Required card AR-020. This is the decision of record.

This is actually one of the most important architectural decisions in the project. My recommendation is don't build everything yourself. Use Unity Gaming Services (UGS) where they are already excellent, and build only the parts that make Astra unique. You're one founder. Your advantage is the game, not writing another authentication system. --- # AR-020 — Backend, Store & Telemetry (LOCKED) Status: APPROVED Priority: HIGH --- # Backend Philosophy Astra follows a Hybrid Backend Architecture. The project uses: * Unity Gaming Services (UGS) for multiplayer infrastructure. * Custom Aurion Backend for game-specific systems. Rule: > Never rebuild infrastructure that already exists and is battle-tested. Only build systems that are unique to Astra. --- # High Level Architecture text MOBILE CLIENT │ Unity Netcode (NGO) │ ┌──────────────┴──────────────┐ │ │ Unity Gaming Services Aurion Backend │ │ │ │ Authentication Player Profile Matchmaking Inventory Lobby Cosmetics Relay (Early MVP) Store Cloud Diagnostics Progression Analytics Seasons Crash Reporting Economy ProjectOS LiveOps Admin Panel Asset Database Telemetry Warehouse --- # Unity Gaming Services (UGS) UGS is responsible only for multiplayer infrastructure. ## Authentication UGS Authentication Supports * Google * Apple * Guest * Facebook (optional later) Reason Don't build login systems. --- ## Lobby UGS Lobby Responsible for * Creating matches * Inviting friends * Duo queue Nothing else. --- ## Matchmaking UGS Matchmaker Responsible for Finding players. Not progression. Not inventory. --- ## Relay (Early Development) Used during MVP and Alpha. Later Can migrate to dedicated servers. --- ## Cloud Diagnostics Crash reports Stack traces Performance logs Device issues --- ## Remote Config (Recommended) Enable/disable events XP multipliers Season switches Without updating the app. --- # Aurion Backend (Custom) Everything unique to Astra lives here. --- ## Player Profile Stores * Name * Avatar * Level * Hero Mastery * Weapon Mastery * Legend Progression * Statistics --- ## Inventory Stores * Owned cosmetics * Character unlocks * Weapon skins * Barrier skins * Emotes * Banners Gameplay items NEVER stored here. Relics and runes are match-only. --- ## Store Handles * Cosmetic catalogue * Seasonal bundles * Temple Journey rewards * Featured items Never contains gameplay power. --- ## Entitlement Service One of the most important systems. Every purchase creates Permanent entitlement. Example Player ↓ Purchased Hanuman Sacred Armor ↓ Entitlement Created ↓ Inventory Updated ↓ Immediately available Nothing is unlocked until Entitlement exists. --- ## Progression Tracks Player Hero Weapon Legend Battle Pass Everything cosmetic. --- ## Seasons Stores Current Season Past Seasons Rewards Availability --- ## ProjectOS Lives inside Aurion Backend. Completely separate from game runtime. --- ## Admin Dashboard Used by developers. Can * Add cosmetics * Enable events * View analytics * Moderate players * Ban accounts --- # Store Architecture text Store ↓ Category ↓ Item ↓ Price ↓ Availability ↓ Purchase ↓ Validation ↓ Entitlement ↓ Inventory ↓ Player Everything server validated. --- # In-App Purchases (IAP) Platform stores remain the payment provider. * Apple App Store * Google Play Flow: 1. Player selects cosmetic. 2. Platform completes payment. 3. Receipt sent to Aurion Backend. 4. Backend validates receipt with Apple/Google. 5. Backend creates entitlement. 6. Inventory updates. 7. Client refreshes inventory. Never trust the client. --- # Cosmetics Stored server side. Player cannot modify. Every cosmetic identified by UUID. --- # Telemetry Every important event should be recorded. Examples Match Started Match Finished Player Eliminated Weapon Used Barrier Used Ability Activated Hero Selected Zone of Death Loot Picked Store Viewed Purchase Completed Crash Disconnect Ping FPS Battery Device Model Everything anonymous where possible and compliant with applicable privacy laws. --- # Analytics Dashboard ProjectOS should visualize: Gameplay * Match duration * Win rate * Hero usage * Weapon usage * Barrier usage * Average survival time * Hot drop locations Technical * FPS * RAM usage * Battery usage * Crash rate * Network latency * Device distribution Business * DAU * MAU * Retention * Session length * Conversion * Revenue * Cosmetic popularity --- # Security The client is never trusted. The server validates: * Purchases * Inventory * Progression * Rewards * Match results * Statistics * Unlocks Clients only request actions. Servers approve them. --- # Database Single PostgreSQL database. Dedicated schema astra Tables * accounts * profiles * inventory * cosmetics * entitlements * progression * hero_mastery * weapon_mastery * seasons * telemetry * purchases * bans * analytics * liveops Prisma manages all migrations. --- # LiveOps Aurion Backend controls * Events * Seasons * Featured Store * Login Rewards * Maintenance * Emergency balancing * Server announcements No client update required. --- # 🔒 Final Architecture Decision | System | Owner | | ---------------------- | --------------------------------- | | Authentication | Unity Gaming Services | | Lobby | Unity Gaming Services | | Matchmaking | Unity Gaming Services | | Relay (MVP) | Unity Gaming Services | | Dedicated Game Servers | Contabo (server-authoritative) | | Game Simulation | Unity Dedicated Server on Contabo | | Player Profile | Aurion Backend | | Inventory | Aurion Backend | | Cosmetics | Aurion Backend | | Store | Aurion Backend | | Entitlements | Aurion Backend | | Progression | Aurion Backend | | Seasons | Aurion Backend | | LiveOps | Aurion Backend | | ProjectOS | Aurion Backend | | Telemetry Storage | Aurion Backend (PostgreSQL) | | Crash Diagnostics | Unity Gaming Services | | Remote Configuration | Unity Gaming Services | --- ## Recommendation I would make one change to our earlier plan. For launch, use UGS Matchmaking + Lobby, but do not rely on Relay for production matches. Instead: * Use Unity Dedicated Server builds running on your Contabo VPS infrastructure. * Let UGS handle player discovery and match formation. * Once a match is formed, players are handed off to a dedicated authoritative game server. This keeps the gameplay fair, reduces cheating, scales better, and gives you full control over server costs and infrastructure while still benefiting from Unity's mature multiplayer services.