Abstract
I have been working with C4 Model and arc42 software documentation. For quite a while. Combining these two standards is a great way to document your software system. This is especially true as AI assisted coding becomes more commonplace because these provide a template for capturing the requirements of the platform so AI can help with development. The purpose of this post is to share the instructions I have created for using the arc42 template, to demonstrate where the C4 Model diagrams fit in, and to serve as a reference to make using these standards easier.
Disclaimer
This post is solely informative. Critically think before using any information presented. Learn from it but ultimately make your own decisions at your own risk.
My arc42 Instructions
1 - Introduction and goals
REFERENCE 1 - Introduction and Goals | arc42 Documentation
Content. Elevator pitch describing (a) who asked for this system to be created, (b) the high-level business goals the system was created for, i.e. why the system exists, and (c) who uses the system.
1.1 Requirements overview
REFERENCE 1 - Introduction and Goals | arc42 Documentation
Content. A list of the business features of the system. A business feature implements one and only one business process which supports the platform’s underlying business goals.
Motivation. From the end user’s point of view, the features of the system should clearly support business activity.
Form. A table or list with the feature name and a short description. Keep the description as short as possible to optimize readability and avoid redundancy. Optionally associate the feature with a high-level business goal. Optionally refer to requirements documents for each feature.
1.2 Quality goals
REFERENCE 1 - Introduction and Goals | arc42 Documentation
Content. A list of the ISO 25010 quality goals most important to the system.
Motivation. Quality goals influence fundamental architectural decisions to ensure the system operates as expected.
Form. A table or list with the quality goal name and a short criteria statement for meeting the goal. Keep the statement as short as possible to optimize readability and avoid redundancy. Refer to 10 (Quality Requirements). Optionally associate the quality goal with a high-level business goal.
1.3 Stakeholders
REFERENCE 1 - Introduction and Goals | arc42 Documentation
Content. Explicit overview of stakeholders of the system. Stakeholders are all persons, roles or organizations having a stake in the system’s architecture.
Motivation. You should know all parties involved in development of the system or affected by the system. Otherwise, you may get nasty surprises later in the development process. These stakeholders determine the extent and the level of detail of your work and its results.
Form. A table or list with role names, person names, and their expectations with respect to the architecture and its documentation. This can be a simple custom table or a more formal RACI Matrix. Optionally include limited contact information.
2 - Constraints
REFERENCE 2 - Constraints | arc42 Documentation
Content. Constraints are decisions, standards, regulations, or conditions that are outside the control of the team and therefore cannot be changed by the architecture. The system’s architecture must operate within the boundaries defined by these constraints. Constraints may originate from enterprise architecture, security, compliance, legal requirements, organizational policies, existing technology platforms, operational requirements, vendor agreements, or business directives. Add subsections as necessary, grouping constraints together.
Motivation. Architects need to understand which decisions are fixed and which remain open for design. Explicitly documenting constraints helps avoid unnecessary discussions, ensures compliance with organizational and regulatory requirements, and provides context for architectural decisions made elsewhere in this document.
Form. A table or list of constraints that significantly influence the system’s architecture. Include:
- A concise description of the constraint.
- The source or owner of the constraint.
- The impact on the architecture, if not obvious.
- References to the governing policy, standard, regulation, or other documentation.
Constraints may be grouped into categories which include but are not limited to:
- Business and organizational
- Legal and regulatory
- Security and privacy
- Enterprise architecture and technology standards
- Infrastructure and operations
- Vendor, product, or platform constraints
- Project and delivery constraints
3 - Context
REFERENCE 3 - Context and scope | arc42 Documentation
Content. Describe the system boundary, its users, and its communication partners. Document the interactions that cross the boundary to clearly show what is inside the system, what is outside it, and how they communicate.
Motivation. A clear understanding of the system boundary and external interactions helps architects and stakeholders identify responsibilities, dependencies, integration requirements, and the impact of change.
3.1 Business context
REFERENCE 1 3 - Context and scope | arc42 Documentation
REFERENCE 2 System context diagram | C4 model
Content. Describe the system from a business perspective by identifying all relevant users and communication partners that interact with the system. Focus on what interactions occur and why they occur.
Motivation. Understanding the business context helps stakeholders share a common view of the system’s responsibilities, boundaries, and dependencies, providing a foundation for architectural decisions.
Form. A diagram — “App Name: Business Context View” — based on the C4 System Context Diagram (REF.2) with an optional table or list include the following:
The short form:
- Partner System: The name of the partner system.
- Inputs: Brief description of data coming into the system.
- Outputs: Brief description of data going out of the system.
The long form:
- Partner Organization: The name of the company, group, or organization responsible for the partner system.
- Partner System: The name of the partner system.
- Data Shared: Short business description of the data being exchanged.
- Data Format: JSON, XML, CSV, [tab] delimited, Excel, … *( Interface Direction: If the system initiates communication, then outbound. If the partner system initiates communication, then inbound.
- Transfer Direction: If interface direction is outbound, then either push or pull data from the partner. If the interface direction is inbound, then either send or receive data from the partner. Execution Mode: Manual, scheduled, on-demand, real-time Implementation: The product or standard used to establish communication.
3.2 Technical context
REFERENCE 3 - Context and scope | arc42 Documentation
Content. Describe the system from a technical perspective by identifying how all relevant users and communication partners interact with the system. Focus on the technical communication channels: network components, ports, protocols, networks/vpns, and other connectivity details.
Motivation. Understanding the technical context helps architects, developers, and operations teams identify integration requirements, dependencies, network flows, and security considerations.
Form. A diagram — “App Name: Technical Context View” — showing the system, its communication partners, relevant networking and infrastructure components, and the communication paths between them. Each connection should identify the port and protocol used. (and/or) A table or list including the source component and domain/IP address, matched with the target component, domain/IP address, port, and protocol.
7 - Deployment view
REFERENCE 1 7 - Deployment view | arc42 Documentation
Content. Describe the technical infrastructure used to deploy, execute, and operate the application. This section should identify the deployable application components, the infrastructure on which they run, the deployment patterns used to deploy them, and the resources they depend upon. Together, these views provide a complete understanding of the application’s deployment environment and operational dependencies.
Motivation. Understanding the deployment view helps architects, developers, operations teams, support teams, and other stakeholders understand how the application is deployed and operated. It provides visibility into deployment requirements, infrastructure dependencies, and resource usage, enabling impact analysis, operational support, troubleshooting, disaster recovery planning, and infrastructure governance.
7.1 Deployment overview
REFERENCE 1 7 - Deployment view | arc42 Documentation
REFERENCE 2 Container Diagram | C4 model
Application components
Content. Describe the major application and storage components that make up the system. Application components are independently deployable executables such as applications, services, containers, workers, scheduled processes, web servers, and APIs. Storage components include databases, file systems, object storage, and other persistent data stores. The diagram should show the primary application components and their relationships. Similar components that share the same purpose and deployment pattern (file ETL) may be represented by a single view in the diagram, with the individual components documented in an accompanying table.
Motivation. Knowing the application’s components helps architects, developers, operations teams, and other stakeholders understand how the application is structured, executed, and operated. It provides a high-level view of the major executables, data stores, and interactions that make up the system while avoiding unnecessary implementation detail.
Form. A diagram — “App Name: Application Components View” — based on the C4 Container Diagram (REF.2) with a required, supplemental table which includes the following:
- Application Component: The name of the component
- Responsibility: Brief description of what the component does OPTIONAL
- Deployment Pattern: Reference to a deployment view sub-section containing the deployment pattern details
Component resource mapping
Content. Provide a detailed inventory of resources needed for each deployed application component; list all dependencies required for the component to operate successfully. The inventory should include resource details for all deployment environments. Every component identified in “Application components” should be documented individually, including components that are represented by a single consolidated view in the diagram.
Motivation. Component resource mapping helps architects, developers, operations teams, and support teams understand how individual components are deployed, identify operational dependencies, assess the impact of change, and support troubleshooting and infrastructure planning.
Form. A table which includes the following:
- Application Component : The name of a deployed part of the application
- Resource: A business-level description of the resource needed by the building block — File transfer inbox
- Solution: The service or technology used in the deployment infrastructure for the resource — S3 Bucket
- “Non-production 1”: The details of the deployment in the 1st level, non-production environment. —
acme-fpa-input-dev01. Rename column to match your environment —DEV. - “Non-production n”: The details of the deployment in the nth level, non-production environment —
acme-fpa-input-test. Rename column to match your environment —TEST. - PROD: The details of the deployment in a production environment —
acme-fpa-input
7.n “Pattern name” deployment pattern
REFERENCE 1 7 - Deployment view | arc42 Documentation
REFERENCE 2 Deployment Diagram | C4 model
Content. Describe the technical infrastructure required to deploy and run an application component. Multiple components may use this deployment pattern for execution. Rename “Pattern name” to fit the pattern being described — Docker on ECS deployment pattern, NGINX on EC2 deployment pattern, Lambda deployment pattern, RDS deployment pattern.
Motivation. Understanding the technical infrastructure required by each application component helps architects, developers, operations teams, and support teams identify deployment requirements, operational dependencies, and the impact of change. It also provides an inventory of the infrastructure required to successfully deploy the component.
Form. A diagram — “App Name: ‘Pattern name’ Deployment Pattern View” — based on the C4 Deployment Diagram (REF.2). An optional table of supplemental information — CIDER ranges, subnet names, network zones, etc. — may be added as needed.
8 - Crosscutting concepts
REFERENCE 8 - Crosscutting concepts | arc42 Documentation
Content. Describe the architectural practices and technologies used consistently across the application. Crosscutting concerns span multiple components or services and typically include authentication, authorization, logging, distributed tracing, monitoring, file transfer, and error handling. This section should explain the standards, technologies, and patterns used to implement these concerns across the solution.
Motivation. Understanding crosscutting concepts helps stakeholders understand the common technologies and standards used throughout the application. Many of these concepts are driven by enterprise requirements and constraints that all applications must follow.
Form. Organize this section into dedicated subsections for each significant crosscutting concern. Each subsection should describe the purpose of the concern, the technologies used, applicable standards or policies, and how it is implemented throughout the application. Example subsections:
8.1 Authentication 8.2 Authorization 8.3 Logging 8.4 Distributed Tracing 8.5 Monitoring and Alerting 8.6 File Transfer 8.7 Error Handling 8.8 Configuration Management 8.9 Auditing 8.10 Secrets Management 8.11 Data Protection
9 - Architecture decisions
REFERENCE 1 9 - Architecture decisions | arc42 Documentation
REFERENCE 2 JEP 2: JEP Template
Content. Document the significant decisions that affect the system and have a lasting impact on its structure, quality attributes, operations, maintainability, or evolution. Include decisions relating to architecture patterns, technology selection, integration approaches, security design, deployment models, data management, and other choices that meaningfully influence the architecture. Focus on decisions that required evaluation of alternatives and represent deliberate trade-offs.
Motivation. Recording decisions provides a means of collaboration in the decision-making process and transparency for the rationale behind important choices. It helps to avoid revisiting previously resolved discussions, and provides context for interpreting the architecture, managing technical debt, and planning future changes.
Form. Create an Architecture Decision Record (ADR), which is a separate wiki page or document.
The ADR status may be one of:
- RFC (Request for Comment)
- Accepted
- Rejected
- Superseded
- Deprecated
- Abandoned
The ADR content follows the JDK Enhancement Proposal (JEP) document template sections:
- Summary
- Goals
- Non-goals
- Success metrics [Optional]
- Motivation
- Description
- Alternatives
- Testing [Optional]
- Risks and assumptions
- Dependencies
- References [Optional]
10 - Quality
REFERENCE 10 - Quality | arc42 Documentation
Content. This section outlines all quality requirements and provides additional detail to what was defined in 1.2 (Quality goals).
Motivation. Quantify quality goals in a specific and measurable way.
10.1 Quality requirements overview
REFERENCE 10 - Quality | arc42 Documentation
Content. This section provides an overview of the system’s quality requirements and defines the measurable criteria used to evaluate important quality attributes. It supplements 1.2 (Quality goals) by specifying concrete requirements and acceptance criteria.
Motivation. Quality goals are often expressed at a high level and may be open to interpretation. This section translates those goals into specific, measurable, and verifiable requirements, ensuring a common understanding among stakeholders and providing a basis for architectural decisions, implementation priorities, and validation activities.
Form. Typically presented as a structured overview or table that maps quality attributes to their corresponding requirements and measurable targets. Detailed descriptions, metrics, constraints, and acceptance criteria may be provided in other documentation and referenced here.
10.2 Quality scenarios
REFERENCE 10 - Quality | arc42 Documentation
Content. Quality scenarios make quality requirements concrete and allow to decide whether they are fulfilled (in the sense of acceptance criteria). Ensure that your scenarios are specific and measurable. Scenarios may be provided in other documentation and referenced here.
Two kinds of scenarios are especially useful:
- Usage scenarios (also called application scenarios or use case scenarios) describe the system’s runtime reaction to a certain stimulus. This also includes scenarios that describe the system’s efficiency or performance. Example: The system reacts to a user’s request within one second.
- Change scenarios describe the desired effect of a modification or extension of the system or of its immediate environment. Example: Additional functionality is implemented or requirements for a quality attribute change, and the effort or duration of the change is measured.
Motivation. Quality scenarios provide realistic situations that demonstrate how quality attributes should be achieved in practice. They help stakeholders develop a common understanding of expected system behavior, validate architectural decisions, and identify tradeoffs between competing quality goals.
Form. Typical information for detailed scenarios include the following:
The short form:
- Context/Background: What kind of system or component, what is the environment or situation?
- Source/Stimulus: Who or what initiates or triggers a behavior, reaction or action.
- Metric/Acceptance Criteria: A response including a measure or metric
The long form:
- Scenario ID: A unique identifier for the scenario.
- Scenario Name: A short, descriptive name for the scenario.
- Source: The entity (user, system, or event) that initiates the scenario.
- Stimulus: The triggering event or condition the system must address.
- Environment: The operational context or condition under which the system experiences the stimulus.
- Artifact: The building-blocks or other elements of the system affected by the stimulus.
- Response: The outcome or behavior the system exhibits in reaction to the stimulus.
- Response Measure: The criteria or metric by which the system’s response is evaluated.
11 - Risks and technical debt
REFERENCE 11 - Risks and technical debt | arc42 Documentation
Content. Documents the potential risks and identified technical debt affecting the system. Highlight architectural concerns, outstanding compromises, and areas requiring future attention to ensure long-term sustainability and success. Roadmap when concerns may be addressed.
11.1 Potential risks
REFERENCE 11 - Risks and technical debt | arc42 Documentation
Content. Known risks that may affect the system’s success, including security vulnerabilities, single points of failure, scalability bottlenecks, and dependencies on external systems beyond the team’s control. These are usually potential things that might go wrong or cause failure if left unaddressed.
Motivation. Documenting potential risks enables the team to proactively identify, assess, and mitigate threats to the system’s success. It supports informed decision-making, improves transparency, and helps ensure that architectural concerns are addressed before they become significant issues.
Form. A table containing the identified risks, with a concise title and description for each entry. Entries may optionally be assigned an identifier for reference within Section 11.3 (Technical roadmap). Include only information necessary to understand and assess the risk, avoiding unnecessary duplication with other sections.
11.2 Identified debt
REFERENCE 11 - Risks and technical debt | arc42 Documentation
Content. Known technical debt affecting the system, including architectural compromises, implementation shortcuts, deferred improvements, outdated technologies, and temporary solutions that have been carried forward. These are identified — things that are known to exist, having negative consequences if remain unresolved.
Motivation. Documenting technical debt provides transparency into architectural compromises and their impact on the system. It helps stakeholders prioritize remediation efforts, manage risk, and make informed decisions about future investments.
Form. A table containing the identified debt, with a concise title and description for each entry. Entries may optionally be assigned an identifier for reference within Section 11.3 (Technical roadmap). Include only information necessary to understand and assess the debt, avoiding unnecessary duplication with other sections.
11.3 Technical roadmap
REFERENCE 11 - Risks and technical debt | arc42 Documentation
Content. Describe the scheduled plan of activities and initiatives intended to address 11.1 (Potential risks), 11.2 (Identified debt), 9 (Architectural Decisions), as well as to evolve the architecture and improve the system over time. The roadmap communicates architectural priorities and direction while avoiding detailed project management or implementation planning.
Motivation. The technical roadmap provides a forward-looking view of how the architecture is expected to evolve. It helps stakeholders understand planned investments, prioritize future work, and track progress toward reducing debt, mitigating risks, and making system improvements.
Form. A table or timeline presenting the planned architectural initiatives, improvements, and remediation activities. Entries should include provide traceability back to identified items and an estimated start and end date.
12 - Glossary
REFERENCE 12 - Glossary | arc42 Documentation
Content. Capture the relevant domain-specific and technical terminology required to understand the architecture documentation. Use acronyms consistently throughout the document as the standard terminology, defining them only one time here.
Motivation. Establish a shared vocabulary by maintaining definitions for important terms, abbreviations, and acronyms.
Form. A table containing a term with its definition. Add additional columns for multiple language translations.
Summary
That’s it, enjoy!
Summary
That’s it, enjoy!
References
Arc42 Documentation. (n.d.). https://docs.arc42.org/home/
C4 Model. (n.d.). https://c4model.com/
ISO 25010. (n.d.). https://iso25000.com/index.php/en/iso-25000-standards/iso-25010
Roos, P. (2025, January 17). The Ultimate Guide to Software Architecture Documentation. workingsoftware.dev. https://www.workingsoftware.dev/software-architecture-documentation-the-ultimate-guide/?utm_source=chatgpt.com
