Deployment Overview

The Shift Platform ships as a single container exposing a single port (3000). All service APIs run in-process via the Hono gateway -- there is no inter-service HTTP proxying, no sidecar containers, and no service mesh. This design keeps the deployment topology simple while supporting horizontal scaling.

Architecture

Client --> Gateway (:3000)
           |-- /healthz              (platform-core health)
           |-- /api/v1/catalog/*     (yellowpages -- in-process)
           |-- /api/v1/passport/*    (passport -- in-process)
           |-- /api/v1/pulse/*       (pulse -- in-process)
           |-- /api/v1/ledger/*      (ledger -- in-process)
           |-- /api/v1/palette/*     (palette -- in-process)
           |-- /api/v1/communication/* (communication -- in-process)
           |-- /api/v1/inference/*   (inference -- in-process)
           |-- /api/v1/git/*         (git -- in-process)
           |-- /api/v1/stage/*       (stage -- proxy or in-process fallback)
           +-- /*                    (static web UI -- SPA with per-service fallbacks)

Environments

Environment	URL	Branch	Replicas	Namespace
Production	app.the-shift.dev	main	2	shift-platform
Staging	staging.the-shift.dev	stage	1	shift-platform-staging
Local K8s	shift.lvh.me	--	1	shift-platform

CI/CD Pipeline

Push-to-deploy via GitHub Actions:

1. Lint -- bun run check (Biome)
2. Test -- bun run test (bun:test across all services)
3. Docker Build -- Multi-stage build (deps, web assets, production image)
4. Push -- Image pushed to GCP Artifact Registry
5. Deploy -- kubectl apply to GKE cluster with Kustomize overlay

Pushing to main triggers a production deploy. Pushing to stage triggers a staging deploy.

Storage

Both production and staging use Convex as the storage backend (SHIFT_STORAGE=convex), with a self-hosted Convex instance running in-cluster. For local development, you can use either Convex or file-based storage.

Next Steps

• Docker -- Building and running the container image
• Kubernetes -- Kustomize manifests and cluster topology
• Local K8s -- Running the full stack locally with kind
• Staging -- Staging environment details
• Production -- Production environment details
• Environment Variables -- Full configuration reference