Architecture Overview

Enterprise Architecture as Code (EAaC) is a framework for practicing enterprise architecture as a versioned, validated, code-like discipline rather than a collection of slide decks and wiki pages. At its center is a deterministic Python engine (ea-core) that owns every operation with a single correct answer — validation, scaffolding, graph computation, reporting, and guarded file operations. Around that core, AI agents supply only what genuinely requires judgment: conversational guidance, artifact authoring, and compliance reasoning.

The thesis: separate the parts that must be provably correct from the parts that require judgment, give the correct parts one host-agnostic home, and treat the body of architectural knowledge as data the system reads rather than logic it hardcodes. This addresses the three structural failures of EA practice — architecture living in unvalidatable prose, monolithic lock-in-prone tooling, and ungrounded AI assistance whose "the architecture is consistent" is a guess, not a proof.

The picture

            ┌──────────────────────────────────────────────────────────┐
            │                  CONTRACT CONSUMERS                       │
            │  Adapter surfaces host the judgment agents; the raw `ea`  │
            │  CLI is direct/reference use (no adapter, no judgment).   │
            │                                                          │
            │   Claude plugin      Antigravity        CI / direct CLI   │
            │   (adapter)          plugin (adapter)   (reference use)   │
            │        │                  │                  │            │
            └────────┼──────────────────┼──────────────────┼───────────┘
                     └────────┬─────────┴──────────────────┘
                                          │
                       Stable CLI contract │  JSON on stdout + exit codes
                          (versioned)      │  (the ONLY integration boundary)
                                          ▼
            ┌──────────────────────────────────────────────────────────┐
            │                      ea-core (Python ≥ 3.10)             │
            │   Deterministic, fully tested. No host/LLM knowledge.    │
            │                                                          │
            │   validate · scaffold/commit · graph · report ·          │
            │   materialize · promote · migrate · guarded file ops     │
            └───────┬──────────────────────────────────┬───────────────┘
                    │ reads                             │ reads/validates
                    ▼                                   ▼
        ┌───────────────────────┐     ┌────────────────────────────────┐
        │     Method Packs      │     │      Single source of truth    │
        │ artifact types,       │     │   Tailoring Manifest           │
        │ methods, rules (DATA, │     │   + typed Artifact Repository  │
        │ read at runtime)      │     │     Org scope + projects       │
        └───────────────────────┘     └────────────────────────────────┘

• Arrows point downward only (consumers → contract → core → data); the core never imports upward (P2).
• Judgment lives above the line (agents on surfaces); determinism lives below it (P1).
• Method Packs and the source of truth are data, read and validated by the core; agents read packs at runtime to know how to guide (P4, P8).
• The Artifact Repository is partitioned into an Org scope and projects with layered references (project → Org only); promotion moves a project artifact into Org under human-in-the-loop control (P3, P8).

Component responsibilities

Component	Owns	Must not
ea-core	Deterministic ops, schema validation, guarded file I/O, the CLI contract	Call LLMs; import adapters; keep authoritative state outside the source of truth
Surfaces / adapters	Surface I/O ↔ CLI translation; agent prompts (judgment)	Hold core business logic; bypass the contract
Agents (prompts)	Tailoring dialogue, artifact authoring, advisory synthesis, compliance reasoning	Hardcode artifact/method knowledge; write without user confirmation
Method Packs	Artifact types, methods, relationships, rules (as data)	Contain executable surface/core logic
Tailoring Manifest	Org configuration: domains, archetype provenance, settings, policies, overlays	Be mutated silently; hold a method-selection list
Artifact Repository	Typed EA artifacts, partitioned into an Org scope and projects	Contain artifacts that don't validate, or that belong to no scope
Org scope	The shared org-level architecture; promotion target	Reference into any project
Project	The work context scoping artifacts and operations; many coexist	Reference another project directly

Key domain concepts

• Method Pack — a distributable, versioned data library defining artifact types, methods (each a practice with ordered steps), relationships, and validation rules. Tailoring selects individual methods; the repo materializes only the selected methods and their required types/rules. (reference/packs.md)
• Tailoring Manifest — the one org-level configuration: domain structure and allowed types, archetype provenance, settings, governance policies, and the relationship/rename overlays. Exactly one per repository; projects do not tailor independently. (reference/manifest.md)
• Artifact Repository — the typed store of the organization's actual EA artifacts; every entry validates against the active types and Manifest constraints. (reference/repository.md)
• Scope — the partition an artifact belongs to: the single Org scope (shared, reusable architecture projects consume and contribute back to) or exactly one project (the context within which work happens). Operations run in the context of a named scope.
• Domain — a manifest-defined partition (business, data, …) into which artifact types are organized within every scope; org tailoring, not pack data — different organizations may place the same type in different domains. On disk: <scope>/<domain>/<type>/<id>.md.
• Archetype — a named preset representing a weight of practice (light → heavy). Organizations evolve between archetypes by configuration (a delta-preserving migration), not rebuild.
• Promotion — the governed flow by which a project artifact becomes org-level: a deterministic, reviewable, confirmed core operation keeping a single authoritative copy.
• Surface / adapter — a consumer of the CLI contract. The raw ea CLI is the contract's reference interface; an adapter surface (the Claude and Antigravity plugins) wraps it for a richer environment and hosts the judgment agents (ea-architect, ea-methodologist). (reference/surfaces.md)
• Agent — an LLM prompt living on a surface, responsible only for judgment and conversation; it reads Method Packs to know how to guide and proposes (never commits) changes.

Repository layout (this codebase)

src/ea_core/        # the deterministic engine + `ea` CLI
tests/              # unit + e2e contract tests (incl. per-feature e2e suites)
plugins/            # the two adapter surfaces (ea-claude, ea-antigravity)
packs/              # production method packs (open-agile-architecture,
                    #   enterprise-architecture, lean-ux, …)
presets/            # production archetype presets pairing with the packs
docs/               # this documentation
proposals/          # accepted design proposals

Non-goals (still binding)

• No graphical modeling UI — surfaces are conversational and CLI/CI consumers, not diagram editors.
• No hosted multi-tenant SaaS — the runtime is local/host-agnostic.
• No authoring intelligence inside the core — the core never calls an LLM; judgment lives only in agent prompts.
• No hosted pack registry — distribution rides git and files.
• No silent automation — no "smart defaults" applied without user acceptance.