From a488a385ad9ba48541960203aa58674b9d1b6ae8 Mon Sep 17 00:00:00 2001 From: zwitschi Date: Sat, 11 Oct 2025 18:58:05 +0200 Subject: [PATCH] docs: expand deployment view with infrastructure overview and CI/CD details --- docs/architecture.md | 30 +++++++++++++++++++++++++++++- 1 file changed, 29 insertions(+), 1 deletion(-) diff --git a/docs/architecture.md b/docs/architecture.md index 3053d90..1b961c2 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -112,7 +112,35 @@ Runtime scenarios, sequence diagrams, and performance considerations are documen ## 7. Deployment View -To be detailed in subsequent sections. +### 7.1 Infrastructure Overview + +- **Application Containers**: Backend (FastAPI + Uvicorn) and frontend (Vite/Node) each ship with dedicated Dockerfiles under `backend/` and `frontend/`. +- **Data Services**: PostgreSQL with PostGIS and Redis run as managed containers; volumes persist database state between restarts. +- **Reverse Proxy**: An Nginx gateway routes `/api` traffic to the backend service and serves built frontend assets in production deployments. + +### 7.2 Local Development Topology + +- `docker-compose.yml` orchestrates backend, frontend, Postgres/PostGIS, Redis, and Nginx for an end-to-end sandbox. +- Developers may alternatively run the frontend and backend directly via `npm run dev` and `uvicorn` while relying on the compose-managed data services. +- Environment variables are loaded from the repository root `.env` file (not tracked); a sample configuration lives at `.env.example`. + +### 7.3 Continuous Integration & Delivery + +- **CI Pipelines**: GitHub Actions lint and format both stacks, execute `pytest`, and run Playwright login flows on every pull request. +- **Build Artifacts**: Successful pipelines publish container images tagged with the commit SHA to the project registry (planned). +- **Promotion Strategy**: Main branch builds deploy to a shared staging environment; tagged releases promote to production once smoke tests pass (planned). + +### 7.4 Environment Configuration + +- **Secrets Management**: Local development uses `.env` files; higher environments will source secrets from the cloud provider's vault service (e.g., AWS Secrets Manager) with runtime injection. +- **Database Migration**: Alembic migrations execute during deployment rollout to guarantee schema alignment before application start. +- **Feature Flags**: Environment-specific toggles (planned) will allow gradual rollout of simulation and multiplayer features. + +### 7.5 Observability and Operations + +- **Logging**: Structured JSON logs emitted from FastAPI are shipped to centralized storage (e.g., OpenSearch) via Fluent Bit sidecars (planned). +- **Metrics**: Prometheus exporters for application and database metrics inform Grafana dashboards tracking request rate, latency, and simulation throughput. +- **Alerting**: PagerDuty escalation policies will trigger on error budgets and availability SLO breaches once production traffic begins. ## 8. Concepts