# Inside an Architecture-as-Code platform: a working example By Muthukrishnan (Muthu) Bommiah · Governed AI · Jun 9, 2026 > A tour of aac.muthub.org, the open prototype I built to show architecture as a control plane, and the design choices that mattered most: catalogs, executable guardrails, waivers as data, a computed scorecard and an MCP server for coding agents. **Architecture-as-Code is easiest to understand when you can click through one, so I built one.** [aac.muthub.org](https://aac.muthub.org) is a working prototype of an architecture control plane: enterprise architecture expressed as machine-readable, version-controlled artifacts that drive delivery, risk and cost decisions. It runs on a fictional sample portfolio, not anyone's real systems, but every part of it works. Building it taught me more than writing about it did. Some design choices that looked minor turned out to carry the whole thing, and a few things I expected to be hard were easy. This is a tour of what is there and why. ## Four catalogs as the source of truth - **Application systems:** a browsable catalog of systems, their containers and deployable units, and a disposition for each (invest, tolerate, migrate, eliminate). - **Patterns:** reusable reference architectures with maturity levels from draft to production-ready. - **Standards:** enterprise standards and guardrails, each broken into testable requirements, across security, data, integration, identity, infrastructure, DevOps, FinOps and AI/ML. - **Waivers:** architecture exceptions as first-class records with risk, expiry and remediation tracking, so an exception is a decision with an owner rather than a forgotten email. The system catalog borrows its vocabulary from Simon Brown's [C4 model](https://c4model.com/), which describes software in four levels: system context, container, component and code. I chose C4 because engineers already recognize it. The important decision was to treat the diagram as a *view* of the data, generated from the catalog, and never as the source. The moment a diagram becomes the thing people edit, it starts drifting from reality. ## Waivers were the feature that mattered most I expected the policy engine to be the heart of the platform. It turned out to be the waiver registry. In every large enterprise I have worked in, the real architecture is the set of standards *minus* the exceptions nobody can find. If exceptions live in email, the conformance number is fiction. So a waiver in the prototype is data, versioned in Git next to everything else. A simplified illustration of the shape: ```yaml waiver: id: WVR-0007 standard: SEC-ENC-01 # encryption at rest with managed keys system: sample-payments-api risk: high owner: platform-lead expires: 2026-12-31 remediation: migrate to managed KMS keys before expiry approved_by: architecture-board ``` Two fields do most of the work: `owner` and `expires`. An exception with a named owner and a date is a managed risk. An exception without them is a permanent hole that someone will rediscover during an audit. Once waivers are data, the policy engine can honor them automatically and stop honoring them the day they expire. It also lets you report exception debt the same way you report technical debt. ## An operational lifecycle, not a review meeting Architecture moves through the same lifecycle as code. **Define** the design from requirements. **Build** the artifacts for standards, archetypes and components in an IDE or visual tool, with local validation. **Test** them with schema validation and unit tests in CI. **Accept** them through automated compliance checks that also generate the Markdown and diagrams, gated by a pull request. **Deploy** by publishing the approved architecture to policy-as-code pipelines and the enterprise catalog. The pull request is the review board now. A human architect still approves, but the approval happens on a diff with test results attached, not on a slide deck. Nygard's case for [small, modular decision records](https://www.cognitect.com/blog/2011/11/15/documenting-architecture-decisions) applies directly: decisions live next to the artifacts they shape, so the reasoning travels with the change. ## Six principles behind it 1. **Machine-readable and version-controlled:** YAML, JSON or C4/Structurizr models in Git, with clear ownership and an audit trail. 2. **Executable guardrails:** policies run in CI/CD with a clear pass or fail. 3. **Model-to-runtime parity:** continuously compare the as-designed model with the as-built infrastructure to catch drift. 4. **Shift-left governance:** block non-compliant releases before they reach production. 5. **Decisions as code:** architecture decision records live next to the code, preserving the why. 6. **Human oversight plus automation:** people make the judgment calls; automation handles repeatability and scale. If I had to rank them, parity is the hardest and the most underrated. Writing rules is straightforward. Proving that what runs in production still matches the model requires reading real infrastructure state, and that is where most programs quietly stop. My advice is to begin parity with one high-value check, such as confirming that every deployed data store matches its declared data classification, and expand from there. ## Governance leaders can actually read Because the architecture is data, the platform computes an executive scorecard straight from the artifacts: standards conformance, risk posture, technical-debt exposure, remediation velocity, pattern reuse and cloud spend at risk, plus a risk heat map by domain. In the sample portfolio, conformance reads 33% with five active waivers. Those figures are invented for the demo, so ignore the values. The point is that nobody assembled a slide. The numbers are a query, and they change when a pull request merges. That shift changes the conversation with executives. Instead of debating whether a status report is accurate, the discussion moves to which waivers to retire first and which standards are generating the most exceptions. A standard that attracts many waivers is often a bad standard, and the data tells you so. ## Where a prototype stops and a program starts A prototype on a fictional portfolio proves the mechanics. It does not prove that an enterprise can run it, and I want to be honest about the gap, because it is where most Architecture-as-Code efforts stall. The first gap is the catalog itself. In the prototype every system record is complete because I wrote them. In a real enterprise the inventory is partial, duplicated across tools and owned by nobody in particular. My rule is to never import a catalog wholesale. Seed it from the systems that change most often, require an owner for every record, and let the policy checks expose missing data. A check that fails because the classification field is blank is doing useful work. The second gap is trust in the rules. A policy that produces false positives in its first month loses its audience for a year. Run every new rule in report-only mode first, publish the results, and switch it to blocking only after the owning teams agree the findings are real. The third is ownership of the platform. Someone has to maintain the schemas, review rule changes and keep the MCP server current as standards change. If that work is a side project for an architecture team already in review meetings all week, the control plane decays into another stale repository. Fund it as a product, with a small team and a backlog, or do not start. ## Putting the rules where code is written The developer utilities are where it becomes practical. A command-line tool validates and scaffolds artifacts (`aac init`). An **MCP server** built on the open [Model Context Protocol](https://modelcontextprotocol.io/introduction) lets IDEs and AI assistants read system models, standards, waivers and patterns, validate YAML against enterprise schemas and run compliance rules. A **policy engine** written in Rego for [Open Policy Agent](https://www.openpolicyagent.org/docs) enforces security, integration and FinOps policies with its own test suite. **Context-driven development** grounds Copilot code generation in approved standards and patterns. A reference GitHub Actions pipeline runs schema validation, the compliance rules and three OPA checks (KMS encryption, autoscaling and API gateway) on every pull request. I deliberately started small: five compliance rules in the MCP server and three OPA checks in the pipeline. A handful of rules that everyone trusts beats a hundred that generate noise. Next on the roadmap is an AI review agent that also handles natural-language-to-YAML authoring and drift detection, and *aac2iac*, which turns architecture models into Terraform, OpenTofu, CloudFormation or Pulumi. **What to do Monday** - Open the prototype at aac.muthub.org with your lead architect and list which of the four catalogs your enterprise could seed from existing data. - Export every open architecture exception you can find into one versioned file with owner and expiry fields, and count how many lack either. - Choose **three** enterprise standards and write each as a testable requirement that a pipeline could check with a clear pass or fail. - Name an owner and a small team for the architecture control plane before writing any policy code. If you lead architecture in a regulated enterprise, I am curious: which would you build first, the waiver registry or the policy engine? **Bottom line:** Architecture-as-Code is not a document format. It is a control plane: catalogs as truth, policies as tests, waivers as owned and dated decisions, and an MCP server so the AI writing your code knows the rules before it starts. *Based on my public prototype at aac.muthub.org and my LinkedIn post of May 2, 2026.* --- Muthukrishnan (Muthu) Bommiah · https://muthub.org · Views are my own and do not represent my employer.