Architecture Description: [System name]
Complete architecture description for one system. The structure follows
the concepts of ISO/IEC/IEEE 42010:2022: stakeholders and their concerns
drive the choice of viewpoints, each viewpoint governs one view, and
correspondences keep the views consistent. Replace every [bracketed]
value and every row marked Example.
Document control
| Field | Value |
|---|
| Document ID | [AD-SYSTEM-001] |
| System (entity of interest) | [System name] |
| System release described | [vX.Y or "target architecture YYYY"] |
| Version | [0.1] |
| Status | [Draft / In review / Approved / Superseded] |
| Architect / owner | [@architect] |
| Classification | [Internal / Confidential / Public] |
| Last updated | YYYY-MM-DD |
Approvals
| Role | Name | Decision | Date |
|---|
| Chief / enterprise architect | [@name] | [Approved / Approved with comments / Rejected] | YYYY-MM-DD |
| Engineering lead | [@name] | [Decision] | YYYY-MM-DD |
| Security architect | [@name] | [Decision] | YYYY-MM-DD |
| Operations lead | [@name] | [Decision] | YYYY-MM-DD |
Revision history
| Version | Date | Author | Change summary |
|---|
| 0.1 | YYYY-MM-DD | [@name] | Initial description of the current architecture |
| 0.2 | YYYY-MM-DD | [@name] | Example: Added deployment view; recorded decision AD-DEC-004 |
| 1.0 | YYYY-MM-DD | [@name] | Example: Baseline approved by the architecture board |
Contents
1. Introduction
1.1 Purpose of this description
This document describes the architecture of [System name] so that
stakeholders can [understand how the system meets their concerns, assess
proposed changes, plan development and operations, support audit].
It records the fundamental concepts and properties of the system in its
environment and the principles governing its design and evolution.
1.2 Scope
- Covered: [the system boundary, for example "all services in the
order platform, their data stores and the integration with the ERP"].
- Not covered: [neighbouring systems, described elsewhere].
- Time frame: [current state as of YYYY-MM-DD / target state for
YYYY / transition states].
1.3 Architecture description framework
[Name any framework this description conforms to, for example a company
architecture framework, arc42, C4, or "none". If a framework predefines
viewpoints, list them in section 4 and mark them "from framework".]
1.4 Related documents
| ID | Document | Version / date | Relationship |
|---|
| REF-01 | [Software requirements specification] | [x.y] | Requirements this architecture satisfies |
| REF-02 | [Enterprise architecture principles] | [x.y] | Constraints and principles |
| REF-03 | [Architecture decision records] | [Location] | Detailed decisions summarised in section 7 |
| REF-04 | ISO/IEC/IEEE 42010:2022 | 2022 | Conceptual basis of this description |
2. Entity of interest and environment
2.1 System overview
[Two or three paragraphs: what the system does, for whom, its business
importance, and its main parts at the highest level. Avoid technology
names unless they are part of the mission.]
2.2 Environment
| Element of the environment | Type | Influence on the system |
|---|
| Example: Warehouse staff | People | Primary users; shift work, handheld devices |
| Example: ERP system | System | Owns master data; sets integration contract |
| Example: GDPR | Regulation | Limits where personal data may be stored |
| Example: Company cloud platform | Technology | Mandated runtime and tooling |
| [Element] | [People / System / Organisation / Regulation / Technology] | [Influence] |
2.3 Architecture drivers
[The few forces that shape this architecture most: business goals,
quality attribute priorities, hard constraints. Each driver should
appear again as a concern in section 3.]
| Driver | Type | Source |
|---|
| Example: Orders must keep flowing during an ERP outage | Quality (availability) | Business continuity plan |
| Example: Delivery by YYYY-MM with a team of 6 | Constraint (schedule) | Programme plan |
| [Driver] | [Goal / Quality / Constraint] | [Source] |
3. Stakeholders and concerns
3.1 Stakeholders
| ID | Stakeholder | Role in relation to the system |
|---|
| SH-01 | Example: Product owner | Defines functionality and priorities |
| SH-02 | Example: Development team | Builds and maintains the system |
| SH-03 | Example: Operations / SRE | Runs, monitors and recovers the system |
| SH-04 | Example: Security officer | Accountable for information security |
| SH-05 | Example: End users | Use the system daily |
| SH-06 | Example: Auditor | Verifies compliance |
| [SH-nn] | [Stakeholder] | [Role] |
3.2 Concerns
| ID | Concern | Raised by | Priority |
|---|
| CN-01 | Example: Which functions does the system provide and to whom? | SH-01, SH-05 | High |
| CN-02 | Example: How is the system decomposed and who owns each part? | SH-02 | High |
| CN-03 | Example: Can the system keep taking orders when the ERP is down? | SH-01, SH-03 | High |
| CN-04 | Example: How is personal data protected and where is it stored? | SH-04, SH-06 | High |
| CN-05 | Example: How is the system deployed, scaled and recovered? | SH-03 | Medium |
| CN-06 | Example: How fast can a new feature be released safely? | SH-01, SH-02 | Medium |
| [CN-nn] | [Concern phrased as a question] | [SH IDs] | [High / Medium / Low] |
3.3 Stakeholder and concern map
| Concern | SH-01 | SH-02 | SH-03 | SH-04 | SH-05 | SH-06 |
|---|
| CN-01 | X | | | | X | |
| CN-02 | | X | | | | |
| CN-03 | X | | X | | | |
| CN-04 | | | | X | | X |
| CN-05 | | | X | | | |
| CN-06 | X | X | | | | |
4. Architecture viewpoints
4.1 Viewpoint catalogue
| ID | Viewpoint | Concerns framed | Stakeholders | Model kinds | Origin |
|---|
| VP-01 | Context | CN-01 | SH-01, SH-05, SH-06 | System context diagram, actor list | [Framework / custom] |
| VP-02 | Functional decomposition | CN-02, CN-06 | SH-02 | Container diagram, responsibility table | [Framework / custom] |
| VP-03 | Information | CN-04 | SH-04, SH-06, SH-02 | Entity model, data classification table | [Framework / custom] |
| VP-04 | Behaviour and resilience | CN-03 | SH-01, SH-03 | Sequence diagram, failure mode table | [Framework / custom] |
| VP-05 | Deployment and operations | CN-05 | SH-03 | Deployment diagram, environment table | [Framework / custom] |
| [VP-nn] | [Viewpoint] | [CN IDs] | [SH IDs] | [Model kinds] | [Origin] |
4.2 Viewpoint specifications
Write one specification per viewpoint. The first one is a worked example.
VP-01 Context viewpoint
- Overview: shows the system as a black box with the people and
systems it interacts with.
- Concerns framed: CN-01.
- Typical stakeholders: SH-01, SH-05, SH-06.
- Model kinds: system context diagram (Mermaid flowchart or C4
context), actor and external system table.
- Conventions: rounded nodes are people, double-bordered nodes are
the system of interest, cylinders are external data owners; arrows
carry the purpose of the interaction, not the protocol.
- Analysis methods: review that every actor in the SRS appears;
check that no interaction lacks an owner.
- Correspondence rules: every external system here appears as an
integration point in VP-02 (rule CR-01).
VP-02 Functional decomposition viewpoint
- Overview: [what the view shows].
- Concerns framed: [CN IDs].
- Typical stakeholders: [SH IDs].
- Model kinds and notation: [models and how they are drawn].
- Conventions: [naming, colour, granularity rules].
- Analysis methods: [how a reviewer checks the view].
- Correspondence rules: [rules linking this view to others].
VP-03 to VP-05
[Repeat the structure above for each viewpoint in 4.1. A viewpoint
without analysis methods cannot be reviewed; add at least one.]
5. Architecture views
5.1 Context view (governed by VP-01)
| Actor or external system | Interaction | Owner |
|---|
| Example: Warehouse clerk | Creates and submits orders | Operations department |
| Example: ERP | Master data, order posting | Finance IT |
| [Element] | [Interaction] | [Owner] |
Known issues in this view: [list or "none"].
5.2 Functional decomposition view (governed by VP-02)
| Element | Responsibility | Owner team | Key interfaces |
|---|
| Example: Order service | Validate, store and publish orders | Team Orders | REST /orders, event order.submitted |
| Example: ERP adapter | Translate events to ERP calls, retry on failure | Team Integration | Queue consumer, ERP SOAP API |
| [Element] | [Responsibility] | [Team] | [Interfaces] |
Known issues in this view: [list or "none"].
5.3 Information view (governed by VP-03)
| Entity | Classification | Contains personal data | Store | Retention |
|---|
| Example: Customer | Confidential | Yes (name, address) | Order database (EU) | 7 years after last order |
| Example: Order event | Internal | No | Event queue, audit store | 1 year |
| [Entity] | [Public / Internal / Confidential / Restricted] | [Yes / No] | [Store] | [Retention] |
Known issues in this view: [list or "none"].
5.4 Behaviour and resilience view (governed by VP-04)
Order submission while the ERP is unavailable:
| Failure | Effect | Detection | Mitigation | Concern |
|---|
| Example: ERP unavailable | Orders not posted to ERP | Adapter error rate alert | Queue buffers events, retries with backoff | CN-03 |
| Example: Order database primary fails | Writes fail | Health check | Automatic failover to replica | CN-03, CN-05 |
| [Failure] | [Effect] | [Detection] | [Mitigation] | [CN ID] |
Known issues in this view: [list or "none"].
5.5 Deployment and operations view (governed by VP-05)
| Environment | Purpose | Region | Scaling | Recovery objective |
|---|
| Production | Live traffic | [EU-West] | [Horizontal, 2 to 10 pods per service] | [RTO 4 h, RPO 15 min] |
| Staging | Release verification | [EU-West] | [Fixed, 1 pod per service] | [Best effort] |
| [Environment] | [Purpose] | [Region] | [Scaling] | [Objective] |
Known issues in this view: [list or "none"].
6. Correspondences
6.1 Correspondence rules
| ID | Rule | Between | Check |
|---|
| CR-01 | Every external system in the context view has exactly one owning element in the functional view | VP-01, VP-02 | Review at each release |
| CR-02 | Every entity holding personal data is stored only in elements deployed in an EU region | VP-03, VP-05 | Review + automated policy check |
| CR-03 | Every failure mode in the behaviour view has a monitored detection signal in operations | VP-04, VP-05 | Review |
| [CR-nn] | [Rule] | [Viewpoints] | [How checked] |
6.2 Element correspondences
| Element (view) | Corresponds to (view) | Relation | Rule |
|---|
| ERP (5.1) | ERP adapter (5.2) | Owned integration | CR-01 |
| Customer (5.3) | Managed PostgreSQL in EU region (5.5) | Stored in | CR-02 |
| ERP unavailable (5.4) | Adapter error rate alert (5.5) | Detected by | CR-03 |
| [Element] | [Element] | [Relation] | [CR ID] |
6.3 Requirements traceability
| Requirement (REF-01) | Addressed by | View |
|---|
| Example: SRS-RA-010 availability 99.9% | Replicated services, queue buffering | 5.4, 5.5 |
| Example: SRS-DC-002 EU data residency | EU region deployment | 5.3, 5.5 |
| [Requirement ID] | [Architectural element or decision] | [View] |
7. Architecture decisions and rationale
| ID | Decision | Options considered | Rationale | Concerns | Status |
|---|
| AD-DEC-001 | Example: Decouple ERP posting through an event queue | Synchronous call; batch file; event queue | Keeps order capture available during ERP outages (CN-03) at the cost of eventual consistency | CN-03 | Accepted |
| AD-DEC-002 | Example: Use the managed PostgreSQL service | Self-hosted PostgreSQL; managed service; document store | Operations team size and backup requirements | CN-05 | Accepted |
| [AD-DEC-nnn] | [Decision] | [Options] | [Rationale] | [CN IDs] | [Proposed / Accepted / Superseded] |
7.1 Principles applied
| Principle | Statement | Implication for this system |
|---|
| Example: Asynchronous integration first | Integrate with slow or unreliable systems through events | ERP adapter consumes a queue |
| [Principle] | [Statement] | [Implication] |
8. Consistency and completeness
8.1 Concern coverage
| Concern | Framed by viewpoint | Addressed in view | Covered |
|---|
| CN-01 | VP-01 | 5.1 | Yes |
| CN-02 | VP-02 | 5.2 | Yes |
| CN-03 | VP-04 | 5.4 | Yes |
| CN-04 | VP-03 | 5.3 | Yes |
| CN-05 | VP-05 | 5.5 | Yes |
| CN-06 | VP-02 | 5.2 | [Partially: release process not yet described] |
8.2 Known inconsistencies and open issues
| ID | Description | Affected views | Owner | Target date |
|---|
| KI-01 | Example: Deployment view shows 3 order service pods; capacity model in REF-01 assumes 4 | 5.2, 5.5 | [@name] | YYYY-MM-DD |
| [KI-nn] | [Description] | [Views] | [@name] | YYYY-MM-DD |
8.3 Evaluation summary
[Results of any architecture evaluation (for example a scenario-based
review): date, method, participants, main risks found, and where the
follow-up actions are tracked.]
9. Appendices
9.1 Glossary
| Term | Meaning in this document |
|---|
| Entity of interest | The system whose architecture is described here |
| Stakeholder | Individual, team or organisation with an interest in the system |
| Concern | A matter of interest to one or more stakeholders |
| Viewpoint | Conventions for constructing, interpreting and analysing one kind of view |
| View | The system described from the perspective of one viewpoint |
| Correspondence | A relation between elements of different views or models |
| [Term] | [Meaning] |
9.2 Notation key
| Symbol | Meaning |
|---|
| Rounded node | Person or role |
| Double-bordered node | System of interest |
| Cylinder | Data store or external system owning data |
| Solid arrow | Request or data flow, labelled with purpose |
| Dashed arrow | Response or asynchronous return |
Standard and licence note
Structure aligned with ISO/IEC/IEEE 42010:2022, Software, systems and
enterprise: Architecture description: stakeholders, concerns,
viewpoints, views, correspondences and decision rationale. This template
is original text written for this collection and reproduces no text from
the standard; obtain the standard for its normative requirements.
Template licence: MIT.