galaxy-game/gateway/docs/runtime.md

Runtime and Components

The diagram below focuses on the deployed galaxy/gateway process and its runtime dependencies.

flowchart LR
    subgraph Clients
        Public["Public REST clients"]
        Authd["Authenticated edge clients\n(Connect / gRPC / gRPC-Web)"]
    end

    subgraph Gateway["Edge Gateway process"]
        PublicHTTP["Public HTTP listener\n/healthz /readyz /api/v1/public/auth/*"]
        AuthGRPC["Authenticated edge listener (h2c)\nConnect / gRPC / gRPC-Web\nExecuteCommand / SubscribeEvents"]
        AdminHTTP["Optional admin HTTP listener\n/metrics"]
        BackendREST["backendclient.RESTClient\nsessions + public auth + user/lobby"]
        BackendPush["backendclient.PushClient\nSubscribePush consumer"]
        Replay["Replay reservation client"]
        PushHub["PushHub"]
        Dispatcher["Push event dispatcher"]
        Telemetry["Logs, traces, metrics"]
    end

    Public --> PublicHTTP
    Authd --> AuthGRPC
    PublicHTTP --> BackendREST
    AuthGRPC --> BackendREST
    AuthGRPC --> Replay
    AuthGRPC --> PushHub
    BackendPush --> Dispatcher
    Dispatcher --> PushHub
    PublicHTTP --> Telemetry
    AuthGRPC --> Telemetry
    AdminHTTP --> Telemetry

    Redis["Redis\nanti-replay reservations only"]
    Backend["backend service\nHTTP + gRPC"]
    Metrics["Prometheus / OTLP collectors"]

    BackendREST --> Backend
    BackendPush --> Backend
    Replay --> Redis
    Telemetry --> Metrics

Notes:

• cmd/gateway refuses startup when Redis connectivity, the backend endpoint, or the response signer is misconfigured.
• Session lookup is synchronous: every authenticated edge request triggers one GET /api/v1/internal/sessions/{id} call to backend; there is no process-local projection.
• The authenticated edge listener is built on connectrpc.com/connect and natively serves the Connect, gRPC, and gRPC-Web protocols on a single HTTP/2 cleartext (h2c) port. Browsers use Connect; native clients can use either Connect or raw gRPC framing against the same listener.
• backendclient.PushClient keeps a long-lived Push.SubscribePush stream open. The dispatcher converts inbound pushv1.PushEvent frames into either PushHub.Publish (for client events) or PushHub.RevokeDeviceSession / PushHub.RevokeAllForUser (for session_invalidation).
• user.* and lobby.* authenticated routes are forwarded to backend through the same REST client, with X-User-Id carrying the verified identity.
• The admin listener is optional and serves only Prometheus text metrics.