Skip to content

Infrastructure and Local Operations

Topology

flowchart TD
  classDef default fill:#1e293b,stroke:#38bdf8,stroke-width:2px,color:#f8fafc
  classDef highlight fill:#065f46,stroke:#34d399,stroke-width:2px,color:#f0fdf4
  Terraform["Terraform dev environment"]:::highlight --> Run["Cloud Run API"]
  Terraform --> Jobs["Cloud Run migrate/seed/ingest jobs"]
  Terraform --> SQL["Cloud SQL PostgreSQL"]
  Terraform --> Bucket["GCS bucket"]
  Terraform --> Secrets["Secret Manager + IAM"]
  Firebase["Firebase Hosting/Auth"] --> Run
  Local["Docker Compose"] --> LocalSQL["Postgres + pgvector"]
  Local --> Redis["Redis"]
  linkStyle default stroke:#64748b,stroke-width:2px

Local commands

just setup, just up, just migrate, just seed, just ingest-rag, just up-all, just health, and just test form the documented lifecycle. Docker Compose supplies local Postgres/pgvector and Redis.

GCP

Terraform provisions an Artifact Registry, Cloud SQL, GCS, Secret Manager values, least-privilege service accounts, Cloud Run API, and separate jobs. The repository notes that dev is the active PoC environment; prod is reference architecture.

Operations

Cloud Run scales the API to zero with bounded max instances. Health is exposed at /health. Scripts deploy, pause, resume, destroy, and ingest. Secrets are passed through Secret Manager rather than committed configuration. Actual alerting and production SLOs remain open questions.

Terraform module responsibilities

Module Provisioned boundary
cloud-run-api API service, environment, Cloud SQL attachment, secret references
cloud-run-job Reusable migration, seed, and ingestion job
cloud-sql-postgres Instance, database, user, and connection name
gcs-bucket Regional object bucket and lifecycle settings
secrets Secret Manager resources and versions
iam Service account and least-privilege bindings

The dev environment creates a random database password, derives a Cloud SQL socket URL, injects secret IDs into Cloud Run modules, and caps the API at three instances. This is a clear deployment dependency graph: database and secrets precede the API and jobs.

Startup and deployment sequence

  1. Authenticate with gcloud and select a project.
  2. Enable required APIs and configure billing/Firebase exceptions.
  3. Run Terraform init/plan/apply for dev.
  4. Build and publish the backend image to Artifact Registry.
  5. Run migration and seed jobs.
  6. Run RAG ingestion as a job.
  7. Deploy the Firebase frontend and point its API origin at Cloud Run.
  8. Verify /health, authentication, database connectivity, storage, and RAG.

Operational gaps

The repository has lifecycle scripts, but evidence for backups, Cloud SQL maintenance windows, bucket retention, alerting, tracing, structured request IDs, and incident response is limited. Those are essential before calling the PoC production-ready.