# Services Architecture Galaxy Plus: Turn-based Strategy Game ## Purpose This document fixes the high-level service architecture of the system. It is the starting point for implementing the external edge layer, authentication/session management, business services, and push delivery. ## Main Principles - The system exposes a single external entry point: **Edge Gateway**. - Internal business services are **not reachable directly from outside**. - Any external command, except public auth commands, must be authenticated before it is routed further. - Gateway handles only edge concerns. Business validation and domain rules remain inside business services. - Push / long-polling delivery is also handled by the gateway. ## Main Components ### 1. Edge Gateway The gateway is the only public entry point for client traffic. Responsibilities: - transport parsing - authentication of external requests - transport integrity checks - session cache lookup - request signature verification - timestamp window verification - anti-replay checks - rate limiting and abuse protection - command routing - basic policy enforcement - long-polling / push connection handling - delivery of client-facing events from pub/sub The gateway must not implement domain-specific business logic. ### 2. Auth / Session Service This service owns authentication and device session lifecycle. Responsibilities: - `send_email_code` - `confirm_email_code` - device session creation - public key registration for device sessions - session revoke / logout - persistence of session state - publishing session state changes for cache invalidation/update This service is the source of truth for `device_session` state. ### 3. Session Store Persistent storage for device sessions. Typical fields: - `device_session_id` - `user_id` - client public key - session status - creation / revoke timestamps - optional client metadata ### 4. Session Cache Fast lookup cache used by the gateway. Purpose: - resolve `device_session_id -> user_id + public_key + status` - avoid synchronous calls from gateway to auth/session service on every request Cache updates should be driven by session lifecycle events and may also use TTL. ### 5. Anti-Replay Store Edge-level storage for recently seen transport `request_id` values. Purpose: - reject replayed authenticated transport messages within the allowed time window This is transport-level replay protection, not business idempotency. ### 6. Rate Limit Store Shared state for edge-level throttling and abuse control. Typical dimensions: - IP / network - `device_session_id` - `user_id` - command class ### 7. Business Services Internal services that process authenticated commands. Responsibilities: - business validation - authorization by `user_id` - ownership checks - domain invariants - state transitions - business idempotency where required - publishing domain events and/or client-facing events Business services do not verify external signatures and do not access external clients directly. ### 8. Event Bus / Pub-Sub Used for internal event distribution. Purposes: - session cache invalidation/update - client-facing event delivery through the gateway - optional internal domain event propagation between services ## External Flows ### Public Auth Flow These commands are public and do not require an existing device session: - `send_email_code` - `confirm_email_code` Flow: 1. client sends public auth command to gateway 2. gateway applies public-edge checks (format, rate limits, abuse policy) 3. gateway routes command to auth/session service 4. auth/session service performs auth logic 5. if login is confirmed, auth/session service creates `device_session` 6. auth/session service publishes cache update/invalidation event ### Authenticated Command Flow All other external commands require authentication. Flow: 1. client sends authenticated request to gateway 2. gateway validates transport envelope presence and protocol version 3. gateway resolves `device_session_id` through session cache 4. gateway rejects unknown or revoked sessions 5. gateway verifies request signature 6. gateway verifies timestamp window 7. gateway verifies anti-replay constraints 8. gateway applies rate limits and basic policy checks 9. gateway extracts authenticated context, including `user_id` 10. gateway routes the request to the target business service based on `command_type` No business service should receive an unauthenticated external request. ### Push / Long-Polling Flow The gateway owns external push / long-polling connections. Flow: 1. client opens authenticated push / long-polling connection through gateway 2. gateway binds connection to `user_id` and `device_session_id` 3. gateway may send current server time for clock offset calculation 4. internal services publish client-facing events to pub/sub 5. gateway consumes those events and delivers them to the proper client connections Gateway is a delivery layer, not the source of business events. ## Internal Contract Between Gateway and Business Services Business services should receive an internal authenticated command, not raw external transport data. Typical internal authenticated context: - `user_id` - `device_session_id` - `command_type` - verified payload bytes - transport `request_id` - optional command id / trace id - optional client metadata relevant for logging Business services must trust only the gateway as their external ingress. ## Separation of Responsibilities ### Gateway is responsible for - who sent the request - whether transport integrity is valid - whether the request is fresh - whether replay is detected - whether request volume is acceptable - where to route the request ### Business services are responsible for - whether the user is allowed to perform the business action - whether the target object belongs to the user - whether the domain state transition is valid - whether business idempotency rules are satisfied ## Revocation Behavior When a device session is revoked: - auth/session service updates the source of truth - auth/session service publishes revoke/invalidation event - gateway updates or invalidates session cache - gateway rejects further requests for that session - gateway closes active push / long-polling connections bound to that session, if applicable ## Non-Goals The gateway is not a place for full domain authorization logic. It must not become a business “god service”. The auth/session service is not the hot path for every authenticated request. The gateway should authenticate most requests from cache, not by synchronous round-trips.