arc42 vs C4 Model: Differences and How to Combine Them

Someone on your team proposes arc42 for the architecture docs. Someone else says the team already uses C4. The discussion that follows usually assumes you have to pick one, and that assumption is the first thing to drop.

Comparing arc42 vs C4 is a little like comparing a report outline with the charts that go inside it. arc42 is a template: twelve sections that tell you what to document about an architecture, from quality goals to risks. C4 is a model and a notation: four levels of diagrams that tell you how to draw the structure of a software system. They overlap in a few places, and they combine well. This guide covers what each one covers, what arc42 asks for that C4 doesn't draw, what C4 adds to arc42, and a section-by-section mapping of which C4 diagram goes where.

The one-line answer

arc42 is a template for architecture documentation. The C4 model is a way to draw software architecture diagrams. Most teams that use both put C4 diagrams inside arc42 sections.

arc42's own FAQ describes the relationship this way. Asked "What about arc42 and C4?", it says the C4 model "has many similarities to a few sections from arc42, but omits certain parts (e.g. quality requirements, crosscutting concepts, risks and a few others)" (arc42 FAQ, B-17). The same FAQ lists Simon Brown's C4 model among the alternatives to arc42 (A-6), which is true if you only need diagrams, and misleading if you need everything else a document holds.

The twelve arc42 sections

Before mapping anything, it helps to have the sections in front of you with their exact numbers. These are from the arc42 documentation, template version 9.0 (July 2025, per the download page):

One more thing arc42 is explicit about: you don't fill in everything. Its FAQ answers "which parts are essential?" with "Please don't fill in everything. Document only what your stakeholders need", because everything you write "will potentially require maintenance effort in the future" (B-1). That advice matters for the combination below. A lean arc42 document with good C4 diagrams in three sections beats a complete one nobody updates.

What arc42 covers that C4 doesn't

C4 is about structure and, through its supplementary diagrams, runtime and deployment. It says nothing about the parts of an architecture that aren't boxes. In arc42 terms, these sections have no C4 counterpart at all:

• Section 1, Introduction and Goals. Why the system exists, who cares about it, and the three to five quality goals that shape every later decision. A C4 context diagram shows who uses the system. It can't say that "a checkout must complete in under two seconds" matters more than "the admin UI is pretty".
• Section 2, Constraints. "Must run on the company's Kubernetes platform", "must be written in Java", "data may not leave the EU". Constraints explain choices a diagram only displays.
• Section 4, Solution Strategy. The handful of fundamental choices (monolith first, event sourcing for the ledger, buy the search engine) summarized in one place.
• Section 8, Crosscutting Concepts. Authentication, error handling, logging, persistence patterns, internationalization. These run through every box, so no single box can show them.
• Section 10, Quality Requirements. Concrete quality scenarios: stimulus, response, measure.
• Section 11, Risks and Technical Debt. What you know is fragile, and what you've deferred.
• Section 12, Glossary. The words the business uses, defined once.

These are exactly the sections arc42's FAQ names when it says C4 "omits certain parts". If your architecture documentation is only C4 diagrams, these are the questions a new architect or an auditor will still have after reading it.

What C4 adds to arc42

arc42 deliberately doesn't prescribe a notation. Section 5 asks for a "hierarchial collection of black boxes and white boxes", section 3 suggests "all kinds of diagrams that show the system as a black box", and section 6 accepts anything from a numbered list of steps to sequence diagrams, BPMN or state machines (section 5, section 3, section 6). That flexibility is a strength of the template, and it's also where arc42 documents tend to vary most: every author draws differently.

C4 fills that gap with two things:

1. A consistent zoom. arc42's building block view already has levels: Level 1 is "the white box description of the overall system together with black box descriptions of all contained building blocks", and Level 2 "zooms into some building blocks of level 1" (section 5). C4's levels give those zoom steps a fixed meaning (system, container, component, code), so a reader who knows C4 knows what they're looking at before they read the labels.
2. A small shared vocabulary. Person, software system, container, component, relationship, each with a name, a description and usually a technology. It's enough notation to make diagrams comparable across teams, and little enough that nobody needs training.

There's also a practical benefit. If the C4 diagrams come from a model rather than a drawing tool, the same element appears with the same name in sections 3, 5, 6 and 7. arc42 has no opinion on how you achieve that, but it's what makes the sections agree with each other.

Mapping table: which C4 diagram goes in which arc42 section

This mapping is ours, derived from arc42's section definitions and the C4 diagram definitions. arc42's FAQ points to community examples of the combination (for instance bitsmuggler's arc42 + C4 example repository) rather than prescribing one, and teams do vary on the details noted in the last column.

The sections not in the table (1, 2, 4, 8, 10, 11, 12) are text and tables, not C4 diagrams. That's not a gap in either method; it's the division of labor.

Worked example

Here's what the combination looks like for the e-commerce system from our complete guide to the C4 model: a React single-page app, an API gateway, Go services for orders, products and users, PostgreSQL databases, Kafka and a notification service. This is a lean arc42 skeleton with the C4 diagrams placed, not a full document.

1. Introduction and Goals
   - Purpose: customers browse and order products; warehouse staff manage stock
   - Quality goals: (1) checkout completes in under 2 s at p95
                    (2) no order is confirmed without a successful payment authorization
                    (3) a new service can be added without changing existing ones

2. Constraints
   - Runs on the company Kubernetes platform; Go for backend services

3. Context and Scope
   - Business context: C4 System Context diagram
     [Customer], [Warehouse Staff] -> [E-Commerce Platform]
     -> [Stripe], [FedEx API], [SendGrid]
   - Technical context: table of partner / protocol / data exchanged

4. Solution Strategy
   - Database per service; asynchronous notifications via Kafka

5. Building Block View
   - Level 1: C4 Container diagram (SPA, API Gateway, Order/Product/User
     services, three PostgreSQL databases, Kafka, Notification Service)
   - Level 2: C4 Component diagram of the Order Service only
     (Order Handler, Order Service, Order Repository, Payment Client,
     Inventory Client)

6. Runtime View
   - "Customer places an order": C4 dynamic diagram, 10 numbered steps

7. Deployment View
   - Production: C4 deployment diagram
   - Staging: differences from production only

8. Crosscutting Concepts
   - Authentication at the gateway; idempotency keys on POST /orders;
     structured logging with a request ID

9. Architecture Decisions
   - ADR-001 Database per service
   - ADR-002 Kafka for order events instead of synchronous calls
   - ADR-003 Authorize payment before writing the order

10. Quality Requirements
   - Scenario: 500 checkouts per minute during a sale, p95 under 2 s

11. Risks and Technical Debt
   - Stock is reserved before payment; no compensation on payment failure yet

12. Glossary
   - Order, Reservation, Authorization, Fulfilment

Notice where the diagrams sit: sections 3, 5, 6 and 7. Everything else is a few lines of text. Notice too how the risk in section 11 and ADR-003 in section 9 refer to the same thing the dynamic diagram in section 6 shows. That cross-referencing is where a combined arc42 and C4 document earns its keep: the diagram shows the order of steps, the ADR says why, and the risk says what's still wrong.

For the dynamic diagram itself, the C4 dynamic diagram guide walks through this exact scenario step by step. For section 9, the complete guide to architecture decision records covers the format arc42 recommends and how to keep an index.

If arc42's twelve sections feel like more than your team needs, our software architecture documentation template is a shorter markdown outline built from the same ideas, with a section explaining how it maps back to arc42.

Keeping both current

arc42 and C4 share a failure mode: both are excellent on the day they're written. arc42's own FAQ warns that every section you fill in is maintenance you've signed up for (B-1). Some habits that hold up:

• Keep diagrams out of the document body where you can. Reference or embed diagrams generated from a model instead of pasting screenshots. A screenshot of a container diagram is stale the day a container is renamed. A diagram rendered from the model is only as stale as the model.
• Put the fast-changing sections next to the code. Sections 5, 6 and 9 change with the code. Sections 1, 2 and 10 change with the business. Storing the first group in the repository (arc42 ships Markdown and AsciiDoc templates for this) means pull requests can update them.
• Write ADRs forward, never edit them. A superseded decision gets a new ADR. Section 9 becomes a history instead of a rewritten story.
• Give every section an owner and a review date. A document with no owner is a document nobody updates.
• Check the structural sections against the code. Sections 3 and 5 describe things that exist in code, so they can be checked automatically. Sections 1, 8 and 10 can't; they need a human review, on a schedule.

That last point is where archyl fits, and only for part of the problem. archyl holds the C4 model, not an arc42 document. Its AI discovery proposes systems, containers, components and relationships from a repository for you to approve, ADRs attach to the C4 elements they affect, and a drift score checks whether the documented elements still exist in the code. That covers the diagram-heavy sections (3, 5, 6, 9). It doesn't write your quality goals, your crosscutting concepts or your risk list, and there's no arc42 export; the text sections stay in your arc42 document, linking to the model.

FAQ

Is arc42 better than C4?

Neither is better because they don't do the same job. arc42 is a documentation template covering goals, constraints, structure, runtime, deployment, decisions, quality and risks. C4 is a way to draw structure consistently. If you need a full architecture document, use arc42 (or something shaped like it). If you need consistent diagrams, use C4. Most teams that need both use C4 diagrams inside arc42.

Can you use arc42 and C4 together?

Yes, and it's common. arc42 doesn't prescribe a notation, so C4 diagrams fit into its sections directly: the context diagram in section 3, the container and component diagrams in section 5, dynamic diagrams in section 6 and deployment diagrams in section 7.

Where does the C4 container diagram go in arc42?

In section 5, Building Block View, at Level 1: the white box view of the whole system. Component diagrams go at Level 2 for the containers that need them. If your system is a modular monolith, your Level 1 building blocks may be modules rather than containers, and the fit is looser.

Does arc42 require UML?

No. arc42 suggests notations in several sections (section 3 mentions a UML deployment diagram for the technical context, for example) but leaves the choice to you. C4, UML and plain boxes and arrows are all used with it.

Where do ADRs go in arc42?

Section 9, Architecture Decisions. arc42 itself recommends an ADR for every important decision, in Michael Nygard's structure, and allows documenting a decision locally in the building block it affects if that reads better.

Is arc42 free?

Yes. The template is free and open source, licensed CC BY-SA 4.0, and available in twelve languages and formats including AsciiDoc, Markdown, Word and Confluence (download page).

Want the C4 half of your arc42 document to stay true to the code? Try archyl free and generate the model from your repository. Keep reading: What is the C4 Model? A Complete Guide | Architecture Decision Records: The Complete Guide | C4 Dynamic Diagram Guide | Software Architecture Documentation Template.