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.

```mermaid
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](./gateway/README.md)

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](./authsession/README.md)

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.