# Enterprise Architecture > Unified enterprise & software architecture skill grounded in four open-source standards — C4 + Structurizr DSL, ArchiMate 3.x, TOGAF ADM, and arc42 + ADRs (MADR). Use it whenever the user wants to: produce architecture diagrams as code (C4 context/container/component, Structurizr, PlantUML, Mermaid); write architecture docs or decision records (arc42, ADRs/MADRs, design docs); review or assess a design against quality attributes and EA principles; or model an enterprise (capabilities → applications → technology, app landscapes, portfolio rationalization). Trigger it even when no framework is named — e.g. "draw the architecture of this service", "give me a container diagram", "write an ADR for choosing Kafka", "is this design sound?", "map our capabilities to apps", "document my architecture in arc42", "create an HLD or LLD", "assess this design against ISO 25010 / quality attributes", "produce a solution design". Do NOT trigger it for writing application code or REST endpoints, IaC / cloud deployment (Terrafo - Skill: `gauravs19/enterprise-architecture` (Agent Skill, multi-file: 6 files) - Install (CLI): `npx skillmds@latest add gauravs19/enterprise-architecture` - Raw SKILL.md: https://api.skillmd.com/api/skills/gauravs19/enterprise-architecture/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Web & Frontend - Author: gauravs19 (https://skillmd.com/u/gauravs19) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/gauravs19/enterprise-architecture --- # Enterprise Architecture A practical toolkit for doing real architecture work the way open-source EA standards intend it — diagrams as code, documentation as code, decisions as records, and a single traceable model underneath. It unifies four complementary frameworks so you reach for the right tool at the right altitude instead of forcing everything into one notation. ## The mental model: four frameworks, four altitudes These frameworks are not competitors — they answer different questions. Knowing which one fits the question is most of the skill. | Framework | Question it answers | Altitude | When to reach for it | |---|---|---|---| | **C4 model** | "How is *this software system* structured?" | System → code | A single system/service: context, containers, components | | **ArchiMate** | "How does the *whole enterprise* hang together?" | Business → app → tech | Capabilities, app landscapes, cross-system flows | | **TOGAF ADM** | "How do we *deliver* an architecture change?" | Process/governance | Running an architecture engagement end-to-end | | **arc42 + ADRs** | "How do we *write it down* so others understand & decisions stick?" | Documentation | Documenting a system; recording a decision | A useful rule of thumb: **C4 zooms into one system, ArchiMate zooms out to the enterprise, TOGAF is the *method* for changing it, and arc42/ADR is how you *narrate* it.** They compose: an arc42 doc embeds C4 diagrams and links ADRs; a TOGAF engagement produces ArchiMate models and ADRs as deliverables. ## How to use this skill 1. **Pick the mode** (below) from what the user is asking for. If ambiguous, ask one short clarifying question rather than guessing — architecture work is expensive to redo. If the question is *which framework / how should we approach this* rather than a request for an artifact ("is TOGAF worth it?", "Zachman vs TOGAF?", "how do we structure this effort?"), read `references/choosing-frameworks.md` and answer with a grounded recommendation that routes into the right mode. 2. **Read the matching reference file(s)** in `references/` before producing output. They contain the real notation, element catalogs, templates, and gotchas. Do not work from memory of the standards — load the reference so the output is correct and idiomatic. 3. **Produce diagrams/docs as code**, default to text formats that live in Git and render anywhere. Save artifacts to files when the user has a repo/workspace; otherwise emit inline. 4. **Keep one source of truth.** When elements recur across diagrams/docs, give them stable IDs and reuse them (see *Traceability* below). Don't redraw the same box with a different name in two places. ## The four modes ### Mode 1 — Diagram (diagrams as code) *Triggers: "draw / diagram / visualize the architecture", "C4 container diagram", "Structurizr workspace", "show the components".* - For a **single software system**, use **C4** → read `references/c4-structurizr.md`. - Default output: **Structurizr DSL** when the user wants a reusable model that generates multiple views; **Mermaid** when they want something that renders inline immediately (chat, GitHub, Markdown docs); **PlantUML (C4-PlantUML)** when they're already in a PlantUML/Kroki toolchain. - Produce views in order of altitude: System Context → Container → Component (→ Code only if explicitly asked; it's usually noise). Stop at the level that answers the question. - For **cross-system / enterprise** views, use **ArchiMate** → read `references/archimate.md`. - Respect good-diagram hygiene from the reference: 5–20 elements per view, every external dependency shown, consistent naming, a title and a legend. ### Mode 2 — Document (docs & decisions as code) *Triggers: "document this system", "write an ADR / decision record", "arc42 docs", "design doc / RFC for X".* - **Whole-system documentation** → arc42. Read `references/arc42.md`. Use the discover → generate → validate loop and the detail-level knob (LEAN / ESSENTIAL / THOROUGH) so you write the right amount, not a 40-page tome nobody reads. - **A single decision** → ADR/MADR. Read `references/adr-madr.md`. Capture the context and the *options considered with trade-offs*, not just the chosen answer — the value of an ADR is the reasoning a future reader can't reconstruct. - Embed diagrams (Mode 1) rather than describing visuals in prose. Link ADRs from the relevant arc42 section (§9 Decisions). ### Mode 3 — Review / assess *Triggers: "review my architecture", "is this design sound?", "assess this against best practice", "what are the risks in this design?".* - Read `references/review-rubric.md`. Assess against **quality attributes** (the ISO/IEC 25010 set: performance, security, reliability, maintainability, etc.) and EA principles, not personal taste. - Output **severity-categorized findings** (Critical / Major / Minor / Suggestion), each with *evidence* and a *concrete remediation*, then a **verdict** (Approved / Approved-with-changes / Needs-revision). Avoid vague praise; an unhelpful "looks good" is worse than nothing. - Where a finding implies a fix, hand off to the right mode (e.g. "record this as an ADR", "redraw the container diagram to show the queue"). ### Mode 4 — Model the enterprise *Triggers: "map our business capabilities", "application landscape", "capability → app → technology", "enterprise architecture model", "rationalize our app portfolio".* - This is the big-picture mode. Use **ArchiMate** for the model (`references/archimate.md`) and **TOGAF ADM** for the method/structure of the engagement (`references/togaf-adm.md`). - Work top-down through the layers: **Strategy/Motivation → Business (capabilities, processes, services) → Application (apps, services, data) → Technology (nodes, platforms)**, then draw the *realization* links between layers (which app realizes which capability; which node hosts which app). The cross-layer links are the whole point — a capability map with no realization links is just a list. - For portfolio rationalization, add a TIME / quality assessment per application (Tolerate / Invest / Migrate / Eliminate) — see the TOGAF reference. ## Traceability — keep one model under everything Give every architectural element a **stable, human-readable ID** and reuse it across diagrams, docs, and ADRs. This is what turns a pile of pictures into an actual model. - Recommended ID scheme (URN-style): `ea:{org}:{system}:{kind}:{name}` - e.g. `ea:acme:checkout:container:payment-api`, `ea:acme:enterprise:capability:billing` - `kind` ∈ person, system, external, container, component, capability, app, node, decision … - When a repo/workspace exists, persist these in an `architecture/` folder (one file per significant artifact, or a Structurizr workspace as the model-of-record) so they're diff-able and greppable. Reference the same ID from the arc42 doc and the ADRs. - Before inventing a new element, check whether it already exists under another name and reuse the ID. Two names for one thing is the most common EA documentation defect. ## Validation After generating diagrams or docs, sanity-check them. For cross-artifact consistency (IDs referenced but never defined, building blocks named in prose but missing from diagrams, quality goals with no scenario, ADRs not linked from any doc), run: ``` python scripts/ea_lint.py ``` It reports issues grouped by severity. Treat its output as advisory review feedback, not a hard gate — explain findings to the user rather than silently "fixing" their intent. ## Output conventions - **Diagrams**: fenced code blocks with the right language tag (` ```mermaid `, ` ```plantuml `, or Structurizr DSL in ` ```text `/a `.dsl` file). One view per block, each with a one-line caption stating what it shows and for whom. - **Docs**: Markdown, headings matching the standard's section structure. Diagrams as separate `.puml`/`.dsl` files referenced from the doc when a repo exists; inlined otherwise. - **Always state which framework and view** you're producing, so the user learns the map. Part of this skill's job is to make the user fluent in the frameworks, not just hand them artifacts. ## Reference files (load as needed) | File | Load when | |---|---| | `references/c4-structurizr.md` | Any C4 diagram; Structurizr DSL; Mermaid/PlantUML C4 | | `references/archimate.md` | ArchiMate views; enterprise/cross-system modeling (Modes 1 & 4) | | `references/togaf-adm.md` | Running/structuring an architecture engagement; portfolio (Mode 4) | | `references/arc42.md` | Whole-system documentation (Mode 2) | | `references/adr-madr.md` | Writing a decision record (Mode 2) | | `references/review-rubric.md` | Reviewing/assessing an architecture (Mode 3) | | `references/choosing-frameworks.md` | "Which framework should I use?", framework comparisons, EA-approach strategy questions | Templates live in `assets/templates/`; the consistency linter in `scripts/ea_lint.py`.