Skip to main content

​
Deployment Architecture

​
SECTION 30 — DEPLOYMENT ARCHITECTURE

​
30.1 Infrastructure Stack

​
30.2 Containerisation

  • Both the Next.js frontend and the FastAPI backend are containerised via Docker.
  • Each service has its own Dockerfile and docker-compose.yml for local development.
  • Google Cloud Run receives the Docker images via a CI/CD pipeline (e.g. GitHub Actions → Google Artifact Registry → Cloud Run deploy).
  • Developer is responsible for defining the CI/CD pipeline based on this architecture.

​
30.3 Scheduled Jobs (Google Cloud Scheduler)

​
30.4 Real-Time Architecture Requirement

The real-time document co-editing sync (Teacher read-only view during Editor review) requires persistent connection support. Options: Option A — WebSocket via Starlette (built into FastAPI)
  • Cloud Run supports WebSocket via HTTP/2.
  • Ensure Cloud Run is configured with --session-affinity for WebSocket connections.
  • Implement reconnection logic on the client.
Option B — Supabase Realtime (managed)
  • Use Supabase Realtime as a managed WebSocket layer.
  • Backend publishes document state changes to Supabase channels.
  • Frontend subscribes to channels and receives real-time updates.
Developer selects the approach based on expertise and project constraints. Both are acceptable. WebSocket is preferred to avoid adding another third-party dependency.

​
30.5 Environment Configuration

  • Three environments: development, staging, production.
  • Environment is reflected in metadata.environment field on all documents.
  • Each environment has its own Neon DB branch, its own Cloud Run services, and its own Cloudinary environment.
  • Never share production credentials with development or staging environments.