Skip to content

Architecture Docs Update

Context

The architecture section has 5 draw.io source files and references 5 PNGs that have never been generated locally. The diagrams were created in March 2026 (PR #93) but never updated to reflect major changes since then:

  • PostgreSQL Flexible Server added (PRs #178–#184)
  • MkDocs docs service added to docker-compose + deployed via SWA (PR #195)
  • CV generation pipeline (publishpipe + Bun, PR #183)
  • Cost dashboard (weekly workflow, PR #190/#196)
  • CI consolidated to test.yml + coverage-doc job (PRs #194–#196)

In addition, no C4 Level 3 (Component) diagrams exist yet.

Source Files

File Diagram Referenced in
docs/assets/architecture.drawio Full system overview architecture/overview.md
docs/assets/c4-context.drawio C4 Level 1 — System Context architecture/index.md
docs/assets/c4-container.drawio C4 Level 2 — Container architecture/index.md
docs/assets/c4-component-frontend.drawio C4 Level 3 — Frontend SPA architecture/frontend.md (new)
docs/assets/c4-component-backend.drawio C4 Level 3 — API Backend architecture/backend.md (new)
docs/assets/c4-component-docs.drawio C4 Level 3 — Docs Service architecture/index.md (new)
docs/assets/deployment.drawio UML Deployment architecture/index.md
docs/assets/azure-cloud.drawio Azure resource layout architecture/index.md

Section 1 — System Overview & C4 Context / Container (Levels 1–2)

1a. architecture.drawio — Full system overview

  • Add PostgreSQL Flexible Server (prod only, dna-prod-portfolio-we-psql-fs)
  • Add MkDocs docs container as a separate container in the SWA box
  • Add CV generation path: GitHub Actions → Bun → cv/dist/ → frontend /public/
  • Add Cost Report workflow arrow: GitHub Actions → Cost Management API → docs commit
  • Verify CI/CD pipeline section reflects consolidated test.yml, deploy-docs, deploy-application

1b. c4-context.drawio — System Context (C4 L1)

  • Add Azure Cost Management as an external system (queried by cost-report workflow)
  • Verify GitHub Actions, Gmail SMTP, Entra ID still accurate
  • No major structural changes needed

1c. c4-container.drawio — Container (C4 L2)

  • Add PostgreSQL container (prod) as a new container
  • Add MkDocs Documentation container explicitly (currently may be missing or grouped)
  • Add CV Worker (GitHub Actions job, not a running container but worth noting)
  • Update nginx proxy note: now also serves locally from docker-compose

Section 2 — C4 Component Diagrams (Level 3)

The C4 model Level 3 zooms into a single container to show its internal components. Create one diagram per container that has interesting internal structure. See c4model.com/abstractions/component for notation guidance.

2a. c4-component-frontend.drawio — React SPA Components (NEW)

Zoom into the Frontend SPA container. Components to show:

Component Technology Responsibility
Navigation React + Wouter Top-level routing, Docs external link
HeroSection React Landing page hero
HowItsMadeSection React Tech stack showcase, links to docs
ContactForm React + React Query Calls POST /api/contact; validation, error UX
CVDownloadButton React Calls GET /api/download-cv; triggers PDF
API Client (shared) openapi-fetch Type-safe HTTP against shared/api.types.ts
Vite Build (build-time) Vite + esbuild Bakes VITE_DOCS_URL, outputs dist/public/
nginx proxy nginx Serves SPA, proxies /api/* to backend

2b. c4-component-backend.drawio — FastAPI Backend Components (NEW)

Zoom into the API Backend container. Components to show:

Component Technology Responsibility
ContactRouter FastAPI router POST /api/contact → Gmail SMTP
CVRouter FastAPI router GET /api/download-cv, /api/cv/generate
AdminRouter FastAPI router POST /api/admin/* bearer-token guarded
HealthRouter FastAPI router /health (probe), /api/health (public)
Database Layer SQLAlchemy async Async engine, session factory
Alembic migrations Alembic Schema versioning, env.py fallback for tests
Settings pydantic-settings Env vars: EMAIL_*, DATABASE_URL, MI flag
Managed Identity auth azure-identity DefaultAzureCredential → asyncpg token refresh

2c. c4-component-docs.drawio — MkDocs Documentation Service (NEW)

Zoom into the MkDocs Docs container. Components to show:

Component Technology Responsibility
MkDocs build engine MkDocs + Material Renders Markdown → static HTML
draw.io export step drawio-desktop / CI Converts .drawio → .png before mkdocs build
Plotly loader plotly-loader.js Deferred CDN inject; re-evals newPlot scripts
Cost dashboard page Plotly + Markdown Renders Azure cost charts from generated MD
Coverage report page Python script Auto-committed by coverage-doc job on each PR
SWA routing staticwebapp.config.json Auth rules, AAD login, allowed roles

Section 3 — Infrastructure / Deployment Views

3a. deployment.drawio — UML Deployment

  • Add PostgreSQL Flexible Server node under Azure prod resource group
  • Add portfolio-docs container (MkDocs, port 8080) to local stack section (if present)
  • Add Key Vault secret for DATABASE_URL

3b. azure-cloud.drawio — Azure resource layout

  • Add PostgreSQL Flexible Server to prod resource group box
  • Add Cost Management as a service being queried (subscription scope)
  • Verify dev RG vs prod RG layout still accurate

Section 4 — Docs Text Updates

After diagram updates, update the written sections:

File Update needed
architecture/overview.md Add PostgreSQL to component table; update deployment pipeline flow
architecture/index.md Update container table (add PostgreSQL, MkDocs); add component diagrams; update deployment details
architecture/backend.md Add component diagram; database section: SQLAlchemy async, Alembic, AAD-only auth, MI connection
architecture/frontend.md Add component diagram; VITE_DOCS_URL build arg; note docs service in local stack

Implementation Order

  1. Open each existing .drawio file in draw.io desktop and apply updates from Sections 1 and 3
  2. Create the three new c4-component-*.drawio files (Section 2) in draw.io desktop
  3. Once export_drawio_docker.sh is working, restart docs container → PNGs auto-generated
  4. Update the written sections in the 4 doc files (Section 4); add component diagram <img> tags
  5. Open PR with drawio + doc text changes (CI auto-exports PNGs in deploy-docs workflow)

Not in Scope

  • ADRs (separate PRs as decisions are made)
  • CI/CD workflow diagrams (covered by docs/ci/ pages)
  • Cost dashboard page (already up to date)