WIP

docs/system-design.md

@@ -0,0 +1,59 @@
+# System Design — QA Physical Architecture
+
+Physical deployment topology for the QA environment. Source: `deploy/qa/docker-compose.qa.yml`, `scripts/ci/*.sh`, `.github/workflows/ci.yml`.
+
+```mermaid
+flowchart TB
+    subgraph CI["Self-hosted CI runner (qa)"]
+        Pipeline["deploy-qa.sh / smoke-qa.sh"]
+    end
+
+    subgraph Registry["Gitea Container Registry"]
+        ApiImage["miccheck-api:qa"]
+        AdminImage["miccheck-admin:qa"]
+    end
+
+    subgraph QAHost["QA Docker host — network: miccheck-qa-net (bridge)"]
+        subgraph AdminC["admin container<br/>nginx:1.27-alpine"]
+            Nginx["nginx<br/>serves Vue SPA<br/>proxies /api/, /health"]
+        end
+
+        subgraph ApiC["api container<br/>aspnet:10.0"]
+            Api["MicCheck.Api<br/>ASPNETCORE_URLS=http://+:8080"]
+        end
+
+        subgraph DbC["db container<br/>postgres:16-alpine"]
+            Db[("miccheck DB")]
+        end
+    end
+
+    Browser["Browser / QA tester"]
+
+    Pipeline -->|docker build/push| Registry
+    Registry -->|pull :qa| AdminC
+    Registry -->|pull :qa| ApiC
+
+    Browser -->|":3001 (QA_ADMIN_PORT)"| Nginx
+    Nginx -->|"http://api:8080 (internal)"| Api
+    Api -->|"Host=db;5432 (internal)"| Db
+
+    Pipeline -.->|"127.0.0.1:55432 (bridge-gateway bound)"| Db
+```
+
+## Components
+
+| Component | Image | Exposure | Notes |
+|---|---|---|---|
+| `admin` | `nginx:1.27-alpine` (built from `src/admin/Dockerfile.ci`, `node:22-alpine` build stage) | `${QA_ADMIN_PORT:-3001}:80` published on host | Serves Vue/Vite SPA; nginx (`src/admin/nginx.conf`) reverse-proxies `/api/` and `/health` to `api:8080` |
+| `api` | `mcr.microsoft.com/dotnet/aspnet:10.0` (built from `src/api/MicCheck.Api/Dockerfile.ci`, `sdk:10.0` build stage) | no published host port — internal only, reached via `admin`'s nginx proxy | `ASPNETCORE_URLS=http://+:8080`; JWT config (`Jwt__SecretKey`/`Issuer=MicCheck`/`Audience=MicCheck`) from `JWT_SECRET_KEY` secret; healthcheck `curl localhost:8080/health` |
+| `db` | `postgres:16-alpine` | `${DB_BIND_HOST:-127.0.0.1}:55432 → 5432`, bound to docker bridge gateway IP (not `0.0.0.0`) — reachable only from sibling CI containers, not off-box | DB `miccheck`, user `miccheck`, password from `POSTGRES_PASSWORD` secret; volume `miccheck-qa-pgdata` |
+
+All three services run on an isolated bridge network `miccheck-qa-net` (project `miccheck-qa`), separate from the local dev Aspire stack.
+
+## Deploy flow
+
+1. `build-and-push` job builds `api` and `admin` images, tags with git SHA and `qa`, pushes to Gitea registry as `$REGISTRY/$REGISTRY_OWNER/miccheck-api` / `miccheck-admin`.
+2. `deploy-qa` job (self-hosted runner, `main` branch only) pulls `:qa` images and runs `docker-compose.qa.yml` via `deploy-qa.sh`.
+3. `smoke-qa` job hits the deployed stack (`smoke-qa.sh`) to verify health.
+
+Secrets used: `REGISTRY`, `REGISTRY_OWNER`, `REGISTRY_USER`, `REGISTRY_TOKEN`, `JWT_SECRET_KEY`, `POSTGRES_PASSWORD`. Vars: `QA_ADMIN_PORT`.