Skip to main content

Living architecture diagrams as delivery docs

· 2 min read
Mike Homol
Mike Homol
Principal Consultant @ ThreeWill

Architecture slides go stale the week after the kickoff. On a state licensing modernization engagement this week, I codified living Azure and solution architecture diagrams under docs/ so the pictures sit next to the IaC and API work that actually change them.

What happened​

  • Added living Azure and solution architecture diagrams under in-repo docs/ (versioned with the delivery monorepo, not a one-off PowerPoint)
  • Status labels on each layer — Exists, Placeholder, Provisioned, Scripted, Planned — so the diagram stays honest as the scaffold grows
  • Teammates continued the same repo spine: Azure SQL IaC hardening, Key Vault and Blob in infrastructure, .NET 8 API scaffold with health checks and CI, and app-folder rename toward an internal web surface (collaborative delivery — not sole Mike authorship)
  • Documented a GitHub Enterprise cutover / brand alignment note for the engagement repo so clone URLs and naming stay honest for the team
  • Pattern worth stealing on other ThreeWill builds: diagrams as first-class docs, updated in the same PRs as infra and API changes

Sanitized solution-layers excerpt​

Client names, product codenames, and org remotes stripped. Same shape as the living docs/ diagram:

API-first and location-driven: one Azure SQL system of record, one shared API, three clients (internal SPA, external portal, offline field app). When a layer moves from Placeholder to Exists, the diagram updates in the same change as the code.