arc42 Template

The arc42 template follows a standardized structure consisting of 12 main sections. When using this template, you will populate the following chapters to describe your architecture:

1. Introduction and Goals: Purpose and objectives.
2. Architecture Constraints: Technical or business constraints.
3. Context and Scope: System boundaries and external actors/systems.
4. Solution Strategy: High-level approach and design principles.
5. Building Block View: Static structure of the system.
6. Runtime View: Dynamic behavior and interactions.
7. Deployment View: Mapping software to hardware/infrastructure.
8. Concepts: Cross-cutting architectural patterns or principles.
9. Architecture Decisions: Key decisions made during design.
10. Quality Requirements: Non-functional requirements (e.g., performance, security).
11. Technical Risks: Identified risks and mitigation strategies.
12. Glossary: Definitions of terms used in the documentation.

The Solution Strategy section provides a brief summary and explanation of the fundamental decisions and strategies that shape the system's architecture. These decisions serve as the pillars of the software architecture and form the basis for many subsequent detailed decisions or implementation rules.

Key elements to include in this section are:

• Technological decisions: Choices regarding the tech stack and tools.
• Top-level decomposition decisions: High-level architectural patterns or design choices (e.g., microservices vs. monolith).
• Quality goal decisions: How the architecture is designed to achieve specific quality requirements (e.g., scalability, security).
• Organizational decisions: Choices regarding development processes or delegating tasks to third parties.

Best Practice: Keep explanations of these key decisions short. Describe how and why decisions were made in the context of the problem, quality goals, and constraints, then refer to more detailed sections for specifics.

The Deployment View describes the technical infrastructure required to run your system and how software building blocks map to that infrastructure.

Use this section to document:

1. Technical Infrastructure: Geographic locations, environments (e.g., development, testing, production), computers, processors, network channels, and topologies.
2. Mapping: How software building blocks (artifacts) are assigned to specific infrastructure elements.

When to prioritize this view:

• When your software runs as a distributed system across multiple computers, processors, servers, or containers.
• When you are designing custom hardware, processors, or microchips.
• When the underlying infrastructure significantly impacts system quality attributes or cross-cutting concerns.

Note for Software Architects: You only need to cover the infrastructure elements necessary to demonstrate the deployment of your software building blocks. Hardware architects may provide more granular detail.

The Deployment View describes the technical infrastructure on which the system runs. It maps software building blocks to specific infrastructure elements.

What to document:

• Infrastructure elements: Geographic locations, environments (development, testing, production), computers, processors, network channels, and topologies.
• Mapping: How software components/artifacts are deployed onto the infrastructure elements.
• Environments: If the system runs in multiple environments (e.g., Dev, Test, Prod), all relevant environments should be documented.

When to use it:

• When the software is a distributed system (multiple computers, processors, servers, or containers).
• When custom hardware, processors, or chips are being designed.
• When the infrastructure impacts the system or cross-cutting concerns.

Recommended Formats:

• UML Deployment Diagrams: The standard way to express this perspective. Use nested diagrams for complex infrastructure.
• Alternative Diagrams: If hardware stakeholders prefer other formats, use any diagram type capable of showing nodes and infrastructure channels.

Use the 'Architecture Constraints' section to document any requirements that limit a software architect's freedom to design and implement solutions or development processes. These constraints may be system-specific or apply to entire organizations.

Recommended Format

• Use simple tables to list constraints along with explanations.
• Categorize constraints to improve clarity. Common categories include:
  • Technical constraints: e.g., specific technologies, frameworks, or hardware requirements.
  • Organizational constraints: e.g., team structures or resource availability.
  • Political constraints: e.g., compliance, legal, or regulatory requirements.
  • Agreements: e.g., programming guidelines, version control standards, documentation requirements, or naming conventions.

Motivation

Defining constraints ensures architects know exactly where they have design freedom and where they must adhere to predefined boundaries. While constraints are often non-negotiable, identifying them clearly allows them to be used as subjects for negotiation if necessary.

The Solution Strategy section provides a short summary and explanation of the fundamental decisions and strategies that shape the system architecture. These decisions serve as the cornerstones for the architecture and form the foundation for detailed implementation rules.

When documenting your solution strategy, include:

• Technology decisions: The core technologies chosen for the system.
• Top-level decomposition: Decisions regarding architectural or design patterns (e.g., microservices, layered architecture).
• Quality goal achievement: How the architecture is designed to meet key quality requirements (e.g., scalability, security, maintainability).
• Organizational decisions: Relevant decisions such as the selected development process or the delegation of tasks to third parties.

Best Practices:

• Keep it short: Explanations of key decisions should be concise.
• Motivate decisions: For every key decision, explain what was decided and why it was decided that way, specifically referencing the problem statement, quality goals, and key constraints.
• Cross-reference: Refer to more detailed explanations in subsequent sections of the documentation.

Use Section 2 to document any requirements that limit the design and implementation decisions of software architects or the development process. These constraints may apply to a single system or extend across an entire organization.

What to include:

• Technical constraints: e.g., specific frameworks, hardware limitations, or required protocols.
• Organizational constraints: e.g., team structures, required development methodologies, or resource availability.
• Political or Convention-based constraints: e.g., coding standards, naming conventions, documentation requirements, or specific versioning policies.

Recommended Format:

A table containing all identified constraints along with a clear explanation for each. If the list is extensive, categorize them into technical, organizational, or political/convention groups.

For more detailed guidance, refer to the official arc42 documentation: https://docs.arc42.org/section-2/[Architecture Constraints].

The Building Block View provides a static decomposition of the system into building blocks (e.g., modules, components, subsystems, classes, interfaces, layers, etc.) and their dependencies. It is a mandatory part of arc42 documentation, acting like a 'floor plan' for your architecture.

It uses a hierarchical approach of White Boxes and Black Boxes:

• Level 1 (System White Box): A high-level view of the entire system. It includes an overview diagram, the motivation for the decomposition, and a Black Box description of all contained building blocks.
• Level 2 (Sub-component White Boxes): Scales up specific building blocks from Level 1. It provides a White Box description (internal structure) for selected blocks and a Black Box description for their internal components.
• Level 3+: Further refinement of Level 2 blocks. You can add more levels by copying the existing structure.

Strategy: Prefer relevance over completeness. Only create detailed White Box descriptions for blocks that are important, unexpected, risky, complex, or unstable. Exclude simple, standard, or trivial parts of the system.

Cross-cutting concepts (Наскрізні концепції) represent the fundamental rules, ideas, and decisions that apply to multiple parts of your system. They are essential for maintaining conceptual integrity (consistency and homogeneity) across the architecture and contribute significantly to the system's internal quality.

Common topics for cross-cutting concepts include:

• Domain models: Core models used throughout the system.
• Architecture or design patterns: Structural rules applied across modules.
• Technology usage rules: Specific ways a technology must be used.
• Technical decisions: Fundamental technical choices that affect multiple components.
• Implementation rules: Standards for how code should be written or structured.
• Security/Safety: Concerns that cannot be isolated to a single building block.

These concepts can be documented in various forms, such as conceptual documents, model fragments, implementation samples, or references to standard framework usage (e.g., how Hibernate is used for ORM).