Architecture Log: Cross-Platform Multiplayer Ecosystem

Context

The architecture requires an in-memory store for caching and ephemeral session management. As a Day-0 project, capital efficiency and deployment speed were primary constraints. Benchmarking of external data stores (e.g., Memcached, Dragonfly) was bypassed to avoid introducing networking overhead outside our primary AWS VPC.

Decision

Intercepted the default Redis integration and provisioned AWS ElastiCache (Valkey) as the foundational in-memory store.

Rationale

• Ecosystem Anchoring: Restricting the selection to native AWS managed services eliminates the operational overhead of VPC peering and third-party billing.
• Capital Efficiency: AWS ElastiCache for Valkey operates at a 33% lower cost compared to equivalent Redis nodes, optimizing initial startup runway.
• Risk Mitigation: Valkey acts as a 1:1 API drop-in replacement for Redis. If Valkey suffers from maintenance degradation, the connection string can be migrated back to ElastiCache Redis with minimal code changes.

Context

The platform requires a standalone game launcher handling authentication handoffs, social features, and binary delta patching. Extensive ecosystem features for Android necessitated a robust mobile foundation.

Decision

Build a Flutter Frontend connected to a Rust Core via flutter_rust_bridge (FFI).

Rationale

• Resource Optimization: Consolidating UI development into Flutter reduces the overhead of staffing platform-specific engineering teams.
• Discarded Alternatives: Electron was rejected due to its bundled Chromium footprint and lack of mobile support. Tauri was also passed over, as its Android ecosystem was deemed too immature for our mobile roadmap while introducing UI inconsistencies via its webview dependency.
• Native Extensibility: Flutter's method channels provide an escape hatch for platform-level implementations where cross-platform abstractions fail.
• Backend Integration: Rust guarantees memory safety, which Flutter natively supports via efficient FFI integration.
• Platform Isolation: Both tools allow conditional compilation. Heavy Rust binaries (BLAKE3, mmap) are dropped for lean Android builds while preserving bare-metal disk I/O for desktop users.

Context

The core gameplay loop demands high-frequency data synchronization. The Unity client, especially on constrained hardware, is susceptible to frame drops from Garbage Collection (GC) spikes during heavy serialization workloads. CPU allocation overhead and AWS egress bandwidth must be minimized.

Decision

Implement gRPC/Protobuf for all high-frequency game data and WebSockets. Utilize hash-gated fetching for large payloads, and restrict JSON/REST to initial authentication.

Rationale

• GC Mitigation: JSON was rejected for game-state transfer. Parsing large JSON strings in C# creates heap allocations, causing GC stutter. Protobuf's binary serialization reduces client-side processing overhead.
• Egress Cost Optimization: Protobuf's binary format reduces payload size compared to verbose JSON, lowering AWS data transfer out (DTO) costs at scale.
• Hash-Gated Fetching: To mitigate bandwidth waste, large profile payloads are prefaced with a lightweight hash comparison. The Unity client only fetches and deserializes the full binary payload if the server-side hash invalidates the local cache.
• Architectural Exception: JSON/REST is retained for identity management. Authentication requests are infrequent, making the GC impact negligible and simplifying the web portal's tooling. This allows us to utilize standard web tooling for our web portal without forcing complex gRPC-web proxies into the browser layer.

Context

The web portal serves as the primary user-facing application, bridging interactive content with secure identity management. The existing infrastructure (Wix) limited our ability to implement fluid UI experiences, obscured granular SEO control, and incurred recurring costs.

Decision

Build a custom Svelte application deployed via Cloudflare Pages.

Rationale

• Cost & Control Optimization: Migrating off a managed builder grants granular DOM control for SEO. Cloudflare Pages leverages edge networks to effectively reduce portal OpEx to zero.
• Performance: Svelte provides granular state reactivity, critical for optimizing render times so complex scroll and animation libraries (Lenis) perform without framework-induced stuttering.
• Discarded Alternatives: React was rejected due to Virtual DOM overhead and unnecessary architectural complexity for our UI needs which makes it easy to write poorly optimized code without strict enforcement standards. SolidJS offered superior raw performance but its developer experience was less conducive to rapid iteration.
• Hiring Risk Mitigation: Acknowledged the smaller talent pool for Svelte by establishing a strict pre-production threshold. If staffing requirements were not met 3 months prior to project kickoff, the architecture had a pre-approved fallback to revert to React, absorbing the framework's overhead to protect the delivery timeline.
• Edge Computing Integration: Svelte server actions compile to Cloudflare Workers, allowing secure proxying to the AWS backend and native Web Crypto API integration with zero cold-starts.

Context

During R&D, a strict 8GB shared memory limit was identified on the Meta Quest 3. Loading 1:1 scale environments as monolithic scenes would lead to Out-Of-Memory (OOM) crashes on standalone VR hardware.

Decision

Architect the technical blueprint for an asynchronous Addressable Spatial Grid, shifting away from standard Unity scene loading.

Rationale

• Risk Identification: Manual modeling of a cross-platform open world was determined to be a production risk without aggressive LOD and texture-stripping pipelines.
• Hardware Overrides: The architecture dictates dynamically streaming asset chunks in and out of memory based on the player's active radius, appending platform-specific suffixes (e.g., baked lighting for Android, dynamic lighting for PC).
• Domain Handoff: Drafted as an R&D blueprint to serve as a mandate for incoming Technical Art and Client Engineering leads, providing the framework needed to execute CI/CD automation.

Context

Managing a single codebase for Consoles, PC, and VR introduces the risk of platform dependencies bleeding together. If high-level scripts reference opposing SDKs, the compiler fails and breaks the CI/CD pipeline.

Decision

Enforce strict compiler-level isolation using Unity Assembly Definitions (.asmdef) across the project structure.

Rationale

• Interface-First Architecture: Core assemblies contain only interfaces and data models (e.g., `IInteractable`). Platform-specific assemblies (e.g., `PC.asmdef`, `VR.asmdef`) implement these interfaces but are forbidden from referencing each other.
• Selective Wrapping: Third-party code is sandboxed within its own .asmdef to prevent dependency pollution. Core infrastructure with a high risk of vendor lock-in (Analytics, Matchmaking) is hidden behind internal interfaces. Tightly coupled utilities (DOTween, UI frameworks) are exempt to maintain developer velocity.
• Strategic Handoff: Established to protect architectural integrity from Day 1, providing the foundational ruleset required to maintain a hardware-isolated codebase.

Context

The backend needs to handle stateless HTTP traffic (Identity) and highly stateful, long-lived WebSocket connections (Matchmaking, Chat). The planned deployment on AWS App Runner was impacted by the service's scheduled deprecation.

Decision

Abandoned App Runner. Bifurcated the compute layer: stateless APIs deploy via AWS ECS Express Mode, while WebSockets route to ECS Fargate.

Rationale

• Vendor Deprecation: Immediate migration to the core ECS control plane ensured long-term platform stability.
• Capital Efficiency: ECS Express Mode reduces infrastructure expense for stateless requests during development by sharing a single Application Load Balancer (ALB) across multiple services.
• Protocol Alignment: Express Mode handles burst-scaling for HTTP authentication, while Fargate provides the granular network control required to prevent websocket drops during sustained sessions.
• Scale-Out Path: Standardizing on the ECS control plane ensures a smooth migration of stateless APIs to Fargate when traffic hits production scale.