Tech Story: Production documentation (README, deployment runbook, architecture, OAuth guide)

[GitAddRemote]

Tech Story

As a developer or operator, I want comprehensive production documentation so that anyone (including future-me) can understand how the system is deployed, how the auth flows work, and how to perform common operational tasks without needing to reverse-engineer the code.

Context

By the time this milestone is complete, Station will have a non-trivial production setup: Terraform-managed infra, Nginx reverse proxy, Docker Compose services, a CI/CD pipeline, Redis-backed auth, and OAuth M2M. None of this is obvious from the source code alone. Good documentation is what separates a portfolio project from a professional one.

Technical Elaboration

README.md (repo root) — update

Current README focuses on local development. Add a top-level Production section that links to the detail docs below. Also add:

• Architecture overview: what each service is and how they relate
• Subdomain map: api.drdnt.org → backend, station.drdnt.org → frontend, bot.drdnt.org → reserved
• Quick-reference: how to trigger a deploy (push a v* tag)
• Quick-reference: how to check service health on the VPS

docs/deployment.md — new

Full deployment runbook. Sections:

1. Prerequisites — Linode account, domain registrar access, GitHub secrets
2. First-time setup — step-by-step: Terraform apply → bootstrap VPS → Nginx + Certbot → set .env.production → first deploy
3. Routine deploys — tag and push; what GitHub Actions does; how to watch the workflow
4. Rollback — how to re-tag a previous version and push to trigger a rollback deploy
5. Secrets management — what secrets exist, where they live (VPS .env.production, GitHub Secrets), how to rotate them
6. Monitoring basics — docker compose ps, docker compose logs -f backend, free -h, df -h
7. Common issues — OOM: check free -h, consider adding swap or upgrading. Container crash loop: docker compose logs backend --tail=100. Cert expired: certbot renew.

docs/architecture.md — new

Plain-English architecture explanation with a text diagram:

Internet
   │
   ▼
Nginx (VPS host, port 80/443)
   ├── api.drdnt.org     ──► Station Backend (Docker, port 3001)
   │                              │
   │                         ┌───┴────────────────┐
   │                         │  PostgreSQL (Docker) │
   │                         │  Redis (Docker)      │
   │                         └────────────────────┘
   ├── station.drdnt.org ──► Station Frontend (Docker, port 3000)
   └── bot.drdnt.org     ──► (reserved / health endpoint)

Station Backend ◄──── Station-Bot (Linode VPS, separate Docker Compose)
                       OAuth 2.0 Client Credentials

Explain each component in 2–3 sentences. Link to the deployment and OAuth docs.

docs/oauth-m2m.md — new

The M2M auth flow explained for someone who hasn't worked with OAuth before:

1. What Client Credentials is and when to use it (vs user login)
2. The full request/response cycle with example curl commands
3. How Station-Bot uses it (token acquisition, caching, refresh, retry)
4. How to register a new OAuth client (admin endpoint, bcrypt secret)
5. How to revoke a client (set isActive: false in DB)
6. Security properties: short-lived tokens, JTI blacklist, bcrypt secrets

docs/cicd.md — new (referenced in #90)

• Pipeline diagram: tag push → GitHub Actions → GHCR → SSH → VPS → health check
• Required GitHub Secrets table (name, description, how to generate/rotate)
• How to manually re-run a failed deploy
• Monorepo CI: which workflows run on PRs vs tags

Definition of Done

• README.md updated with Production section and links to detail docs
• docs/deployment.md written covering first-time setup through rollback
• docs/architecture.md written with text diagram and plain-English explanations
• docs/oauth-m2m.md written with curl examples for the Client Credentials flow
• docs/cicd.md written with secrets table and pipeline diagram
• All docs reviewed for accuracy against the final implementation (not an earlier draft)
• No placeholder text ("TODO", "TBD") left in any doc

Dependencies

• Depends on: all other v0.2.0 issues (can only be finalized once implementation is complete)
• Blocks: nothing — docs are the last step before milestone close