The frameworks, explained properly.

This guide does two things: first the theory in full — each framework in detail: origin, structure, core concepts, what it produces — then the practice: which parts earn their keep, where frameworks pay off, and four worked case studies. Because before judging what's ceremony and what's value, you need to know what each framework actually contains.

ZF
Zachman Framework
John Zachman · IBM, 1987 · an ontology, not a method

The oldest EA framework, born from a 1987 IBM Systems Journal paper. Zachman observed that complex engineering disciplines (aircraft, buildings) describe one product from multiple perspectives, each answering different questions — and that information systems needed the same discipline. The result is a 6×6 classification matrix: it tells you what kinds of descriptions exist, never how or in what order to produce them.

The grid — six questions × six perspectives

Columns are the interrogatives — What (data), How (function), Where (network), Who (people), When (time), Why (motivation). Rows are audiences, from the executive setting scope down to the running enterprise. Each cell holds one primitive model. The key rule: moving down a row is a transformation of perspective, not just "more detail" — the owner's business-entity model and the architect's logical data model are different models of the same thing.

Perspective ↓ / Question → What (data)How (function)Where (network) Who (people)When (time)Why (motivation)
Executivescope contexts List of things important to the businessList of processes List of locationsList of organizations List of events & cyclesList of goals & strategies
Business managementbusiness concepts Semantic / business entity modelBusiness process model Business logistics networkWorkflow & org model Master scheduleBusiness plan
Architectsystem logic Logical data modelApplication architecture Distributed system architectureHuman-interface architecture Processing structureBusiness rule model
Engineertechnology physics Physical data modelSystem design Technology architecturePresentation architecture Control structureRule design
Techniciantool components Data definitions (DDL)Programs Network configurationSecurity & access definitions Timing definitionsRule specifications
Enterprisethe running instance Actual dataWorking functions Physical networksTrained people Executed schedulesEnforced rules

Core ideas

  • An ontology — a complete classification of architecture descriptions
  • Primitive models per cell; real deliverables are composites of several cells
  • Column traceability: every cell in a column describes the same thing at a different altitude

Strengths

  • Complete — nothing about a system falls outside the grid
  • Audience-matching: explains why one diagram can't serve everyone
  • Framework-agnostic — every other framework's artifacts can be located in it

Limits

  • No process, no deliverables, no guidance on how — by design
  • No notation — you bring your own modeling language
  • Filling all 36 cells is impractical and never the point
How it evolved
YearMilestoneWhat changed
1987"A Framework for Information Systems Architecture" (IBM Systems Journal)The original paper — only three columns (data, function, network), inspired by how construction and aerospace document one product from many perspectives
1992Sowa & Zachman extensionAdded the Who / When / Why columns, completing the six interrogatives
2011Version 3.0 — "The Zachman Framework for Enterprise Architecture"Rebranded as an enterprise ontology; row names shifted from builder-metaphor roles (Planner, Owner, Designer, Builder, Subcontractor) to audience perspectives (Executive, Business Management, Architect, Engineer, Technician)
The seven rules of the grid
#RuleWhy it matters
1Columns have no orderWhat is not more important than Why; the grid is a classification, not a sequence
2Each column has one simple, generic modelThe What column is always entities-and-relationships, whatever the row
3Each cell's model is uniqueA logical data model is not a physical data model with less detail — it's a different model
4Each row is a distinct, complete perspectiveEvery row describes the whole enterprise, from one audience's point of view
5Each cell is unique — no cell substitutes for another36 cells, 36 different primitive models
6Composite of all cells in one row = complete model from that perspectiveReal-world deliverables are composites assembled from primitives
7The logic is recursiveThe same grid can classify descriptions of a whole enterprise, one division, or one system
The row-to-row transformations (reification)

Zachman names the movement down the rows reification — the process by which an abstract idea becomes a running instance: Identification (executive names what matters) → Definition (business management defines the concepts) → Representation (architect represents them as system logic) → Specification (engineer specifies the technology) → Configuration (technician configures the tools) → Instantiation (the enterprise runs). Each arrow is a translation between audiences, and every translation is a place where intent can be lost — which is exactly where architects add value.

Worked example — tracing one column (What) for an online retailer
PerspectiveThe "What" cell contains
ExecutiveA list: customers, orders, products, suppliers, payments — the things the business must keep track of
Business managementA business entity model: a Customer places Orders; an Order contains Products; a Payment settles an Order — with business definitions ("an Order exists once checkout completes")
ArchitectA logical data model: normalized entities, attributes, keys — ORDER(order_id, customer_id, status, placed_at), independent of any database engine
EngineerA physical data model: PostgreSQL tables, indexes, partitioning strategy for the orders table, read replicas
TechnicianThe actual DDL, migration scripts, connection pool configuration
EnterpriseThe production data itself — 14 million order rows and counting

Read the column bottom-up and you get audit traceability: which executive concern does this table serve? Read it top-down and you get impact analysis: if the business redefines "Order", what breaks? This column trace — not the full grid — is how Zachman gets used in anger (see Case study 04 below).

Using the grid diagnostically

Four practical uses

  • Audience matching — when a stakeholder rejects a diagram, locate it in the grid: you've probably given a row-1 audience a row-3 artifact
  • Coverage audit — map your existing docs onto the grid; the empty cells that matter for a current decision are your gaps
  • Scoping conversations — "we're talking row 2, column Why" ends many circular meetings
  • Locating other frameworks — C4 lives around rows 3–4 of What/How; a capability map is row 1–2; every framework's artifacts fit somewhere in the grid

Common misconceptions

  • "It's a methodology" — it isn't; it never tells you what to do first, or at all
  • "Lower rows are more detailed" — no: they're different perspectives, each complete in itself
  • "You should fill it in" — the grid is a map for classifying descriptions you need anyway, not a to-do list
  • "It's obsolete" — the ontology can't really age; what dated is the ambition to document everything
TG
TOGAF
The Open Group, 1995 (from US DoD's TAFIM) · current: TOGAF 10 · a method + governance

The most widely adopted EA framework. Where Zachman classifies, TOGAF prescribes a process: the Architecture Development Method (ADM), a repeatable cycle for taking an enterprise from a current state to a target state with governance along the way. It covers four architecture domains — Business, Data, Application, Technology (BDAT) — and TOGAF 10 restructured the content into a small stable core plus extended guidance so it can be adopted piecemeal.

Requirements Management feeds every phase Preliminary A · Vision B · Business C · Info Systems D · Technology E · Opportunities F · Migration G · Governance H · Change Mgmt
The ADM cycle: nine phases around a continuous Requirements Management hub. In practice the loops nest and repeat — nobody runs it once, clockwise, to completion.
The ADM — every phase, what it does, what it produces
PhasePurposeKey outputs
PreliminaryEstablish the architecture capability itself — scope, principles, tailoring, toolsArchitecture principles, tailored framework, governance setup
A · Architecture VisionScope the engagement, identify stakeholders and their concerns, get sponsorshipStatement of Architecture Work, Architecture Vision, stakeholder map
B · Business ArchitectureBaseline and target for the business layer: capabilities, processes, organizationBusiness architecture (baseline + target), gap analysis
C · Information SystemsTwo sub-architectures: Data (what information, where mastered) and Application (which systems, how they interact)Data & application architectures (baseline + target), gaps
D · Technology ArchitecturePlatforms, infrastructure, networks that host the application layerTechnology architecture (baseline + target), gaps
E · Opportunities & SolutionsConsolidate all gaps into work packages; define transition architectures (plateaus)Work packages, transition architectures, high-level roadmap
F · Migration PlanningCost, prioritize, and schedule — turn the roadmap into a funded planImplementation & Migration Plan, finalized roadmap
G · Implementation GovernanceEnsure delivery projects conform to the architectureArchitecture contracts, compliance reviews, dispensations (waivers)
H · Architecture Change ManagementWatch for drift and changed conditions; decide when a new ADM cycle is neededChange requests, updated architecture
Requirements MgmtThe hub of the cycle — requirements flow into and out of every phase continuouslyRequirements repository, impact assessments

Beyond the ADM

  • Content framework — metamodel of deliverables, artifacts, and building blocks
  • Enterprise Continuum — organize assets from generic (industry) to specific (yours)
  • Architecture Repository — where all of it lives
  • Capability framework — ARB, contracts, skills, maturity models

Strengths

  • Shared vocabulary across the industry — everyone knows what "Phase B" means
  • Baseline → target → gap is genuinely reusable on any transformation
  • Explicitly designed to be tailored, not adopted wholesale
  • Certification (Foundation / Practitioner) is a recognized hiring signal

Limits

  • Document-heavy if followed literally; easy to mistake deliverables for outcomes
  • No notation of its own — pairs with ArchiMate for the actual models
  • Weak on modern delivery (agile, product teams) — the guidance exists but feels bolted on
The vocabulary — deliverables, artifacts, and building blocks
TermMeaningExample
DeliverableA contractually specified, formally reviewed work product — what a phase hands overArchitecture Definition Document, Implementation & Migration Plan
ArtifactA single architectural description inside a deliverable — TOGAF sorts them into catalogs (lists), matrices (relationships), and diagrams (pictures)Application Portfolio catalog, Application/Function matrix, Application Communication diagram
Architecture Building Block (ABB)A capability specification — what is needed, technology-neutral"An event streaming platform with replay and ordering guarantees"
Solution Building Block (SBB)The concrete implementation that realizes an ABB"Apache Kafka on AWS MSK, 3 brokers, us-east-1"

The ABB → SBB distinction is TOGAF's quiet masterstroke: phases B–D specify ABBs, phase E maps them to SBBs. Keeping the two apart is what lets you change vendors without rewriting the architecture.

Architecture principles — the anatomy

A TOGAF principle has four mandatory parts — Name, Statement, Rationale, Implications. The implications are what separate a principle from a poster on the wall:

NameBuy before build before extend
StatementWe adopt commercial or open-source products unmodified before building custom software, and we never fork what we adopt.
RationaleCustom code is a liability with a permanent maintenance tail; our differentiation is in logistics, not software infrastructure.
ImplicationsEvery build decision needs a documented buy evaluation first (record it as an ADR). Product selection weight shifts toward configurability. Some "perfect fit" requirements will be renegotiated rather than built.

Keep 5–10 principles, no more. When two principles conflict on a real decision (they will), the resolution is an ADR — and that's the system working, not failing.

Gap analysis — the core technique

Every domain phase (B, C, D) ends the same way: draw a matrix with baseline building blocks as rows, target building blocks as columns. Where a baseline block maps to a target block — carried forward (possibly upgraded). A baseline row with no target column — eliminated (deliberately, or you've found an accidental omission). A target column with no baseline row — new, and every "new" cell is a gap that must land in a work package in Phase E. The discipline isn't the matrix; it's that nothing gets eliminated or created by accident.

The Enterprise Continuum & Architecture Repository

Enterprise Continuum — generic → specific

  • Foundation architectures — universal (the TRM: every system has compute, storage, network)
  • Common systems architectures — recurring solutions (an integration architecture, a security architecture)
  • Industry architectures — sector reference models (BIAN for banking, TM Forum for telecom, IATA for airlines)
  • Organization-specific — yours. The point: check the three shelves to the left before designing from scratch
  • Runs twice in parallel: an Architecture Continuum (ABBs) and a Solutions Continuum (SBBs)

Architecture Repository — where it all lives

  • Architecture Metamodel — the tailored content framework you agreed to use
  • Architecture Landscape — the models, at three altitudes: strategic, segment, capability
  • Reference Library — templates, patterns, adopted industry models
  • Standards Information Base — the approved-technologies list projects get held to
  • Governance Log — decisions, compliance assessments, waivers granted
  • In practice this is a wiki + Git + the ADR log, not a product you buy
Governance in practice — how conformance actually works
MechanismWhat it is
Architecture Review BoardThe standing body that approves architectures, hears exceptions, and owns the principles. Small (5–7), senior, with real veto power — or it's theater
Architecture ContractThe agreement between the architecture function and an implementing project: what will be built, which standards apply, what conformance will be checked
Compliance assessmentTOGAF's graded scale — Irrelevant → Consistent → Compliant → Conformant → Fully conformant → Non-conformant. The grades matter: most healthy projects are "compliant" (follows the spirit, some features unimplemented), and demanding "fully conformant" everywhere is how ARBs lose the room
Dispensation (waiver)A time-boxed, recorded permission to deviate — with an owner and an expiry. An honest waiver log is worth more than a clean compliance report; it's your technical-debt register at the architecture level
Scaling the ADM — iterations and altitude

The ADM diagram looks like a waterfall; the standard itself says it isn't. It runs as nested loops: an Architecture Capability iteration (Preliminary + A) when the practice itself changes, an Architecture Development iteration (B–D) that cycles as understanding improves, a Transition Planning iteration (E–F) as plans meet budget reality, and an Architecture Governance loop (G–H) that runs continuously. The Landscape is also layered by altitude — strategic (the whole enterprise, low detail), segment (one business area), capability (one capability increment, high detail) — and a full ADM cycle can run at any of the three. A two-week capability-level cycle is still TOGAF.

In practice — the ceremony vs. what survives

The ceremony (skip deliberately)

  • Running all ten phases sequentially with full deliverable sets
  • Exhaustive Architecture Repository & Enterprise Continuum curation
  • Heavyweight document templates for every phase output

What survives contact

  • ADM as a scoping checklist — “have I forgotten anything?”, never a linear process
  • The spine — baseline → target → gap → roadmap, on any transformation
  • TIME portfolio scoring — rate each application on business value × technical fit → Tolerate / Invest / Migrate / Eliminate, with a next step per app
  • The vocabulary — “Phase B”, “ARB”, “waiver” mean the same thing in every large org; that shared language is half the certification's value
AM
ArchiMate 3.x
Telematica Instituut (NL), early 2000s → The Open Group since 2008 · a modeling language

The standard notation for enterprise architecture — what UML is to software design, ArchiMate is to the enterprise. It defines a precise vocabulary of elements and relationships across layers, so a model means the same thing to every reader. TOGAF says when to model; ArchiMate says how to draw it.

The layers
MOTIVATION goals · drivers requirements “why?” — crosses all layers STRATEGY capability · resource · course of action BUSINESS actor · role · process · business service · object APPLICATION component · application service · interface · data object TECHNOLOGY node · device · system software · network · artifact PHYSICAL equipment · facility IMPL. & MIGRATION work package · plateau realization serving
The stack: each layer's services serve the layer above; concrete elements realize abstract ones. Motivation crosses everything — every element should trace to a “why”.
LayerQuestion it answersTypical elements
MotivationWhy does the architecture exist?Stakeholder, driver, goal, outcome, requirement, principle
StrategyWhat courses of action and capabilities get us there?Capability, resource, course of action, value stream
BusinessHow does the business operate?Business actor, role, process, service, function, business object
ApplicationWhich systems support the business?Application component, application service, interface, data object
TechnologyWhat infrastructure runs the applications?Node, device, system software, network, artifact
PhysicalWhat physical machinery and facilities are involved?Equipment, facility, distribution network, material
Implementation & MigrationHow do we get from here to there?Work package, deliverable, plateau, gap

Each layer is crossed with three aspects: active structure (who/what acts), behavior (what happens), and passive structure (what is acted upon). This layer × aspect grid is ArchiMate's quiet homage to Zachman.

The relationships that carry the meaning

Structural

  • Composition / aggregation — part-of (strong / loose)
  • Assignment — an active element is allocated to behavior ("this team runs this process")
  • Realization — a more concrete element makes an abstract one real ("this app realizes this capability") — the single most important relationship for impact analysis

Dependency & dynamic

  • Serving — provides functionality to ("the API serves the portal")
  • Access — behavior reads/writes passive elements (data)
  • Triggering / flow — temporal order and what passes between behaviors
  • Influence — motivation elements affecting each other (+/−)

In practice

  • Viewpoints — predefined element selections per stakeholder concern (Layered, Capability Map, Application Cooperation, Technology…)
  • Archi — the free, de-facto modeling tool; Open Exchange Format for portability
  • A maintained model answers impact questions no diagram pile can
Notation — how to read any ArchiMate diagram in 30 seconds

Shape = aspect

  • Square corners — active structure: the thing that acts (actor, role, component, node)
  • Rounded corners — behavior: what happens (process, function, service)
  • Rectangle with corner fold / plain — passive structure: what is acted on (business object, data object, artifact)

Color = layer (convention)

  • Yellow — business layer
  • Blue — application layer
  • Green — technology layer
  • Motivation elements are typically purple/lilac; strategy orange; implementation pink — colors are convention, not part of the standard, but every tool follows them

Naming conventions

  • Behavior elements: verb-ish — "Handle claim", "Process payment"
  • Services: noun + "service" from the consumer's view — "Payment service"
  • Active structure: nouns — "Claims department", "Policy admin system"
  • Objects: business nouns — "Insurance policy", "Claim file"
The core metamodel pattern (the one idea under every layer)

Every ArchiMate layer repeats one service-oriented pattern: internal active structure (a component, a team) is assigned to internal behavior (a process, a function), which realizes an externally visible service, exposed through an interface, which serves the layer above. That's why the language composes so cleanly across layers: the business layer consumes application services; the application layer consumes technology services. Once you see the pattern, you can model anything in it — and spot models that break it (an app "serving" another app's database directly, say) at a glance.

Beyond the basics — derivation, junctions, grouping

Derived relationships

  • If A realizes B and B serves C, a valid derived relationship A → C exists
  • This is what makes big models navigable: draw the detailed chain once, show the derived shortcut in executive views
  • Tools compute these — it's the formal basis for "what depends on what" queries

Junctions & specialization

  • And/Or junctions — split or join triggering/flow ("either channel triggers the process")
  • Specialization — "is a kind of"; lets you define your own element subtypes ("Microservice" as a specialization of Application Component)

Grouping & location

  • Grouping — informal container for any elements (a domain, a bounded context)
  • Location — where things physically are (a region, a data center)
  • Both are how large landscape views stay readable
The standard viewpoints — pick by stakeholder concern
ViewpointQuestion it answersFor whom
OrganizationWho is structured how?Executives, HR, PMO
Business Process CooperationHow do processes interact end-to-end?Process owners, ops managers
Capability MapWhat does the business do?Executives, strategy, portfolio
Application CooperationWhich apps talk to which, and how?Solution architects, integration teams
Application UsageWhich business processes use which apps?Business analysts, app owners
TechnologyWhat infrastructure exists and what runs on it?Infrastructure & platform teams
LayeredThe whole stack, all layers, realization links verticalArchitects — the "one slide" of EA
MotivationWhich goals and requirements drive what?Sponsors, business owners
Implementation & MigrationWhich work packages deliver which plateaus?Program managers, transformation leads
Worked example — one chain through all layers

Goal "Reduce claim settlement time" (motivation) is realized by capability "Claims Management" (strategy) ← realized by business process "Handle claim" performed by role "Claims handler" (business) ← served by application service "Claims processing service" realized by component "ClaimCenter" (application) ← served by technology service "Container platform" realized by node "AKS cluster" (technology). One connected chain — so when someone proposes retiring ClaimCenter, the model answers instantly: which process stalls, which capability degrades, which goal is at risk. That query is the business case for maintaining the model.

ArchiMate vs. UML vs. BPMN — pick the right language
LanguageScopeGranularityUse it for
ArchiMateWhole enterprise, all layersCoarse — architecture-level only, deliberately ~60 element types not 250Landscapes, capability maps, cross-layer impact
UMLOne system's software designFine — classes, sequences, statesDetailed design inside a component (C4 level 4 territory)
BPMNOne process, executable detailFine — tasks, gateways, events, swimlanesProcess automation and workflow engines; an ArchiMate business process can "link" to the BPMN that details it
In practice — the ceremony vs. what survives

The ceremony (skip deliberately)

  • Modeling every element type across all layers “for completeness”
  • An enterprise-wide model maintained by one team that nobody consults

What survives contact

  • A small subset carries the value — realization + serving links over a capability map and an application landscape; those two views are what executives and PMs actually request
  • A maintained model beats stale wall art — one living Archi model outperforms a folder of Visio exports every time
C4
C4 model + Structurizr DSL
Simon Brown, ~2011 · open source · system-level diagramming

Born as a reaction to two failure modes: meaningless boxes-and-lines on whiteboards, and heavyweight UML nobody maintains. C4 describes one software system at four zoom levels — "Google Maps for your codebase" — with strict notation hygiene so every diagram is self-explanatory.

The four levels
person system ext 1 · CONTEXT everyone SPA API DB queue 2 · CONTAINER technical people inside the API container order controller payment component order repository 3 · COMPONENT that container's devs class Order { place() cancel() } 4 · CODE the IDE draws this
Google-Maps zoom: each level opens one box from the level before. Most systems need only levels 1–2; draw 3 selectively, generate 4.
LevelShowsAudienceElements
1 · System ContextThe system as one box, its users, and neighboring systemsEveryone, including non-technicalPerson, software system, external system
2 · ContainerThe deployable/runnable units inside the system — web app, SPA, API, database, message broker (not Docker containers)Technical people, in and around the teamContainer (with technology stated)
3 · ComponentThe major building blocks inside one container and their responsibilitiesDevelopers working on that containerComponent
4 · CodeClasses/functions inside one componentRarely drawn — the IDE generates it betterUML class diagram, etc.

Supplementary diagrams

  • System Landscape — all systems in an enterprise scope
  • Dynamic — numbered interactions for one scenario
  • Deployment — containers mapped onto infrastructure

Notation rules

  • Every element: name, type, technology, one-line description
  • Every relationship labelled with intent + protocol ("Reads orders from · JDBC")
  • Title and legend on every diagram; 5–20 elements per view

Structurizr DSL

  • Define the model once as text; generate many views from it
  • Lives in Git next to the code it describes — diffable, reviewable
  • Renders via Structurizr, Mermaid, or PlantUML (C4-PlantUML)
The philosophy — abstractions first, notation second

C4's real contribution isn't the diagrams; it's the shared abstraction model: a person uses a software system, which is made of containers, which are made of components, which are made of code — connected by relationships. Agree on those words first and any notation works; skip that agreement and no notation saves you. This is why a team fluent in C4 can whiteboard coherently: they're not sharing a drawing style, they're sharing a vocabulary.

Per-level guidance — what to include, what to leave out
LevelIncludeLeave outClassic mistake
ContextYour system (one box), every user type, every external system you integrate withAny internals, any technology namesDrawing internals because "context feels too simple" — simple is the point; this is the diagram executives keep
ContainerEvery separately deployable/runnable unit + datastores + technology choices, and the protocols between themClasses, modules, infrastructure details (that's the deployment diagram)Confusing containers with Docker containers — a database is a container; a Kubernetes pod is deployment detail
ComponentThe major structural building blocks of one container and their responsibilitiesEvery class — a component is a cohesive unit (a service, a repository, a module), not a fileDrawing it for every container "for completeness" — draw it only where the internal structure is genuinely non-obvious
CodeNothing, usually — let the IDE generate it on demandHand-maintaining class diagrams that are stale by the next commit
Structurizr DSL — the model-as-code idea, concretely
workspace "Checkout" {
  model {
    customer = person "Customer" "Buys products online"
    checkout = softwareSystem "Checkout System" {
      spa    = container "Checkout SPA"  "Cart & payment UI"   "React"
      api    = container "Checkout API"  "Order orchestration" "Spring Boot"
      db     = container "Orders DB"     "Order storage"       "PostgreSQL" "Database"
      events = container "Event Bus"     "Order events"        "Kafka"
    }
    stripe = softwareSystem "Stripe" "Payment provider" "External"

    customer -> spa    "Uses"                "HTTPS"
    spa      -> api    "Calls"               "JSON/HTTPS"
    api      -> db     "Reads from / writes to" "JDBC"
    api      -> events "Publishes events to" "Kafka protocol"
    api      -> stripe "Charges cards via"   "REST"
  }
  views {
    systemContext checkout "Context"   { include *  autolayout lr }
    container     checkout "Containers" { include *  autolayout lr }
  }
}

One model, two views — and the point is what happens next: rename api once and every view updates; add a container and the context diagram doesn't change (right altitude, no noise). The file lives in Git, so architecture changes show up in pull requests next to the code that caused them.

The supplementary diagrams — when the four levels aren't enough

System Landscape

  • Zoom out past one system: every system + every person in a scope, and who talks to what
  • This is where C4 hands over to ArchiMate — a landscape with capabilities and realization links wants the richer language

Dynamic diagram

  • One scenario, numbered arrows: "1. SPA submits order → 2. API reserves stock → 3. API charges Stripe…"
  • Use for the 2–3 flows people always ask about (checkout, login, refund) — not every endpoint

Deployment diagram

  • Containers mapped onto deployment nodes: AWS account → VPC → EKS cluster → pod
  • One per environment that differs (prod vs. dev); this is where replicas, AZs, and failover live
A C4 diagram review checklist

Every diagram

  • Title says diagram type + scope ("Container diagram — Checkout System")
  • Every element: name + type + technology + one-line responsibility
  • Every arrow labelled with intent and protocol — "uses" alone is a smell
  • Legend present; 5–20 elements; single level of abstraction per diagram (no components floating next to containers)

Tooling landscape

  • Structurizr DSL + Structurizr Lite (free, runs local) — model-of-record
  • C4-PlantUML — C4 macros for PlantUML/Kroki pipelines
  • Mermaid C4 — renders natively in GitHub/GitLab Markdown; best for zero-tooling teams
  • GUI options (IcePanel, diagrams.net C4 shapes) exist, but text formats keep diagrams in code review
In practice — the ceremony vs. what survives

The ceremony (skip deliberately)

  • Component and Code diagrams for everything — the IDE renders code structure better than you can draw it
  • Diagrams as one-off pictures, redrawn (differently) for every meeting

What survives contact

  • Context + Container — the two diagrams developers actually read; they answer 90% of questions
  • The model in the repo — one DSL file as source of truth, updated in the same pull request as the change it depicts
A4
arc42 + ADR / MADR
Gernot Starke & Peter Hruschka (arc42) · Michael Nygard, 2011 (ADR) · docs & decisions as code

Two complementary open templates. arc42 answers "how do we document a system?" with twelve sections, each answering exactly one question. ADRs (Architecture Decision Records) answer "why is it built this way?" — one significant decision per file, written when the decision is made, immutable afterwards.

arc42's twelve sections
§SectionThe question it answers
1Introduction & GoalsWhat is this system for, and what are the top 3–5 quality goals?
2ConstraintsWhat is fixed and non-negotiable (tech, org, regulation)?
3Context & ScopeWhat's inside vs. outside, and who/what do we talk to?
4Solution StrategyWhat are the fundamental decisions and approaches, in half a page?
5Building Block ViewHow is the system statically decomposed? (embed the C4 diagrams here)
6Runtime ViewHow do the blocks interact in the important scenarios?
7Deployment ViewWhere does it run — hardware, environments, mapping?
8Crosscutting ConceptsWhat patterns apply everywhere (security, persistence, logging)?
9Architecture DecisionsWhich significant decisions were made? (the ADR log lives here)
10Quality RequirementsWhat does "good" mean, as measurable scenarios?
11Risks & Technical DebtWhat could hurt us, and what do we already owe?
12GlossaryWhat do our terms mean? (the ubiquitous-language contract)

Anatomy of an ADR (MADR format)

  • Title + status — proposed / accepted / superseded, plus date
  • Context — the forces at play when the decision was needed
  • Decision drivers — what actually mattered (throughput, team skills, cost…)
  • Options considered — each with honest pros and cons; this is the part future readers can't reconstruct
  • Outcome + consequences — the choice, justified against the drivers, with the bad consequences stated too

The conventions that make it work

  • ADRs are immutable — superseded by new ADRs, never rewritten; the log is the history
  • arc42 has a detail knob — LEAN / ESSENTIAL / THOROUGH; write the amount the stakes justify
  • Quality goals must be measurable — vague adjectives are rejected; see the scenario format below
  • Everything is Markdown in Git — reviewed, diffed, and versioned like code
Quality requirements done right — the scenario format (§1 & §10)

arc42's sharpest discipline: a quality goal isn't an adjective, it's a scenariostimulus → environment → response → measure. The measure is what makes it testable, and testable is what makes it architecture rather than aspiration:

QualityScenarioMeasure
PerformanceA customer submits an order during peak load (1,000 concurrent users)Order confirmed in < 200 ms at p95
AvailabilityOne availability zone fails during business hoursCheckout continues; ≤ 30 s of elevated errors; zero data loss
MaintainabilityA new payment method must be addedShipped by one team in ≤ 2 weeks with no change to the order core
SecurityA stolen session token is replayed from a new deviceToken rejected; re-authentication forced; alert raised within 1 min

Pick the top 3–5 and rank them (§1.2) — an architecture that optimizes everything optimizes nothing. The full scenario catalog lives in §10 as a tree: quality attribute → refinement → concrete scenarios.

The building block view — how §5 actually works

§5 is hierarchical white-box / black-box decomposition. Level 1: the whole system as a white box — show its top-level building blocks (these are your C4 containers) and, for each, a black-box description: responsibility, interfaces, quality characteristics. Level 2: open only the blocks that are complex or risky enough to warrant it — each becomes its own white box (C4 components). Level 3 is rare. Two rules keep it honest: every white box needs a stated decomposition rationale (by domain? by team? by rate of change?), and you stop decomposing when the next level would only restate the code.

Filling the tricky sections — field notes

§3 Context — two diagrams, not one

  • Business context: partners and neighboring systems with domain-language flows ("credit check request")
  • Technical context: the same neighbors with channels and protocols (HTTPS, SFTP, topics)
  • Map every external interface to exactly one owner — unowned interfaces are where integrations rot

§8 Concepts — the crosscutting catalog

  • The topics that apply everywhere: domain model, persistence, security & authn/z, error handling, logging/observability, i18n, transactions, configuration
  • Write each once here; link from building blocks — never repeat per block
  • If two blocks solve the same concern differently, §8 is where that inconsistency becomes visible

§11 Risks & debt — kept honest

  • Risks: probability × impact + a mitigation owner — three real risks beat a twenty-row register
  • Technical debt: what we owe, why we took the loan (link the ADR), and the trigger for repaying
  • Review this section at every major release or it becomes fiction
ADRs in depth — significance, lifecycle, conventions

Is it architecturally significant?

  • Hard to reverse — datastore, message bus, language, multi-tenancy model
  • Affects quality attributes — anything that moves the §1 goals
  • Crosscutting — constrains many teams or components
  • Expensive — in money, time, or migration pain
  • One yes is enough. Library choices inside one module usually aren't ADRs

Lifecycle

  • proposed → written before or during the decision, circulated for review
  • accepted → the record of what we're doing and why
  • superseded by ADR-NNNN → the old record stays; the log is the history
  • deprecated / rejected — rejected ADRs are kept too: "we considered and declined" saves the next person the same detour

Conventions & tooling

  • Files: docs/adr/0001-use-postgres.md — numbered, kebab-case, immutable numbering
  • Linked from arc42 §9 (the decision log is §9)
  • Tooling: adr-tools (CLI), log4brains (site generator), MADR templates — but a folder of Markdown needs no tooling at all
  • Anti-patterns: writing ADRs retroactively in bulk (the reasoning is gone), and rubber-stamp ADRs with one option (that's a memo, not a decision record)
In practice — the ceremony vs. what survives

The ceremony (skip deliberately)

  • The 40-page document nobody reads — thoroughness as a failure mode
  • Filling all twelve sections because the template has twelve sections

What survives contact

  • ADRs written at decision time — the trade-offs a future reader can't reconstruct; the single highest-ROI habit in this whole page
  • arc42 at LEAN / ESSENTIAL detail — sections 1, 3, 4, 5 and 9 carry most of the value for most systems; let readers' questions pull in the rest
+
The rest of the landscape
FEAF / DoDAF / MODAF · Gartner · BIZBOK

Three more names you'll meet in job specs and RFPs — each real, each with a legitimate niche, each worth understanding properly even if you never adopt it.

FEAF — the US federal enterprise architecture

Born from the Clinger-Cohen Act (1996), which legally required US federal agencies to maintain an IT architecture. FEAF's core is a set of shared reference models — a common taxonomy so that spending and systems can be compared across agencies and duplicates consolidated. That purpose (compare & consolidate at portfolio scale) is why it looks bureaucratic from a delivery seat: it isn't for building systems, it's for governing thousands of them.

Reference modelClassifiesThe question it standardizes
PRM · PerformanceOutcomes and measuresWhat results does this investment produce?
BRM · BusinessFunctions and services of governmentWhat business function is this — and who else already does it?
DRM · DataData description, context, sharingWhat information is this, and how is it exchanged?
ARM · ApplicationApplication components & interfacesWhat software capabilities exist and overlap?
IRM · InfrastructurePlatforms, networks, facilitiesWhat does it run on?
SRM · SecurityControls and their placementHow is it protected, consistently?
DoDAF / MODAF / NAF — architecture for defense procurement

DoDAF (US Department of Defense) organizes architecture descriptions into viewpoint families, each a set of prescribed views. Its center of gravity is interoperability: forcing hundreds of contractors' systems to document themselves the same way so they can be integrated and compared. MODAF was the UK's adaptation; both now converge on the NATO Architecture Framework (NAF). If you work in defense, aerospace, or national-scale public safety, the RFP will name these and compliance is non-negotiable; outside those worlds you'll never see them.

FamilyNameDescribes
AVAll ViewpointScope, context, dictionary for the whole architecture description
CVCapabilityCapabilities, their taxonomy, phasing and dependencies
OVOperationalOperational activities, nodes, information exchanges — the mission, technology-free
SV / SvcVSystems / ServicesThe systems and services that realize the operational views, and their interfaces
DIVData & InformationConceptual → logical → physical data models
StdVStandardsApplicable technical standards and forecasts
PVProjectPrograms/projects delivering the capabilities

Worth stealing even outside defense: the OV/SV split — describe the mission without technology first, then map systems onto it — is the same discipline as capability-before-application, enforced by contract.

Gartner — EA as a consulting practice, not a document set

The stance

  • No public metamodel, no grid, no phases — deliberately. Gartner's research position: EA frameworks fail when they become documentation programs
  • Business-outcome-driven EA: start from a measurable business outcome, work backwards to the minimum architecture that enables it
  • "Just enough architecture, just in time" — deliverables are decision briefs and roadmaps for executives, not model repositories
  • EA positioned as an internal consultancy with a portfolio of advice, measured like one

What to take from it

  • Measure the EA function by decisions influenced and money saved — if you can't name the decisions your architecture work changed this quarter, that's the finding
  • Every artifact needs a customer — a named person with a pending decision
  • Pairs well with the four standards here: Gartner supplies the operating model, they supply the artifacts
BIZBOK — business architecture as its own discipline

The Business Architecture Guild's body of knowledge (with its own certification, CBA). Its premise: the business can and should be modeled independently of IT — then IT maps onto it. Four core artifact types interlock:

ArtifactWhat it capturesHow it's used
Capability mapWhat the business does (not how, not who) — Level 1: ~7–10 top capabilities; Level 2: their decompositions; Level 3: working detail. Stable across re-orgs because it ignores the org chartThe anchor for everything: heat-map it by investment, maturity, or pain to make portfolio arguments on one page
Value streamEnd-to-end stages that deliver value to a stakeholder ("Acquire product: browse → select → pay → receive")Cross-mapped to capabilities: which capabilities enable each stage — connecting what we do to why anyone cares
Information mapThe business's core information concepts and their relationships, in business languageFeeds data architecture; arbitrates naming wars ("what exactly is an 'account'?")
Organization mapBusiness units mapped to the capabilities they performExposes duplication ("three units all doing collections") and orphan capabilities nobody owns

Heat mapping is the signature move: color the capability map by any lens — strategic importance, current maturity, IT spend, incident volume — and misalignment becomes visible to a board in seconds ("our most strategic capability has our weakest systems"). In TOGAF terms all of this slots into Phase B; in this skill it's Mode 4's foundation.

CAPABILITY MAP — heat: supporting-system health Marketing healthy Customer Onboarding 4 overlapping apps Order Management aging platform Fulfilment healthy Billing ★ strategic + weakest Collections 3 units doing it Customer Service healthy Risk & Compliance manual processes HR & Talent healthy Finance healthy Data & Analytics under-invested Procurement healthy healthy needs attention act now ★ strategic capability
A level-1 capability map heat-mapped by system health — the board sees the argument (“Billing is strategic and weakest”) before anyone speaks.

Frameworks are scaffolding, not the building.

That's the theory. Now the practice: full-ceremony adoption — every phase, every deliverable — is rare and usually collapses under its own weight. The value is delivered through a handful of living artifacts, not through framework compliance. Practitioners steal the useful parts and quietly ignore the rest.

36
Zachman cells — used as a lens, not a to-do list
What practitioners keep is one column traced when a question demands it, and the audience-matching instinct.
10
ADM phases — run as nested loops, never A–H
The part that appears in every real transformation deck is the spine: baseline, target, gaps, roadmap.
1
Page executives actually read
The business-capability map anchors portfolio decisions in language the board understands — heat-map it and the argument makes itself.
Every framework, one honest verdict
FrameworkPractical valueVerdict
Zachman The mental model. When a stakeholder says “this diagram doesn't help me,” you've usually given a row-1 audience a row-4 artifact. 30-min lens
TOGAF ADM ADM as a scoping checklist, the baseline→target→gap spine, the shared governance vocabulary — and, bluntly, the certification as a hiring filter. Borrow the spine
ArchiMate 3.x Arguably more useful day-to-day than TOGAF itself: realization links answer “which capabilities break if we retire this app?” Use in anger
C4 model The diagrams developers actually read. Context + Container answer 90% of questions; stop there unless asked. Default choice
arc42 + ADRs The best value-to-ceremony ratio in the whole space. ADRs make decisions defensible two years later when someone asks “why Kafka?” Highest ROI
FEAF / DoDAF / MODAF Essential if you sell into government or defense — the RFP will name them. Otherwise you will likely never touch them. Niche / mandated
Gartner / “pragmatic EA” The attitude is the takeaway: measure EA by decisions influenced and money saved, not by models produced. Attitude, not artifact
BIZBOK capability maps The one-page capability map is the anchor artifact for portfolio rationalization: “we have four apps doing customer onboarding — why?” Steal the map

Where this skill sits: it deliberately builds on the four with the highest practical yield — C4, ArchiMate, TOGAF ADM, and arc42 + ADRs — and treats the rest as context you should recognize, not ceremony you should perform.

Five situations, four worked through.

EA doesn't pay off evenly. These are the recurring situations where the artifacts genuinely change decisions — and for four of them, the full engagement is worked through below: trigger, artifact pipeline, and what “done” looks like.

01
M&A and post-merger integration
You inherit two of everything. A capability map plus an application landscape with realization links tells you what to keep, merge, or kill — with evidence instead of politics. Worked through below ↓
capability map · TIME
02
Cloud migration & modernization programs
Multi-year programs drift without an anchor. Baseline → target → gap → transition plateaus keeps the program coherent across budget cycles and re-orgs. Worked through below ↓
baseline/target · roadmap
03
Vendor & platform decisions
An ADR with the options and trade-offs recorded makes the decision defensible two years later — when the people who made it have left and someone asks “why Kafka?”
ADR / MADR
04
Regulatory & audit traceability
Banks, healthcare, and government need a trace from business requirement to deployed system. Zachman-style thinking — even informal — is how you provide it. Worked through below ↓
requirement → deployment trace
05
Fighting shadow-IT sprawl
A maintained application landscape is the only way anyone knows what exists. Without one, every audit, migration, and security review starts from archaeology.
application landscape
The worked case studies — every artifact named is something this skill produces
Case study 01 · Cloud migration program

Moving a 60-app estate to the cloud over two years

“The data-center contract ends in 24 months. Leadership wants a credible plan, not a lift-and-shift bill shock.”
  1. Baseline architecture (TOGAF) — inventory the current estate: apps, dependencies, data flows. Usually the most valuable and most skipped step.
  2. Target architecture + gap analysis — per-app disposition (rehost / replatform / refactor / retire), grounded in a TIME assessment.
  3. Transition plateaus (roadmap) — 3–4 intermediate states that each deliver value, so the program survives budget reviews.
  4. ADRs for the platform choices — landing zone, container platform, data platform — with the options and trade-offs recorded.
  5. C4 Context + Container diagrams for each system being refactored (not for the rehosted ones — don't model what you're not changing).

Done looks like: every app has a disposition and a plateau; every platform choice has an ADR; the refactored systems have target-state C4 diagrams in their repos.

Case study 02 · Post-M&A portfolio rationalization

Two companies, two of everything

“We acquired a competitor. Finance wants the duplicate-system cost out within 18 months; nobody can even list the duplicates.”
  1. Business capability map — one page, org-chart-independent: what the combined business does. This is the neutral ground both sides can agree on.
  2. Application landscape (ArchiMate) — map every app to the capability it realizes. Duplicates become visually undeniable: two apps realizing one capability.
  3. TIME scoring per app — business value × technical fit → Tolerate / Invest / Migrate / Eliminate, so the keep/kill call is evidence, not politics.
  4. Kill/keep roadmap + ADRs — sequence the eliminations around data migrations and contract end-dates; record each contested call as an ADR.

Done looks like: a capability map both CTOs sign, every duplicate resolved to a disposition with a date, and the contested decisions written down so they stay decided.

Case study 03 · Greenfield platform design

Designing a new payments platform

“New product line, new platform. We need the design communicated before the team scales from 4 to 20 engineers.”
  1. TOGAF-lite — borrow only the vision and the architecture principles (5–7 of them, with consequences). Skip the rest of the ADM; the stakes don't justify it.
  2. C4 Context → Container — the shared picture every new joiner sees first; kept as Structurizr DSL in the repo so it stays current.
  3. arc42 at ESSENTIAL detail — goals, constraints, context, solution strategy, building blocks, and §9 decisions. Not the 40-page version.
  4. ADRs from day one — every significant choice (event bus, datastore, sync vs. async boundaries) recorded while the reasoning is fresh.

Done looks like: a new engineer reaches productive context in a day from the C4 diagrams and the decision log — without a single meeting.

Case study 04 · Regulatory traceability

Surviving an audit with Zachman thinking

“The regulator wants to see how the ‘right to erasure’ requirement is actually implemented — end to end, with evidence.”
  1. The trace, not the grid — this is Zachman used in anger: one column (the “what”), traced down the rows from executive intent to running code. Not 36 cells.
  2. Requirement → capability — which business capability owns erasure (e.g. Customer Data Management), stated in the capability map.
  3. Capability → applications — the ArchiMate realization links list every app touching personal data; this is the audit scope.
  4. Application → deployment — C4 container diagrams + deployment views show where the data lives and which component performs deletion.
  5. Decisions as evidence — the ADRs for retention periods and deletion mechanics are the documented rationale auditors ask for.

Done looks like: one navigable chain from regulation text to the component that deletes the data — each hop an artifact you already maintain, not a document written for the audit.

The six ways EA work goes wrong.

Each of these looks like diligence from the inside. From the outside, it's why “enterprise architecture” has a reputation problem.

The ivory tower

An EA team producing models nobody asked for, disconnected from delivery teams. The models are correct and irrelevant.

Attach every artifact to a live decision: a migration, a purchase, a review.

The 36-cell grid

Attempting to fill the full Zachman matrix. Completeness becomes the goal; the map outgrows the territory and is stale before it's finished.

Use Zachman as a lens — trace one column when a question demands it.

Ceremonial full-ADM

Running all ten TOGAF phases with full deliverables for a change that needed a two-page vision and three ADRs. Rigor should scale with stakes.

Tailor: pick the phases the risk justifies, skip the rest deliberately.

The 40-page document

Thoroughness as a failure mode: an arc42 doc so complete that nobody reads it, so it answers no one's questions and rots quietly.

Write LEAN or ESSENTIAL; let the reader's questions pull detail in.

Two names, one thing

The same system called “Billing Engine” in one diagram and “Invoice Service” in another. The most common EA defect — it silently breaks traceability.

Stable IDs, reused everywhere — one model under every diagram, doc, and ADR.

Diagrams as one-off pictures

Architecture drawn in a slide tool, redrawn slightly differently for every meeting. No source of truth, so every version is equally wrong.

Diagrams as code, versioned in the repo next to what they describe.

Theory is the map.
The skill is the vehicle.

Everything named on this page — capability maps, TIME scoring, C4 diagrams, arc42 docs, ADRs — is what the skill actually produces. Install it and ask in plain language.

/plugin marketplace add gauravs19/enterprise-architecture-skill
/plugin install enterprise-architecture@gauravs19-skills