# Runtime and Components

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

```mermaid
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.