# Architecture Documentation

> arc42, C4 model, ISO/IEC/IEEE 42010 (architecture description, viewpoints, views, models), documentation as code, documenting for stakeholders.

## arc42 template and its sections

- [arc42 Architecture Decisions](https://arc.fuet.ch/concepts/documentation/arc42-architecture-decisions.md): Section 9 of arc42 records important, expensive, large-scale or risky architecture decisions with their reasons. It points back to section 4 for the most fundamental decisions instead of repeating them.
- [arc42 Architecture Documentation Template](https://arc.fuet.ch/concepts/documentation/arc42-documentation-template.md): arc42 is a free template that gives architecture information a fixed place across twelve sections. Teams tailor it to their needs and use it in agile, lean or formal projects.
- [arc42 Constraints](https://arc.fuet.ch/concepts/documentation/arc42-constraints.md): Chapter 2 of arc42 lists every requirement that limits how architects may design and build a system. It shows where the team is free to choose and where it must comply.
- [arc42 Context and Scope](https://arc.fuet.ch/concepts/documentation/arc42-context-and-scope.md): Context and Scope is the arc42 chapter that shows the system as a black box and what it exchanges with its environment. The business view covers the data exchanged. The technical view covers the channels.
- [arc42 Glossary](https://arc.fuet.ch/concepts/documentation/arc42-glossary.md): The arc42 glossary is section 12 of the template. It lists the key domain and technical terms stakeholders use, so everyone means the same thing by the same word.
- [arc42 Introduction and Goals](https://arc.fuet.ch/concepts/documentation/arc42-introduction-and-goals.md): Section 1 of arc42 gives a short overview of what the system must achieve. It lists the top three to five quality goals and a table of stakeholders with their expectations.
- [arc42 Quality Requirements](https://arc.fuet.ch/concepts/documentation/arc42-quality-requirements.md): Chapter 10 of arc42 turns quality requirements into concrete quality scenarios, so readers can decide whether each requirement is met. It points to the top goals from section 1.2 and adds lower-priority ones.
- [arc42 Quality Requirements Chapter](https://arc.fuet.ch/concepts/documentation/arc42-quality-chapter.md): Chapter 10 of arc42 turns quality requirements into concrete scenarios. A quality tree gives the overview, and each scenario lets you decide whether a requirement is met.
- [Crosscutting Concept](https://arc.fuet.ch/concepts/documentation/arc42-crosscutting-concepts.md): A crosscutting concept is a practice, pattern, or rule that applies in several parts of a system. arc42 section 8 documents each one once, so the system stays consistent.
- [Data architecture documentation in arc42](https://arc.fuet.ch/concepts/documentation/data-architecture-documentation-in-arc42.md): In arc42, data topics have several homes. Data flows go in the business context, data structures can appear as building blocks, and domain terms go in the glossary. A domain data model can also sit in the crosscutting concepts.
- [Solution Strategy](https://arc.fuet.ch/concepts/documentation/arc42-solution-strategy.md): The solution strategy is a short chapter of an arc42 document. It lists the fundamental decisions that shape the architecture and ties them to the problem, quality goals, and constraints.

## Views, viewpoints and view models

- [4+1 View Model](https://arc.fuet.ch/concepts/documentation/4-1-view-model.md): The 4+1 View Model describes a software system through several views at once. Each view speaks to different stakeholders. A fifth view, made of scenarios, illustrates how the architecture works.
- [Additional Architecture Viewpoints (Security, Information, Operational, Development, Process, Evolution)](https://arc.fuet.ch/concepts/documentation/additional-architecture-views-and-perspectives.md): Besides the basic structural views, a project can add viewpoints for information, development, operations, deployment, security and evolution. Each covers a specific kind of concern that stakeholders raise.
- [Architectural View](https://arc.fuet.ch/concepts/documentation/purpose-of-views.md): An architectural view describes a system from the angle of one stakeholder group. Splitting the description into views keeps each part understandable and lets each reader find what matters to them.
- [Architecture View](https://arc.fuet.ch/concepts/documentation/architecture-view.md): An architecture view shows one side of a system's design. It shows how the architecture addresses the concerns of specific stakeholders, the people with an interest in the system.
- [Architecture View Model](https://arc.fuet.ch/concepts/documentation/architecture-view-model.md): An architecture view model is a ready-made set of viewpoints that fit together to describe a system. Reusing one, such as 4+1, avoids inventing views and avoids one overloaded model.
- [Architecture Viewpoint](https://arc.fuet.ch/concepts/documentation/architecture-viewpoint.md): An architecture viewpoint is a set of patterns, templates and conventions for building one type of view. It names the stakeholders whose concerns that view addresses. A perspective differs: it applies quality guidelines across views.
- [Characteristics of a Good View](https://arc.fuet.ch/concepts/documentation/characteristics-of-a-good-view.md): A good view serves a named stakeholder and a clear purpose. It shows only the detail readers need, and it lets them check that their concerns are covered.
- [ISO/IEC/IEEE 42010 Architecture Description Model](https://arc.fuet.ch/concepts/documentation/iso-iec-ieee-42010-architecture-description-model.md): The 42010 conceptual model separates a system's architecture from the document that describes it. The description is built from views. Each view follows a viewpoint, and each viewpoint frames stakeholder concerns.
- [ISO/IEC/IEEE 42010 Architecture Description Standard](https://arc.fuet.ch/concepts/documentation/iso-iec-ieee-42010-architecture-description-standard.md): ISO/IEC/IEEE 42010 is an international standard for describing architectures. It separates a system's architecture from its description, and it builds the description from views and viewpoints.
- [Model vs. View](https://arc.fuet.ch/concepts/documentation/model-vs-view.md): A model is structured data holding the elements of an architecture and how they relate. A view is a diagram built on top of that model. Each view serves the concerns of certain stakeholders.
- [Stakeholder Perspective and Concern](https://arc.fuet.ch/concepts/documentation/stakeholder-perspective-and-concern.md): A stakeholder is a person, team or organization with an interest in a system. Their interests are called concerns. Architecture documentation must address these concerns, and the concerns decide which views you build.
- [Stakeholder Questions Addressed in Views](https://arc.fuet.ch/concepts/documentation/stakeholder-questions-addressed-in-views.md): Stakeholders ask recurring questions about a system. Each question points to a view that should answer it. Picking views from these questions keeps documentation useful for its audience.

## Context, component, runtime and deployment views (incl. C4)

- [Architectural Overview Diagram](https://arc.fuet.ch/concepts/documentation/architectural-overview-diagram.md): An architectural overview diagram shows the inside of a system at a high level, together with the users and other systems it talks to. It records the early, big solution decisions and gives a base that other diagrams refine.
- [AS-IS and TO-BE View](https://arc.fuet.ch/concepts/documentation/as-is-and-to-be-view.md): An AS-IS view shows the legacy system as it is. A TO-BE view shows the target. Temporary transition states between them may differ from both.
- [Business and Technical Context](https://arc.fuet.ch/concepts/documentation/business-and-technical-context.md): Business context shows which data a system exchanges with people and neighboring systems. Technical context shows the channels and protocols that carry that data. Documenting both, and linking them, helps stakeholders decide.
- [C4 Component Diagram](https://arc.fuet.ch/concepts/documentation/c4-level-3-component-diagram.md): A C4 component diagram opens up one container and shows the components inside it, with their responsibilities and technology. Teams draw it only when it adds value.
- [C4 Level 4: Code Diagram](https://arc.fuet.ch/concepts/documentation/c4-level-4-code-diagram.md): The code diagram is the fourth and most detailed C4 level. It shows the code elements inside one component. It is optional, and tools usually generate it, so teams rarely draw it by hand.
- [C4 Model](https://arc.fuet.ch/concepts/documentation/c4-model.md): The C4 model describes software architecture with four levels of diagrams: system context, containers, components, and code. Each level zooms into the one before it, so each audience can pick the level it needs.
- [Component View](https://arc.fuet.ch/concepts/documentation/component-view.md): A component view shows how a system is built from parts. In arc42 it is the mandatory building block view: a hierarchy of black boxes and white boxes that makes source code structure understandable through abstraction.
- [Component View Refinement Levels](https://arc.fuet.ch/concepts/documentation/component-view-refinement-levels.md): A building block view is built in levels. Each level zooms into chosen blocks of the level above. Only important, risky, complex or volatile blocks get refined. Simple or standard parts are left out.
- [Container Diagram (C4 Level 2)](https://arc.fuet.ch/concepts/documentation/c4-container-diagram.md): A container diagram zooms into one software system and shows its separately running parts: applications and data stores. It also shows the main technologies and how the parts talk to each other.
- [Deployment View](https://arc.fuet.ch/concepts/documentation/distribution-view.md): The deployment view shows which hardware and environments run the system's building blocks. arc42 documents it because infrastructure affects the system, and it suggests UML deployment diagrams.
- [Essential Architecture Views (Context, Component, Runtime, Distribution)](https://arc.fuet.ch/concepts/documentation/contemporary-essential-views.md): Essential architecture views show a system from four angles: its context, its building blocks, its runtime behavior, and its distribution onto hardware. Each view answers a different question for stakeholders.
- [Runtime View](https://arc.fuet.ch/concepts/documentation/runtime-view.md): The runtime view shows how building blocks work together and talk to each other while the system runs. It covers a few chosen scenarios, picked for architectural relevance rather than completeness.
- [System Context Diagram](https://arc.fuet.ch/concepts/documentation/c4-level-1-system-context-diagram.md): A system context diagram shows one software system as a single box. Around it sit the people and other systems it works with. Technical and non-technical readers can both follow it, so it makes a good first diagram.

## Documentation practices and tools

- [Architecture Canvas](https://arc.fuet.ch/concepts/documentation/architecture-canvas.md): An architecture canvas is a one-page structured sheet for capturing the essentials of a software system quickly. It builds on ideas from the Business Model Canvas and comes in three arc42 variants.
- [Diagram Metadata in PNG (drawio.png)](https://arc.fuet.ch/concepts/documentation/diagram-metadata-in-png-drawio-png.md): A .drawio.png file is a normal PNG image that also carries its own draw.io diagram source. You can show it in documentation and reopen it for editing. Plain XML or SVG files suit Git better.
- [Diagrams as Code](https://arc.fuet.ch/concepts/documentation/diagrams-as-code.md): Diagrams as code means writing architecture diagrams as plain text. A toolchain renders the text into pictures. Teams can then store, compare, and build diagrams like source code.
- [Documentation as Code](https://arc.fuet.ch/concepts/documentation/documentation-as-code.md): Documentation as code means writing documentation with the same tools and workflows as software: plain-text markup, Git, code review, and automated builds. Docs become versioned, reviewable, and publishable by tools.
- [Guidelines for Documentation](https://arc.fuet.ch/concepts/documentation/guidelines-for-documentation.md): Write only what readers will use. Match detail to their needs, describe each thing once and reference it elsewhere, and keep the text short so people actually read it.
- [Kroki](https://arc.fuet.ch/concepts/documentation/kroki.md): Kroki is an open-source service that offers one HTTP API for creating diagrams from text, across many diagram libraries. You can use the free public service or run your own instance.
- [Modeling Method](https://arc.fuet.ch/concepts/documentation/modeling-method.md): A modeling method is a short set of team agreements on how to draw architecture models. It keeps diagrams consistent, readable, and limited to what matters.
- [Motivation for Architecture Documentation](https://arc.fuet.ch/concepts/documentation/motivation-for-architecture-documentation.md): Code shows what a system does, but not why it was built that way. Architecture documentation records those reasons, so knowledge does not stay locked in a few people's heads.
- [Rules of Thumb for Modeling](https://arc.fuet.ch/concepts/documentation/rules-of-thumb-for-modeling.md): Readable diagrams follow a few habits. Give each diagram a title and a key, name each element's type, label every relationship specifically, and keep color coding consistent. These facts come from C4 guidance.
- [Self-Documentation](https://arc.fuet.ch/concepts/documentation/self-documentation.md): Self-documentation means a system carries the information needed to understand it inside itself, mainly in its code. This cuts separate documents that fall out of date, but it cannot capture reasons or the full picture.
- [Software Architecture Documentation Consensus](https://arc.fuet.ch/concepts/documentation/software-architecture-documentation-consensus.md): Teams that document software architecture increasingly agree on the basics: split the description into views, build views with a small set of diagram types, and write for stakeholders. Approaches like arc42 and C4 follow this pattern.
- [View Creation Method](https://arc.fuet.ch/concepts/documentation/view-creation-method.md): Every architecture diagram should say which notation it uses, who it is for and why it exists. The arc42 building block view and runtime view are two views where this applies.

## Documentation antipatterns

- [Architectural Overview Antipattern](https://arc.fuet.ch/concepts/documentation/architectural-overview-antipatterns.md): An overview diagram fails when readers cannot tell what it shows. Common causes are unclear scope, cryptic labels, and unexplained notation. Fix it with a title, a legend, plain names, and several simpler diagrams.
- [Component View Antipattern: Lifting Code to Model Level](https://arc.fuet.ch/concepts/documentation/component-view-antipattern-lifting-code-to-model-level.md): Lifting code to model level means copying code packages, such as Facade, Service or Dto, into the architecture view. The diagram then mirrors the source code instead of abstracting it into meaningful building blocks.
- [Context View Antipatterns](https://arc.fuet.ch/concepts/documentation/context-view-antipatterns.md): A context diagram shows one system as a black box, with its direct neighbors and the data exchanged. Common mistakes blur this view: unlabeled arrows, system internals, unclear boundaries, or too much detail.
- [Distribution View Antipatterns](https://arc.fuet.ch/concepts/documentation/distribution-view-antipatterns.md): A deployment view shows how software maps onto hardware and infrastructure. Reviewers should check three things: the mapping, the environments covered, and whether infrastructure nodes appear.
- [Runtime View Antipattern: Code-Level Activity Diagram](https://arc.fuet.ch/concepts/documentation/runtime-view-antipattern-code-level-activity-diagram.md): A runtime view that draws code-level steps, such as package or script names, repeats what the source code already shows. It leaves out which building blocks work together and who is responsible for what.
- [Self-Invented Notation Drawback](https://arc.fuet.ch/concepts/documentation/self-invented-notation-drawback.md): A self-invented notation is a set of diagram symbols the author made up. Readers cannot tell what the symbols mean without help. A legend, or a standard notation, reduces the problem.
- [Unclear Level of Abstraction Antipattern](https://arc.fuet.ch/concepts/documentation/unclear-level-of-abstraction-antipattern.md): An architecture diagram that mixes high-level and low-level elements confuses readers. The fix is to keep each diagram at one abstraction level and draw separate diagrams when both views are needed.
- [Undetected Duplication Antipattern](https://arc.fuet.ch/concepts/documentation/undetected-duplication-antipattern.md): The same function or element is listed twice in one overview, and nobody notices. The remedy is to describe each element once, where it is handled, and have other places point to that description.