Hosting, Network & Deployment
=============================

Cloud Hosting Model
-------------------

The platform is hosted on **Google Cloud Platform**:

- **Secrets** — GCP Secret Manager is the uniform secrets backend for every
  service (Go and Rust), with secret namespaces selected per environment
  (``SECRET_MANAGER`` / staging variants) and workload identity used in CI.
- **Container images** — built as multi-stage Docker images (Go: alpine or
  distroless-static runtimes; Rust: slim-bookworm builders with mold linker
  and dependency-layer caching) and pushed to GCP Artifact Registry.
- **Object storage** — Google Cloud Storage for document/bucket use.
- **Orchestration** — services are deployed as containers behind Kubernetes
  service DNS (internal addressing of the form ``service-name:80``), with
  graceful-shutdown behaviour tuned to Kubernetes termination grace periods.

Environments
------------

.. list-table::
   :header-rows: 1
   :widths: 20 80

   * - Environment
     - Description
   * - Local / development
     - Developer environment using dotenv files and docker-compose
       (PostgreSQL, Redis, single-node Kafka).
   * - Sandbox
     - A first-class product environment: tenants receive sandbox API keys,
       the gateway routes sandbox requests to dedicated staging deployments
       (``*-staging.gravv.xyz``) over TLS, provider integrations run in
       sandbox modes with webhook simulators, and secrets come from a separate
       Secret Manager namespace.
   * - Live / production
     - Production environment; live secrets, live provider credentials, and
       a production access gate in the Identity service controlling which
       tenants may transact live.

The branch model (``dev`` → ``main``) mirrors environment promotion.

Network Topology
----------------

- **North-south traffic.** All client traffic enters through the API gateway
  over HTTPS. The gateway enforces allowed-host checks, CORS policy,
  authentication, per-tenant rate limiting, and idempotency before any
  internal call.
- **East-west traffic.** Internal service-to-service communication is gRPC.
  In-cluster calls use Kubernetes DNS; cross-environment calls (gateway →
  sandbox) use TLS with a pinned CA bundle layered over native roots.
- **Ports.** Uniform convention: 80/8080 for the main gRPC (or HTTP) listener
  and 8081 for the HTTP health endpoint (``/healthz``, ``/livez``,
  ``/readyz``).
- **Messaging.** Kafka connects services asynchronously; brokers are reached
  over TLS with certificate-based authentication in sandbox/live.

Release Process (CI/CD)
-----------------------

Every deployable service carries an identical GitOps workflow: pushes and pull
requests to ``dev`` and ``main`` trigger a shared reusable deployment workflow
(held in a central deployment repository) using OIDC workload identity
federation — no long-lived cloud credentials in CI. Shared libraries follow
their own pipelines: the commons library runs test-and-release workflows, and
the specifications repository runs buf lint and breaking-change detection on
every pull request before publishing generated Go and Rust packages.

Database migrations are versioned SQL files applied automatically at service
startup (Rust services, identity) or via migration tooling (golang-migrate,
goose) during deployment.

Backup & Recovery
-----------------

- Each service owns an isolated PostgreSQL database, bounding the blast radius
  of any data incident to a single domain.
- Money-movement state is event-sourced over Kafka with durable topics, so
  downstream records (transactions, audit logs) can be rebuilt from the event
  stream.
- Multi-layer reconciliation jobs (onramp routine/full/batch/deep cycles,
  deposit reconcilers, sweep reconciliation) continuously verify stored state
  against provider records and flag stuck or critical transactions to
  operations via Slack.
- The audit trail (PostgreSQL audit/response logs plus MongoDB session
  documents) provides an independent record for reconstruction and forensics.