Architecture as Code

Define, validate, visualize, and govern enterprise system architectures from declarative YAML.
A full-lifecycle platform with an interactive diagram editor, CLI toolchain, AI-native MCP server, OPA policy engine, Copilot Spaces integration, reference CI/CD pipeline, governance pipeline, and auto-published documentation site.

Why Architecture as Code?

Most organizations store architecture knowledge in slide decks and wiki pages that drift from reality within weeks. Architecture as Code treats architecture definitions as source code: version-controlled YAML files that are validated against schemas, linted for policy compliance, rendered into interactive diagrams, and automatically published -- all through a CI/CD pipeline.

The result is a single source of truth that stays in sync with the codebase, enforces enterprise standards, and makes architecture knowledge accessible to every engineer -- including AI coding agents.

Platform Overview

                                    Architecture as Code
    ┌──────────────────────────────────────────────────────────────────────────┐
    │                                                                          │
    │   YAML Sources         Toolchain              Outputs                    │
    │   ────────────         ─────────              ───────                    │
    │                                                                          │
    │   model/          ──>  CLI (aac)          ──> Interactive Diagram Editor │
    │   patterns/       ──>  MCP Server         ──> Published Documentation   │
    │   standards/      ──>  CI/CD Pipeline     ──> PlantUML + Draw.io Export │
    │   waivers/        ──>  JSON Schema + Zod  ──> PR Feedback (diagrams)    │
    │   schema/         ──>  OPA Policy Engine  ──> GitHub Pages              │
    │                   ──>  Ref CI Pipeline    ──> App Repo Validation       │
    │                                                                          │
    └──────────────────────────────────────────────────────────────────────────┘

Capability	Description
Interactive Diagram Editor	Bidirectional sync between a Monaco YAML editor and a React Flow canvas. Edit YAML and the diagram updates; drag a node and the YAML updates.
CLI Toolchain	`aac init`, `aac create`, `aac validate` -- scaffold projects, generate boilerplate, validate artifacts against live schemas with ETag caching.
MCP Server	Expose architecture data to AI coding agents via the Model Context Protocol. 10 resources, 3 tools, 2 guided prompts. Works with VS Code Copilot, Cursor, Claude Desktop.
Policy Engine	OPA Rego policies for enterprise governance: security (KMS encryption), integration (API gateway), and FinOps (autoscaling). Built-in test framework with 100% coverage target.
Context Driven Dev	GitHub Copilot Spaces for RAG-powered, context-grounded code generation. Domain-specific Spaces inject enterprise standards and patterns into the AI context window.
Continuous Integration	Reference GitHub Actions pipeline for app repos: schema validation, 5-rule compliance linter, 3 OPA policy checks, path-filtered triggers, and POSIX exit codes.
Pattern Catalog	6 reusable architecture patterns with C4 diagrams, NFR targets, cost profiles, and getting-started guides.
Standards Catalog	9 enterprise standards with RFC 2119 requirements, verification methods, and approved solutions.
Waiver Registry	10 architecture exceptions with risk assessments, compensating controls, financial impact, and remediation plans.
Governance Pipeline	9-job CI/CD pipeline: schema validation, 5-rule compliance linter, OPA policy checks, diagram generation, and auto-publish to GitHub Pages.

Live Site

https://aac.muthub.org/

Auto-published on every push to main. Includes system detail pages, pattern catalog, standards catalog, waiver registry, pipeline visualization, developer utilities, and executive scorecard.

Quick Start

Prerequisites

Node.js >= 22 (see .nvmrc)
npm >= 9

Install & Run

git clone https://github.com/muthub-ai/aac.git
cd aac
npm install
npm run dev

Open http://localhost:3000. The dashboard shows all systems, patterns, standards, waivers, and developer utilities.

CLI

npm install -g @muthub-ai/aac

aac init                                    # Scaffold project structure
aac create system "Order Management"        # Generate boilerplate YAML
aac validate model/ --type system           # Validate against live schemas
aac validate standards/ --output json       # JSON output for CI/CD

MCP Server (for AI Agents)

npm install -g @muthub-ai/aac-mcp-server

# Test with the MCP Inspector
npx @modelcontextprotocol/inspector aac-mcp -- --root /path/to/your/aac/repo

Or add to your IDE's MCP configuration (VS Code, Cursor, Claude Desktop):

{
  "mcpServers": {
    "aac": {
      "command": "aac-mcp",
      "args": ["--root", "/path/to/your/aac/repo"]
    }
  }
}

Policy Engine (OPA/Rego)

# Install OPA
brew install opa

# Run policy tests
cd packages/policies && npm test

# Check coverage
npm run test:coverage

# Build deployable bundle
npm run bundle

Context Driven Development (Copilot Spaces)

Two pre-configured Copilot Spaces provide context-grounded code generation:

Space	URL
Data & AI Architecture Standards	github.com/copilot/spaces/muthub-ai/2
Infrastructure Resilience Patterns	github.com/copilot/spaces/muthub-ai/1

Using the Copilot Space "Data & AI Architecture Standards",
write the Terraform for a compliant BigQuery data pipeline
with KMS encryption and model monitoring enabled.

MCP Server

The MCP server exposes enterprise architecture governance data to AI coding agents via the Model Context Protocol. It runs as a local subprocess over stdio, giving agents structured access to your architecture repository.

Resources (10 endpoints)

URI	Description
`aac://systems`	List all system models
`aac://systems/{id}`	Read a system's C4 YAML
`aac://standards`	List all architecture standards
`aac://standards/{filename}`	Read a standard's YAML
`aac://waivers`	List all waivers with status
`aac://waivers/active`	List only approved, non-expired waivers
`aac://waivers/{filename}`	Read a waiver's YAML
`aac://patterns`	List all architecture patterns
`aac://patterns/{id}`	Read a pattern's YAML
`aac://schemas/{type}`	Read the JSON Schema for a given artifact type

Tools

Tool	Description
`validate_architecture`	Validate YAML against JSON Schemas (auto-detects type)
`lint_compliance`	Run 5 enterprise policy rules against system models
`scaffold_waiver`	Generate a pre-filled waiver YAML from parameters

Prompts

Prompt	Description
`design_new_system`	Guided workflow to design a C4 model conforming to enterprise standards
`request_architecture_exception`	Generate a formal waiver request to bypass an architecture standard

CLI

The CLI validates architecture artifacts against live enterprise schemas hosted on GitHub, with ETag-based caching for offline support.

Command	Description
`aac init`	Scaffold `.aacrc` config + directory structure (`model/`, `patterns/`, `standards/`, `waivers/`, `schema/`)
`aac create <type> [name]`	Generate boilerplate YAML for `system`, `pattern`, `standard`, or `waiver`
`aac validate <path> [flags]`	Validate YAML against live JSON Schemas. Supports directories, type auto-inference, JSON output, and `--force-refresh`.

Exit codes: 0 success, 1 system error, 2 validation failed.

Policy Engine

Enterprise architecture governance policies written in Rego and enforced by the Open Policy Agent (OPA). Policies are unit-tested with OPA's built-in test framework and validated in CI on every pull request.

Policy Rules

Domain	Policy	Package	Severity
Security	Cryptography Key Management	`architecture.security`	High
Integration	API Gateway Routing	`architecture.integration`	High
FinOps	Cloud Workload Rightsizing	`architecture.finops`	Medium

CI Pipeline Commands

Step	Command	Description
Format	`opa fmt --fail .`	Strict Rego formatting compliance
Syntax	`opa check .`	Compile policies, catch unresolved variables
Test	`opa test -v ./rules/`	Run all `_test.rego` files (fails build on failure)
Coverage	`opa test --coverage ./rules/`	Measure test coverage (100% target)

Bundle Deployment

cd packages/policies && npm run bundle
# Produces: dist/policies.tar.gz
# Load with: opa run --server --bundle dist/policies.tar.gz

Context Driven Development

GitHub Copilot Spaces provide Retrieval-Augmented Generation (RAG) that injects your enterprise standards and patterns directly into the AI's context window. Instead of generating generic code, Copilot retrieves your approved patterns and schemas before responding -- producing compliant code by design.

How It Works

Continuous Indexing -- GitHub builds a semantic search index of attached repository folders. As standards merge to main, the index updates instantly.
Custom Instructions -- Each Space has a permanent system prompt constraining the AI to your enterprise context.
Contextual Grounding -- Copilot searches the indexed Space, retrieves exact YAML patterns, and appends them to the developer's prompt.

Domain Spaces

Space	Sources	URL
Data & AI Architecture Standards	ML governance, Gen AI usage, data platform standards + AI/ML patterns	muthub-ai/2
Infrastructure Resilience Patterns	Multi-region, cloud rightsizing, IaC, cryptography standards + API patterns	muthub-ai/1

IDE Integration

Configure the GitHub MCP server to access Spaces from VS Code or Cursor:

{
  "mcpServers": {
    "github": {
      "command": "gh",
      "args": ["copilot", "mcp-server"]
    }
  }
}

Architecture

Bidirectional Sync Flow

┌─────────────┐     updateFromYaml()     ┌─────────────────┐     applyDagreLayout()     ┌──────────────┐
│  Monaco      │ ──────────────────────>  │  Zustand Store   │ ─────────────────────────> │  React Flow  │
│  YAML Editor │                          │                   │                            │  Canvas      │
│              │ <──────────────────────  │  yamlText         │ <───────────────────────── │              │
└─────────────┘     updateFromCanvas()    │  nodes[]          │     onNodesChange()        └──────────────┘
                                          │  edges[]          │     onEdgesChange()
                                          │  syncSource       │     onConnect()
                                          └─────────────────┘

YAML -> Canvas: Edit YAML -> debounced parse -> yamlToGraph() -> Zod validation -> applyDagreLayout() -> render
Canvas -> YAML: Drag/connect nodes -> graphToYaml() -> update editor
Sync guard: syncSource flag prevents infinite update loops

C4 Model Hierarchy

Person (actor)
Software System
  └── Container
        └── Component
Deployment Node
  └── Infrastructure Node
        └── Container Instance

Each level maps to a custom React Flow node with C4-standard styling. Relationships are labeled edges with optional protocol annotations.

CI/CD Pipeline

9-job pipeline with 5 parallel domain stages:

                ┌─────────────────┐
                │   Lint & Test    │   ← Quality Gate (436 tests)
                └────────┬────────┘
     ┌───────────────────┼───────────────────┬──────────────┐
     │           ┌───────┼───────┐           │              │
     ▼           ▼       ▼       ▼           ▼              ▼
┌──────────┐ ┌────────┐ ┌─────────┐ ┌──────────┐ ┌──────────┐
│   App    │ │Patterns│ │Standards│ │ Waivers  │ │ Policies │
│Architect.│ │Catalog │ │ Catalog │ │ Registry │ │ OPA/Rego │
└────┬─────┘ └───┬────┘ └────┬────┘ └────┬─────┘ └────┬─────┘
     └────────────┼──────────┼───────────┼────────────┘
                ┌─▼──────────────┐
                │    Assemble     │   ← Merge Artifacts
                └────────┬────────┘
                ┌────────┴────────┐
                ▼                 ▼
         ┌────────────┐   ┌────────────┐
         │  PR Review  │   │  Publish   │   ← Deploy
         └────────────┘   └────────────┘

Compliance rules enforced:

No frontend container may connect directly to a database
Every internal system must define at least one container
No orphaned external systems
Deployment container references must resolve to defined containers
Every container must specify its technology

Project Structure

aac/
├── .github/workflows/aac-pipeline.yml     # 9-job CI/CD pipeline
├── .vscode/mcp.json                       # VS Code MCP server configuration
├── model/                                 # System architecture definitions (4 systems)
│   ├── demand-forecasting/
│   ├── ecommerce-platform/
│   ├── image-categorization/
│   └── ml-platform/
├── patterns/                              # Architecture pattern definitions (6 patterns)
├── standards/                             # Enterprise standards (9 YAML files)
├── waivers/                               # Architecture waivers (10 YAML files)
├── schema/                                # JSON Schema definitions (5 schemas)
├── cli/                                   # CLI package (@muthub-ai/aac)
│   ├── bin/aac.ts                         #   Entry point: init, create, validate
│   └── src/                               #   Schema manager, validators, templates
├── mcp-server/                            # MCP server package (@muthub-ai/aac-mcp-server)
│   ├── bin/aac-mcp.ts                     #   Entry point: stdio transport
│   └── src/
│       ├── lib/                           #   Core: repo-resolver, schema-loader, validator
│       ├── resources/                     #   10 resource endpoints
│       ├── tools/                         #   3 tool handlers
│       └── prompts/                       #   2 guided workflows
├── packages/policies/                     # OPA Rego policy engine
│   ├── rules/                             #   3 governance domains (security, integration, finops)
│   ├── data/                              #   Static enterprise reference data
│   └── scripts/                           #   Bundle build script
├── scripts/                               # Build & governance scripts (9 scripts)
├── src/
│   ├── app/                               # Next.js App Router (/, /dashboard, /systems/[id])
│   ├── components/                        # 40+ React components
│   │   ├── canvas/                        #   React Flow canvas
│   │   ├── dashboard/                     #   Catalogs, utilities, system cards
│   │   ├── editor/                        #   Monaco YAML editor
│   │   ├── landing/                       #   Landing page sections (10 sections)
│   │   ├── nodes/                         #   C4 node renderers (6 types)
│   │   └── ui/                            #   Shadcn primitives
│   ├── lib/                               # Pure logic modules
│   │   ├── parser/                        #   YAML <-> graph bidirectional conversion
│   │   ├── validation/                    #   Zod schemas + validation
│   │   ├── layout/                        #   Dagre auto-layout
│   │   ├── export/                        #   Draw.io XML + PlantUML
│   │   └── data/                          #   Pattern, CLI, MCP, Policy Engine data
│   ├── store/                             # Zustand store
│   └── types/                             # TypeScript types
└── build/                                 # Generated artifacts (gitignored)

Tech Stack

Layer	Technology
Framework	Next.js 16 (App Router, Turbopack)
UI	React 19, Tailwind CSS v4, Shadcn UI
Diagram Canvas	React Flow (`@xyflow/react`)
Code Editor	Monaco Editor
Graph Layout	Dagre
State	Zustand 5
Validation	Zod v4 + Ajv (JSON Schema draft-07 & 2020-12)
MCP	@modelcontextprotocol/sdk (stdio transport)
CLI	Commander.js, Chalk
Policy Engine	Open Policy Agent (Rego)
Context Driven Dev	GitHub Copilot Spaces (RAG)
Animation	Framer Motion
Testing	Vitest (436 tests across 24 suites)
Documentation	Custom static site generator, Asciidoctor.js
CI/CD	GitHub Actions, GitHub Pages
Runtime	Node.js 22, TypeScript 5 (`strict: true`, zero `any`)

Available Scripts

Script	Description
`npm run dev`	Start dev server with Turbopack HMR
`npm run build`	Production build
`npm run lint`	ESLint
`npm test`	Vitest watch mode
`npm run test:run`	Single test run (CI)
`npm run test:coverage`	Coverage report
`npm run validate:models`	Validate all YAML models against JSON Schema + Zod
`npm run validate:standards`	Validate standards against JSON Schema (draft 2020-12)
`npm run validate:waivers`	Validate waivers against JSON Schema (draft 2020-12)
`npm run lint:architecture`	Enterprise policy compliance checks (5 rules)
`npm run build:diagrams`	Generate PlantUML + Draw.io diagrams
`npm run build:docs`	Generate documentation site
`npm run build:patterns`	Generate pattern catalog pages
`npm run build:standards`	Generate standards catalog pages
`npm run build:waivers`	Generate waiver registry pages
`npm run policy:test`	Run OPA Rego policy unit tests
`npm run policy:fmt`	Check Rego formatting compliance

System Models

4 example architectures in model/:

System	Containers	Description
E-Commerce Platform	10	Full stack: web app, API gateway, database, payment, messaging
Demand Forecasting	7	ML-powered demand prediction with feature store and model serving
Image Categorization	3	Image classification with training and inference
ML Platform	2	Shared ML infrastructure with model registry

Adding a New System

Create model/my-system/metadata.json with system metadata
Create model/my-system/system.yaml following the C4 YAML schema
Restart dev server -- the system appears in the dashboard and will be validated by CI on the next push

Or use the CLI:

aac create system "Order Management"

Testing

436 tests across 24 suites:

Area	Suites	Tests	Scope
App (`src/lib/`)	15	358	Parser, validation, layout, export, graph filtering, utilities, policy engine data, copilot spaces data, CI pipeline data
CLI (`cli/src/`)	6	52	Commands (init, create, validate), schema manager, config, logger
MCP Server (`mcp-server/src/`)	3	26	Schema loader, validator (AJV + draft-2020-12), repo resolver

npm run test:run                  # All 436 tests
cd mcp-server && npm test         # MCP server tests only

Landing Page

The homepage (/) renders 10 data-driven sections:

Section	Description
Hero	Animated counters for systems, patterns, standards, waivers + secondary stats (LoC, deployable units, repos, utilities)
Executive Scorecard	6 KPI gauge cards: compliance, risk, debt, remediation velocity, pattern reuse, cloud spend
Risk & Compliance	Risk heat map by domain + standards coverage
Portfolio Summary	Systems inventory table, pattern maturity bar chart, waiver lifecycle funnel
Why AaC	6 value-proposition cards explaining the Architecture as Code approach
Operational Lifecycle	5-step horizontal/vertical timeline: Define, Build, Test, Accept, Deploy
Operational Health	4 engineering quality metrics with sparkline trends
CI/CD Pipeline	Interactive DAG visualization of the 9-job governance pipeline
Developer Utilities	6 utility cards (CLI, AI Agent, MCP Server, Policy Engine, Context Driven Dev, CI Pipeline)
Footer	Anchor links to all sections + dashboard links

Dashboard

The Next.js dashboard at /dashboard provides 5 tabs:

Tab	Content
Application Catalog	System cards with container counts, links to interactive diagram editor
Pattern Catalog	6 patterns with search, category filters, and detail drawer
Standards Catalog	9 standards with domain tags and compliance status
Waiver Registry	10 waivers with risk severity badges and lifecycle status
Utilities	CLI documentation, MCP Server documentation, Policy Engine documentation, Context Driven Dev documentation, Continuous Integration reference pipeline, and upcoming tools

Routes

Route	Description
`/`	Landing page
`/dashboard`	System catalog with tabbed navigation
`/dashboard?tab=patterns`	Pattern catalog
`/dashboard?tab=standards`	Standards catalog
`/dashboard?tab=waivers`	Waiver registry
`/dashboard?tab=utilities`	Developer utilities (CLI, MCP Server, Policy Engine, Context Driven Dev, CI Pipeline)
`/systems/:id`	Interactive diagram editor

Acknowledgements

C4 Model by Simon Brown
Model Context Protocol by Anthropic
Open Policy Agent by the CNCF
GitHub Copilot Spaces for context-driven development
React Flow for the interactive canvas
Shadcn UI for accessible component primitives

License

This project is licensed under the MIT License.

Name		Name	Last commit message	Last commit date
Latest commit History 67 Commits
.github/workflows		.github/workflows
.vscode		.vscode
cli		cli
data		data
docs		docs
mcp-server		mcp-server
model		model
packages/policies		packages/policies
patterns		patterns
public		public
schema		schema
scripts		scripts
src		src
standards		standards
waivers		waivers
.gitignore		.gitignore
.nvmrc		.nvmrc
AGENTS.md		AGENTS.md
LICENSE		LICENSE
README.md		README.md
components.json		components.json
eslint.config.mjs		eslint.config.mjs
next.config.ts		next.config.ts
package-lock.json		package-lock.json
package.json		package.json
postcss.config.mjs		postcss.config.mjs
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts

Folders and files

Latest commit

History

Repository files navigation

Architecture as Code

Why Architecture as Code?

Platform Overview

Live Site

Quick Start

Prerequisites

Install & Run

CLI

MCP Server (for AI Agents)

Policy Engine (OPA/Rego)

Context Driven Development (Copilot Spaces)

MCP Server

Resources (10 endpoints)

Tools

Prompts

CLI

Policy Engine

Policy Rules

CI Pipeline Commands

Bundle Deployment

Context Driven Development

How It Works

Domain Spaces

IDE Integration

Architecture

Bidirectional Sync Flow

C4 Model Hierarchy

CI/CD Pipeline

Project Structure

Tech Stack

Available Scripts

System Models

Adding a New System

Testing

Landing Page

Dashboard

Routes

Acknowledgements

License

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 1

Contributors

Uh oh!

Languages