​

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.