# 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*.

<!--
Guidance: How to use this template
- Work in this order: 3 (stakeholders and concerns) -> 4 (choose viewpoints
  that frame those concerns) -> 5 (one view per viewpoint) -> 6 and 7
  (correspondences and decisions). An architecture description that starts
  with diagrams usually answers questions nobody asked.
- Every concern in section 3 must be framed by at least one viewpoint in
  section 4. Section 8 checks this.
- Diagrams use Mermaid and render in the preview and exports. Keep one
  diagram per model and name it after the model in the viewpoint table.
-->

## Document control

<!-- Guidance: Identify the architecture description itself, separately from the system it describes. Version it with the system release it describes. -->

| 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

<!-- Guidance: Record changes in architectural terms: which viewpoint, view, decision or correspondence changed and why. -->

| 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

<!-- Guidance: Keep this list aligned with the headings. -->

1. [Introduction](#1-introduction)
2. [Entity of interest and environment](#2-entity-of-interest-and-environment)
3. [Stakeholders and concerns](#3-stakeholders-and-concerns)
4. [Architecture viewpoints](#4-architecture-viewpoints)
5. [Architecture views](#5-architecture-views)
6. [Correspondences](#6-correspondences)
7. [Architecture decisions and rationale](#7-architecture-decisions-and-rationale)
8. [Consistency and completeness](#8-consistency-and-completeness)
9. [Appendices](#9-appendices)

## 1. Introduction

<!-- Guidance: Tell the reader what this description covers, for whom, and how it relates to other documents. -->

### 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

<!-- Guidance: Describe the system as a whole and everything that influences it or is influenced by it: users, neighbouring systems, organisations, regulations, technology platforms. -->

### 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

<!-- Guidance: A stakeholder is anyone with an interest in the system; a concern is a matter of interest to them. List stakeholders first, then concerns, then map them. Typical concerns: purpose, suitability, feasibility, risks, cost, maintainability, evolvability, security, privacy, performance, deployability. -->

### 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

<!-- Guidance: A viewpoint is the recipe for a view: which concerns it frames, for which stakeholders, which model kinds and notations it uses, and how to analyse it. Reuse established viewpoints where they fit (for example C4 levels, the 4+1 views, or your framework's set) and define your own only for concerns nothing else frames. -->

### 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

<!-- Guidance: One view per viewpoint. Each view states which viewpoint governs it, contains the models that viewpoint prescribes, and records known issues. Write for the stakeholders listed in the viewpoint, not for yourself. -->

### 5.1 Context view (governed by VP-01)

```mermaid
flowchart LR
  clerk([Warehouse clerk]) -->|captures orders| sys[[System name]]
  admin([Administrator]) -->|configures| sys
  sys -->|reads stock, posts orders| erp[(ERP)]
  sys -->|sends order confirmations| mail[Email service]
  idp[Identity provider] -->|signs users in| sys
```

| 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)

```mermaid
flowchart TB
  subgraph sys [System name]
    web[Web client] --> api[API gateway]
    api --> orders[Order service]
    api --> stock[Stock service]
    orders --> queue[[Event queue]]
    queue --> erpad[ERP adapter]
    orders --> odb[(Order database)]
    stock --> cache[(Stock cache)]
  end
  erpad --> erp[(ERP)]
  stock --> erp
```

| 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)

```mermaid
erDiagram
  CUSTOMER ||--o{ ORDER : places
  ORDER ||--|{ ORDER_LINE : contains
  PRODUCT ||--o{ ORDER_LINE : "appears in"
  ORDER ||--o{ ORDER_EVENT : "is audited by"
```

| 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:

```mermaid
sequenceDiagram
  actor Clerk
  participant API as API gateway
  participant Orders as Order service
  participant Q as Event queue
  participant Adapter as ERP adapter
  participant ERP
  Clerk->>API: Submit order
  API->>Orders: POST /orders
  Orders->>Orders: Validate and store
  Orders->>Q: Publish order.submitted
  Orders-->>Clerk: 201 Accepted (pending ERP)
  Q->>Adapter: Deliver event
  Adapter->>ERP: Post order
  ERP--xAdapter: Timeout
  Adapter->>Q: Requeue with backoff
  Note over Adapter,ERP: Retries until ERP recovers or the order is flagged
```

| 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)

```mermaid
flowchart LR
  subgraph cloud [Cloud region EU]
    subgraph k8s [Kubernetes cluster]
      gw[API gateway x2]
      os[Order service x3]
      ss[Stock service x2]
      ad[ERP adapter x2]
    end
    db[(Managed PostgreSQL, primary + replica)]
    mq[[Managed message queue]]
  end
  dc[On-premises data centre] --- erp[(ERP)]
  ad -->|VPN| erp
  os --> db
  os --> mq
  mq --> ad
```

| 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

<!-- Guidance: Correspondences relate elements across views and models; correspondence rules state what must hold. They are how you keep a multi-view description consistent and traceable to requirements. -->

### 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

<!-- Guidance: Summarise the decisions that shaped the views, the options considered and why the chosen option won. Link the full decision records. A decision without alternatives is a statement, not a decision. -->

| 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

<!-- Guidance: Record the checks you ran on this description and anything still unresolved. An honest list of known inconsistencies is better than a description that claims to be complete. -->

### 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

<!-- Guidance: Definitions and supporting material that would interrupt the main text. -->

### 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.