galaxy-game/ARCHITECTURE.md

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.
• Gateway owns external delivery channels; the v1 implementation uses authenticated gRPC server-streaming push, while long-polling remains out of scope.

flowchart LR
    Client["Clients\n(native and browser)"]
    Gateway["Edge Gateway\npublic REST + authenticated gRPC"]
    Auth["Auth / Session Service"]
    Business["Business Services"]
    Redis["Redis\nsession cache + replay keys + event streams"]
    Telemetry["Telemetry Backends\nPrometheus / OTLP"]

    Client --> Gateway
    Gateway --> Auth
    Gateway --> Business
    Gateway --> Redis
    Gateway --> Telemetry
    Auth --> Redis
    Business --> Redis

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
• authenticated gRPC server-streaming 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 message_type

No business service should receive an unauthenticated external request.

Push Flow

The gateway owns external delivery connections. The v1 gateway uses authenticated gRPC server-streaming push. Long-polling remains out of scope for the implemented gateway.

Flow:

1. client opens authenticated push connection through gateway
2. gateway binds connection to user_id and device_session_id
3. gateway starts the channel with a signed service event that includes the current server time for clock offset calculation
4. internal services publish client-facing events to pub/sub targeted by user_id and optionally by device_session_id
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
• message_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 authenticated push streams 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.