# High-Level Design: [Solution name]

> High-level design (HLD) for one solution: the level below the Solution
> Architecture Document and above the per-component low-level designs. It
> fixes the components and their responsibilities, the interfaces between
> them, the data flows, the deployment and environment view, how each
> non-functional requirement is allocated to components, and the security,
> resilience and operability design that every build team must follow.
> Views are organised with the concepts of ISO/IEC/IEEE 42010:2022
> (stakeholders, concerns, viewpoints and views) and drawn in the style of
> the C4 model (context, container and deployment diagrams). Replace every
> `[bracketed]` value and every row marked *Example*.

<!--
Guidance: How to use this template
- Write one HLD per solution or per major release of a solution. The
  Solution Architecture Document (`architecture/solution-architecture`)
  says why and what at business and enterprise level; this HLD says how
  the solution is built, at the level of components, interfaces and
  infrastructure. Each component then gets its own Low-Level Design
  (`architecture/low-level-design`).
- Fill section 2 (drivers) from the SAD and the NFR Catalogue
  (`requirements/nfr-catalogue`) before you draw anything. A component
  diagram without drivers cannot be reviewed.
- Every component in section 5 needs one owner team, every interface in
  section 6 needs a provider and a consumer, and every Must NFR needs at
  least one row in section 9. Empty cells are review findings.
- Record significant choices as ADRs and list them in the Architecture
  Decision Log (`architecture/architecture-decision-log`); section 14
  only points to them.
- How this differs from neighbours: Technical Design Doc
  (`architecture/technical-design-doc`) is a narrative design for one
  feature or service change; Software Design Description
  (`architecture/software-design-description`) is a full IEEE 1016 style
  description of one software system; C4 Architecture
  (`architecture/c4-architecture`) is a diagram set at all four levels.
  The HLD is the solution-wide build blueprint that integrates them.
-->

## Document control

<!-- Guidance: Identify the solution, the SAD version this HLD implements and who signs it off. A change to the component list, an external interface or the deployment topology is a new major version. -->

| Field | Value |
|---|---|
| Document ID | [HLD-001] |
| Solution name | [Solution name] |
| Release or increment | [Release 1 / MVP / Phase 2] |
| Implements SAD | [SAD document ID and version] |
| Version | [0.1] |
| Status | [Draft / In review / Approved / Superseded] |
| Owner | [@solution-architect] |
| Approvers/reviewers | [@enterprise-architect], [@security-architect], [@lead-engineer], [@operations-lead], [@data-architect] |
| Delivery model | [In-house / Systems integrator / Mixed] |
| Last updated | YYYY-MM-DD |
| Classification | [Internal / Confidential] |
| Related documents | [NFR Catalogue ID], [Decision Log ID], [Interface Control Documents], [LLD IDs] |

### Approvals

| Role | Name | Decision | Date |
|---|---|---|---|
| Solution architect (author) | [@name] | [Submitted] | YYYY-MM-DD |
| Enterprise or domain architect | [@name] | [Approve / Approve with conditions / Reject] | YYYY-MM-DD |
| Security architect | [@name] | [Decision] | YYYY-MM-DD |
| Engineering lead | [@name] | [Decision] | YYYY-MM-DD |
| Operations or SRE lead | [@name] | [Decision] | YYYY-MM-DD |
| Architecture review board | [@name] | [Decision and condition IDs] | YYYY-MM-DD |

### Revision history

| Version | Date | Author | Change summary |
|---|---|---|---|
| 0.1 | YYYY-MM-DD | [@name] | First draft for design review |
| 0.2 | YYYY-MM-DD | [@name] | *Example:* Review comments from security and operations addressed |
| 1.0 | YYYY-MM-DD | [@name] | *Example:* Approved by the architecture review board with two conditions |

## Contents

<!-- Guidance: Keep this list in step with the headings. Delete a section only if you state in section 1.2 why it does not apply. -->

1. [Introduction and scope](#1-introduction-and-scope)
2. [Architecture drivers and SAD traceability](#2-architecture-drivers-and-sad-traceability)
3. [Stakeholders, concerns and views](#3-stakeholders-concerns-and-views)
4. [System context](#4-system-context)
5. [Logical architecture and components](#5-logical-architecture-and-components)
6. [Interfaces summary](#6-interfaces-summary)
7. [Data architecture and data flows](#7-data-architecture-and-data-flows)
8. [Deployment and environments](#8-deployment-and-environments)
9. [NFR allocation and design tactics](#9-nfr-allocation-and-design-tactics)
10. [Security design](#10-security-design)
11. [Resilience, availability and recovery](#11-resilience-availability-and-recovery)
12. [Operability and observability](#12-operability-and-observability)
13. [Transition, migration and rollout](#13-transition-migration-and-rollout)
14. [Design decisions](#14-design-decisions)
15. [Risks, assumptions and open issues](#15-risks-assumptions-and-open-issues)
16. [Traceability matrix](#16-traceability-matrix)
17. [Design review checklist and LLD hand-off](#17-design-review-checklist-and-lld-hand-off)
18. [Glossary and references](#18-glossary-and-references)

## 1. Introduction and scope

<!-- Guidance: Say what this HLD covers and what it deliberately leaves to the SAD above and the LLDs below. Pitfall: an HLD that restates the business case; link to the SAD instead. -->

### 1.1 Purpose and audience

This document describes how [Solution name] is structured and deployed so
that build teams can produce low-level designs and code without
re-deciding the architecture, and so that security, operations and
reviewers can check that the solution meets its non-functional
requirements. Primary readers are the engineering leads of each component
team, the platform and operations teams, the security architect and the
architecture review board.

### 1.2 Scope

| In scope | Out of scope |
|---|---|
| *Example:* Order capture, payment orchestration, fulfilment integration and customer notifications for the Order Hub | Warehouse management system internals (owned by the logistics programme) |
| *Example:* Production, pre-production and test environments in the primary and secondary regions | Developer workstation setup |
| *Example:* Migration of open orders from the legacy order system | Historical order archive older than seven years |
| [Item] | [Item] |

### 1.3 Position in the document set

| Document | Level | Answers | Relation to this HLD |
|---|---|---|---|
| Solution Architecture Document (`architecture/solution-architecture`) | Solution, business and enterprise | Why, what, options, cost, principles | Parent: this HLD implements its chosen option |
| NFR Catalogue (`requirements/nfr-catalogue`) | Requirements | How well, measured how | Input: section 9 allocates its IDs |
| Quality Attributes (`requirements/quality-attributes`) | Requirements | Scenarios and priorities | Input: (H,H) scenarios drive section 9 tactics |
| Architecture Decision Log (`architecture/architecture-decision-log`) | Governance | Which decisions, status | Companion: section 14 lists the IDs |
| Interface Control Document (`architecture/interface-control-document`) | Interface | Exact contract of one interface | Child: one per external interface in section 6 |
| Low-Level Design (`architecture/low-level-design`) | Component | How one component is built | Child: one per component in section 5 |

### 1.4 Design summary

[Three to six sentences that a reviewer can read on their own.] *Example:*
Order Hub is a set of four services behind an API gateway, deployed on a
managed Kubernetes platform in two regions (active and warm standby).
Orders are written to a managed relational database and published as
events through a transactional outbox to a managed message broker, from
which fulfilment, notification and analytics consumers read. Payment intent
creation is a synchronous call, through the Payment orchestrator, to the
payment service provider with a timeout set above the measured p99; the
authorisation result returns asynchronously as an event.
All service-to-service calls are authenticated with workload identities
issued by the enterprise identity provider.

## 2. Architecture drivers and SAD traceability

<!-- Guidance: List only the drivers that shape the structure: the SAD decisions, the top NFRs, constraints and principles. Each row must be visible later in a component, interface or tactic. Pitfall: copying the whole requirements list; link to it and keep the shaping ones. -->

### 2.1 Drivers

| ID | Type | Driver | Source | Where addressed |
|---|---|---|---|---|
| DRV-001 *(Example)* | Business goal | Accept orders from web, mobile and partner channels through one API | SAD section 5 | Sections 5 and 6 |
| DRV-002 *(Example)* | Quality | NFR-PE-001 order submission p95 at or below 800 ms at peak (minimum; target 600 ms) | NFR Catalogue | Section 9 |
| DRV-003 *(Example)* | Quality | NFR-RE-002 RPO 5 minutes, RTO 1 hour for order data (minimum) | NFR Catalogue | Section 11 |
| DRV-004 *(Example)* | Constraint | Card data must not enter the solution (payment page hosted by the provider) | Security policy | Section 10 |
| DRV-005 *(Example)* | Constraint | Run on the corporate managed Kubernetes platform | Technology standards | Section 8 |
| DRV-006 *(Example)* | Principle | Integrate asynchronously unless the user waits for the answer | Architecture principles | Section 6 |
| [DRV-NNN] | [Type] | [Driver] | [Source] | [Section] |

### 2.2 Constraints, assumptions and dependencies

| ID | Kind | Statement | Owner | Impact if wrong |
|---|---|---|---|---|
| CON-001 *(Example)* | Constraint | Data must remain in [jurisdiction] | Legal | Region choice in section 8 changes |
| ASM-001 *(Example)* | Assumption | The payment provider sandbox is available from sprint 2 | Programme | Integration testing slips |
| DEP-001 *(Example)* | Dependency | Enterprise identity provider supports workload identity federation | Identity team | Section 10 design changes |
| [ID] | [Kind] | [Statement] | [@owner] | [Impact] |

## 3. Stakeholders, concerns and views

<!-- Guidance: ISO/IEC/IEEE 42010:2022 separates the concerns stakeholders hold from the views that address them. Name the concerns, then show which section is the view for each. Pitfall: drawing diagrams nobody asked for while a real concern (for example cost, or support handover) has no view. -->

| Stakeholder | Key concerns | Viewpoint used | View in this HLD |
|---|---|---|---|
| *Example:* Product owner | Which channels and journeys are covered | Context | Section 4 |
| *Example:* Engineering leads | Component boundaries, contracts, ownership | Logical, interface | Sections 5 and 6 |
| *Example:* Data protection officer | Personal data locations, retention, transfers | Information | Section 7 |
| *Example:* Platform and operations | Runtime footprint, environments, monitoring, on-call | Deployment, operational | Sections 8 and 12 |
| *Example:* Security architect | Trust boundaries, identity, data protection | Security | Section 10 |
| *Example:* Service owner | Availability, recovery objectives, support model | Resilience | Section 11 |
| [Stakeholder] | [Concerns] | [Viewpoint] | [Section] |

Diagram conventions: boxes are runtime containers or external systems,
arrows show the direction of the request or event with its protocol, and
dashed boundaries are trust or network zones. Every element in a diagram
appears in a catalogue table with the same name.

## 4. System context

<!-- Guidance: Show the solution as one box with the people and systems around it. Questions: who uses it, what does it call, what calls it, which of these are outside your control? Pitfall: hiding a critical external dependency (identity provider, payment provider) because it seems obvious. -->

```mermaid
flowchart LR
  C["Customer<br/>(web and mobile)"] -->|HTTPS| OH["Order Hub<br/>[solution]"]
  P["Partner marketplace"] -->|HTTPS API| OH
  A["Customer service agent"] -->|HTTPS| OH
  OH -->|HTTPS| PSP["Payment service provider<br/>[external]"]
  OH -->|Events| WMS["Warehouse management system"]
  OH -->|SMTP and push API| NS["Notification provider<br/>[external]"]
  OH -->|OIDC| IDP["Enterprise identity provider"]
  OH -->|Events| DWH["Analytics platform"]
  ERP["ERP finance"] -->|Batch file| OH
```

| Element | Type | Relationship | Owner | Criticality |
|---|---|---|---|---|
| Customer *(Example)* | Person | Places and tracks orders | Not applicable | High |
| Partner marketplace *(Example)* | External system | Submits orders on behalf of customers | Partner | High |
| Payment service provider *(Example)* | External system | Authorises and captures payments | Vendor | High |
| Warehouse management system *(Example)* | Internal system | Receives orders to fulfil, returns shipment events | Logistics IT | High |
| Enterprise identity provider *(Example)* | Internal system | Authenticates users and workloads | Identity team | High |
| [Element] | [Type] | [Relationship] | [Owner] | [High / Medium / Low] |

## 5. Logical architecture and components

<!-- Guidance: Decompose the solution into deployable containers and the main components inside them. One component, one owner, one clear responsibility. Questions: what does each component own (data, rules)? What must it never do? Pitfall: a "common" or "utility" service that every component calls and nobody owns. -->

```mermaid
flowchart TB
  subgraph Edge["Edge zone"]
    GW["API gateway"]
    WEB["Web front end"]
  end
  subgraph App["Application zone"]
    ORD["Order service"]
    PAY["Payment orchestrator"]
    FUL["Fulfilment adapter"]
    NOT["Notification service"]
  end
  subgraph Data["Data zone"]
    DB[("Order database")]
    MQ[["Message broker"]]
    CACHE[("Cache")]
  end
  WEB --> GW
  GW --> ORD
  ORD -->|create intent| PAY
  PAY -->|PaymentAuthorised| MQ
  MQ --> ORD
  ORD --> DB
  ORD -->|outbox relay| MQ
  ORD --> CACHE
  MQ --> FUL
  MQ --> NOT
  PAY -->|HTTPS| PSPX["Payment provider"]
  FUL -->|Events| WMSX["Warehouse system"]
```

### 5.1 Component catalogue

| ID | Component | Responsibility | Owns data | Technology | Owner team | LLD |
|---|---|---|---|---|---|---|
| CMP-001 *(Example)* | API gateway | Routing, authentication of callers, rate limits, request size limits | None | Managed gateway | Platform | Configuration spec |
| CMP-002 *(Example)* | Order service | Order lifecycle, validation, pricing snapshot, outbox | Orders, order lines | [Language and framework], container | Orders team | LLD-002 |
| CMP-003 *(Example)* | Payment orchestrator | Payment intent, authorise, capture, refund, reconciliation feed | Payment references (no card data) | Container | Payments team | LLD-003 |
| CMP-004 *(Example)* | Fulfilment adapter | Translate order events to warehouse messages and back | Shipment status | Container | Integration team | LLD-004 |
| CMP-005 *(Example)* | Notification service | Customer emails and push messages from events | Notification log (90 days) | Container | Orders team | LLD-005 |
| [CMP-NNN] | [Name] | [Responsibility] | [Data] | [Technology] | [Team] | [LLD ID] |

### 5.2 Responsibility rules

- *Example:* Only the Order service writes order state; every other
  component reads it through the API or the order events.
- *Example:* The Payment orchestrator is the only component that calls
  the payment provider; no other component holds provider credentials.
- *Example:* Adapters translate formats but hold no business rules.
- [Rule]

## 6. Interfaces summary

<!-- Guidance: List every interface between components and with external systems. Detailed contracts live in ICDs, OpenAPI or AsyncAPI files; this table gives the shape and the quality of service. Pitfall: missing the error, retry and versioning behaviour, which is where integrations fail. -->

| ID | Provider | Consumer | Purpose | Style and protocol | Contract | Sync or async | Volume and latency target | Security | Versioning |
|---|---|---|---|---|---|---|---|---|---|
| IF-001 *(Example)* | Order service | Web, mobile, partners via gateway | Create and query orders | REST over HTTPS, JSON | OpenAPI file `orders-v1` | Sync | 50 req/s peak, p95 800 ms | OAuth 2.0 tokens, scopes | URI major version |
| IF-002 *(Example)* | Payment provider | Payment orchestrator | Create intent, authorise, capture | REST over HTTPS, plus provider webhook for the authorisation result | Provider API version [x] | Sync (intent), async (webhook) | Intent creation p95 320 ms, timeout 400 ms; capture 3 s timeout, off the request path | Mutual TLS and API key in vault; webhook signature checked | Provider controlled |
| IF-003 *(Example)* | Order service | Fulfilment, notification, analytics | Order lifecycle events | Events on broker topic `order.events` | AsyncAPI file `order-events` | Async, at least once | 60 msg/s peak (one OrderConfirmed per order at the NFR-PE-002 target of 60 orders/s, cancellations far fewer) | Workload identity, topic ACLs | Schema registry, backward compatible |
| IF-004 *(Example)* | ERP finance | Order service | Daily price list | SFTP batch file, CSV | ICD-004 | Batch, 02:00 | 1 file per day, under 50 MB | Key-based SFTP, checksum | File layout version field |
| IF-005 *(Example)* | Payment orchestrator | Order service | Create payment intent | REST over HTTPS, JSON (internal) | OpenAPI file `payments-internal-v1` | Sync | 60 req/s peak, p95 350 ms including IF-002; caller timeout 450 ms | Workload identity tokens, service-level policy | URI major version |
| IF-006 *(Example)* | Payment orchestrator | Order service | PaymentAuthorised and PaymentFailed events | Events on broker topic `payment.events` | AsyncAPI file `payment-events` | Async, at least once | 60 msg/s peak | Workload identity, topic ACLs | Schema registry, backward compatible |
| [IF-NNN] | [Provider] | [Consumer] | [Purpose] | [Style] | [Contract] | [Mode] | [Target] | [Security] | [Policy] |

Integration rules that apply to every interface: [idempotency keys on
all create operations], [correlation ID propagated end to end],
[timeouts set below the caller's own deadline and above the provider's
measured p99], [no inline retry where a retry would breach the caller's
deadline], [no breaking change
without a new major version and a deprecation period of N months, see
API Deprecation Policy (`architecture/api-deprecation-policy`)].

## 7. Data architecture and data flows

<!-- Guidance: Show where data lives, who owns it, how it moves and how long it is kept. Questions: where is personal data? Which store is the system of record? What is copied, and how is it kept consistent? Pitfall: two components writing the same table. -->

### 7.1 Data stores

| Store | Technology | System of record for | Owner component | Classification | Retention | Backup |
|---|---|---|---|---|---|---|
| Order database *(Example)* | Managed relational database | Orders, lines, status history | CMP-002 | Confidential, personal data | 7 years then anonymise | Point-in-time recovery, 35 days |
| Message broker *(Example)* | Managed broker | Nothing (transport only) | Platform | Confidential | 7 days | Not backed up; replay from outbox |
| Cache *(Example)* | Managed in-memory store | Nothing (derived) | CMP-002 | Internal | 15 minute TTL | None |
| [Store] | [Technology] | [Entities] | [CMP-NNN] | [Class] | [Period] | [Method] |

### 7.2 Data flows

| ID | From | To | Data | Mechanism | Frequency | Personal data | Cross-border |
|---|---|---|---|---|---|---|---|
| DF-001 *(Example)* | Customer | Order service | Order, delivery address, contact | IF-001 | Per order | Yes | No |
| DF-002 *(Example)* | Order service | Analytics platform | Order events with customer ID pseudonymised | IF-003 | Near real time | Pseudonymised | No |
| DF-003 *(Example)* | Notification service | Notification provider | Email address, order summary | Provider API | Per event | Yes | [Yes: provider region, transfer basis] |
| [DF-NNN] | [From] | [To] | [Data] | [Mechanism] | [Frequency] | [Yes / No] | [Yes / No] |

### 7.3 Key flow: place order

Draw one sequence per journey that crosses three or more components or
any external system. *Example:* the place-order flow below shows the
synchronous payment step and the asynchronous event publication.

```mermaid
sequenceDiagram
  autonumber
  participant C as Customer app
  participant G as API gateway
  participant O as Order service
  participant P as Payment orchestrator
  participant S as Payment provider
  participant D as Order database
  participant B as Message broker
  C->>G: POST /orders (idempotency key)
  G->>O: Forward with verified token
  O->>D: Insert order PENDING_PAYMENT
  O->>P: Create payment intent (IF-005, timeout 450 ms)
  P->>S: Create intent (IF-002, timeout 400 ms)
  S-->>P: Intent ID and redirect URL
  P-->>O: Intent ID and redirect URL
  O-->>C: 201 Created with payment redirect
  C->>S: Customer pays on the provider page
  S->>P: Authorisation webhook (IF-002)
  P->>B: PaymentAuthorised event (IF-006)
  B->>O: Deliver PaymentAuthorised
  O->>D: Update CONFIRMED and write outbox row
  O->>B: Outbox relay publishes OrderConfirmed (IF-003)
```

## 8. Deployment and environments

<!-- Guidance: Show where each container runs, in which network zone and region, and how environments differ. Questions: what is shared with other solutions? What is the scaling unit? Pitfall: a production topology that no lower environment resembles, so failover is never tested. -->

```mermaid
flowchart TB
  subgraph R1["Region 1 (active)"]
    subgraph K1["Kubernetes cluster, namespace order-hub"]
      O1["Order service x3"]
      P1["Payment orchestrator x2"]
      F1["Fulfilment adapter x2"]
      N1["Notification service x2"]
    end
    DB1[("Primary database, multi-zone")]
    MQ1[["Broker, multi-zone"]]
  end
  subgraph R2["Region 2 (warm standby)"]
    K2["Cluster scaled to minimum"]
    DB2[("Cross-region replica")]
  end
  LB["Global load balancer and WAF"] --> K1
  LB -.failover.-> K2
  DB1 -.async replication.-> DB2
```

| Environment | Purpose | Topology | Data | Access | Refresh |
|---|---|---|---|---|---|
| Development *(Example)* | Team integration | Single zone, shared cluster | Synthetic | Developers | Continuous |
| Test *(Example)* | System and integration test | Single region, multi-zone | Synthetic and masked | Delivery team | Weekly |
| Pre-production *(Example)* | Performance, failover and release rehearsal | Same as production, smaller scale | Masked production copy | Restricted | Per release |
| Production *(Example)* | Live service | Two regions as above | Live | Break-glass and pipeline only | Not applicable |
| [Environment] | [Purpose] | [Topology] | [Data] | [Access] | [Refresh] |

Infrastructure foundation: the solution is deployed into the landing zone
described in Landing Zone Design (`architecture/landing-zone-design`)
and Infrastructure Design (`architecture/infrastructure-design`); this
section lists only what the solution adds.

## 9. NFR allocation and design tactics

<!-- Guidance: For every Must and Should NFR, name the components that carry it, the tactic used and how it will be verified. A budget split across components (for example latency) must add up. Pitfall: allocating an NFR to "the whole system", which means nobody is accountable. -->

| NFR ID | Requirement (short) | Allocated to | Budget or share | Tactic | Verification |
|---|---|---|---|---|---|
| NFR-PE-001 *(Example)* | Order submit p95 at or below 800 ms | CMP-001, CMP-002, CMP-003 | Gateway 50 ms, Order service 300 ms, payment intent 350 ms p95 (IF-005 timeout 450 ms, at measured p99) | Connection pooling, no synchronous calls except payment intent, cached price lookups, no inline retry | Load test in pre-production at 2x peak |
| NFR-RE-001 *(Example)* | Monthly availability 99.9 % for order capture | CMP-001, CMP-002, CMP-003, database, payment provider | Gateway 99.99 %, Order service 99.98 %, Payment orchestrator 99.98 %, database 99.99 %, payment provider 99.97 % per its SLA [x]; product about 99.91 % | Multi-zone deployment, health-based routing, outbox so the broker is off the serial path, graceful degradation of notifications | SLO dashboard, provider SLA reports, game day |
| NFR-RE-002 *(Example)* | RPO 5 min, RTO 1 h | Database, platform | Not applicable | Cross-region replica, scripted failover runbook | Failover test each half year |
| NFR-SE-003 *(Example)* | All personal data encrypted at rest and in transit | All stores and interfaces | Not applicable | Platform encryption with managed keys, TLS 1.2 or later | Configuration scan, design review |
| NFR-MA-002 *(Example)* | A new sales channel can be added without changing the Order service | CMP-001, CMP-002 | Not applicable | Channel-neutral API, channel ID in the contract | Architecture review of the next channel |
| [NFR-XX-NNN] | [Short statement] | [CMP IDs] | [Budget] | [Tactic] | [Method] |

Allocate budgets against the minimum acceptable value in the NFR
Catalogue and design towards the target. Adding p95 values is
conservative (the p95 of a sum is usually below the sum of the p95s), so
a budget that fits by addition fits in practice. *Example* checks for
Order Hub:

- Latency budget: 50 + 300 + 350 = 700 ms p95, which leaves 100 ms
  inside the 800 ms minimum. The 600 ms target is a design aim, verified
  in the first performance test.
- Timeout path: the Order service waits at most 450 ms for IF-005, so a
  request whose payment call times out returns its 503 within
  50 + 300 + 450 = 800 ms, still inside the minimum. The Payment
  orchestrator's own timeout to the provider (400 ms) is below the
  450 ms its caller allows, and its internal overhead is budgeted at
  30 ms p95 (320 + 30 = 350 ms).
- Retries: one inline retry would take the worst case to
  50 + 300 + 450 + 450 = 1,250 ms, so there is none on the request path.
  The client retries with the same idempotency key. With the timeout at
  the measured p99, about 1 % of intent calls are expected to time out;
  RSK-001 tracks this.
- Availability: unavailability adds approximately for serial
  dependencies: 0.01 + 0.02 + 0.02 + 0.01 + 0.03 = 0.09 %, so the product
  is about 99.91 %, inside the 99.9 % minimum but below the 99.95 %
  target. The broker is not in the product because the outbox decouples
  it (ADR-003), and the identity provider is not because token keys are
  cached for 10 minutes (LLD-002 section 12). Reaching the target needs a
  stronger provider SLA or a second provider; see ISS-002.

## 10. Security design

<!-- Guidance: Describe trust boundaries, identities, data protection and the controls that each component must implement. Link the threat model rather than repeating it. Pitfall: listing controls without saying which component implements them. -->

### 10.1 Trust boundaries and identity

| Boundary | Crossed by | Authentication | Authorisation | Notes |
|---|---|---|---|---|
| Internet to edge *(Example)* | IF-001 | OIDC for customers and agents, OAuth 2.0 client credentials for partners | Scopes checked at gateway, ownership checked in Order service | WAF and rate limits at the edge |
| Edge to application *(Example)* | Internal calls, IF-005, IF-006 | Workload identity tokens | Service-level policy | No network trust assumed |
| Application to external provider *(Example)* | IF-002 | Mutual TLS and API key from secrets vault | Provider account | Key rotation every 90 days |
| [Boundary] | [Interfaces] | [Method] | [Model] | [Notes] |

### 10.2 Security controls by component

| Control | Requirement | Implemented by | Evidence |
|---|---|---|---|
| Input validation against schema *(Example)* | NFR-SE-001 | CMP-001 and CMP-002 | Contract tests, security test cases |
| Secrets in managed vault, never in images *(Example)* | NFR-SE-004 | All components | Pipeline secret scan |
| Audit log of agent actions on orders *(Example)* | NFR-SE-006 | CMP-002 | Log review in test |
| [Control] | [NFR ID] | [CMP IDs] | [Evidence] |

Threat model: [link to Threat Model (`security/threat-model`)]. Security
reference architecture: [link to Security Architecture
(`security/security-architecture`)].

## 11. Resilience, availability and recovery

<!-- Guidance: Give each component a criticality tier, its recovery objectives and what happens when each dependency fails. Use the tier names and objectives of the organisation's tier model unchanged; a component that needs different values needs a different tier or an exception. The failure table is the most reviewed part of an HLD. Pitfall: an RTO for the solution that is shorter than the RTO of a dependency it cannot run without. -->

Tiers use the T0 to T4 model of Resilience Tiering and HA/DR Design
(`architecture/resilience-tiering-ha-dr-design`): *Example* values T1
RTO 1 h, RPO 5 min; T2 RTO 8 h, RPO 1 h; T3 RTO 72 h, RPO 24 h.

| Component | Tier | RTO | RPO | Redundancy | Degraded mode |
|---|---|---|---|---|---|
| CMP-001 API gateway *(Example)* | T1 | 1 h | Not applicable (no data) | Managed, multi-zone, deployed in both regions | None: no order capture without it |
| CMP-002 Order service *(Example)* | T1 | 1 h | 5 min | Three replicas over three zones, standby region | Read-only order tracking if database is read-only |
| CMP-003 Payment orchestrator *(Example)* | T1 | 1 h | 5 min | Two replicas over two zones, standby region; provider has its own SLA | Orders held as pending payment for 30 min |
| CMP-004 Fulfilment adapter *(Example)* | T2 | 8 h | 1 h | Two replicas | Order events wait on the broker; warehouse receives them late |
| CMP-005 Notification service *(Example)* | T3 | 72 h | 24 h | Two replicas | Messages queue on the broker and send later; the order status page stays correct |
| [CMP-NNN] | [Tier] | [Time] | [Time] | [Pattern] | [Behaviour] |

| Failure | Detection | Effect | Response |
|---|---|---|---|
| Payment provider timeout *(Example)* | Error rate and latency alert | New orders cannot complete payment | Circuit breaker opens, customer sees retry message, orders kept pending |
| Payment events delayed *(Example)* | Age of oldest PENDING_PAYMENT order with a provider authorisation | Customers paid but see pending | Broker redelivery; reconciliation job queries the provider after 10 min |
| Zone loss *(Example)* | Platform health checks | One third of capacity lost | Remaining replicas absorb load; autoscaling adds pods |
| Region loss *(Example)* | Synthetic checks from outside | Service down | Declare disaster, run failover runbook, target 1 h |
| Broker unavailable *(Example)* | Consumer lag and publish errors | Events delayed, orders still accepted | Outbox keeps rows; relay resumes when broker returns |
| [Failure] | [Signal] | [Effect] | [Response] |

Detailed tiering and DR design: Resilience Tiering and HA/DR Design
(`architecture/resilience-tiering-ha-dr-design`) and Disaster Recovery
Plan (`ops/disaster-recovery-plan`).

## 12. Operability and observability

<!-- Guidance: Show how the solution will be run: telemetry, alerting, runbooks, support tiers and who is on call. Questions: how does support know a customer journey is broken before customers call? Pitfall: dashboards per component but no end-to-end journey view. -->

| Aspect | Design |
|---|---|
| Telemetry *(Example)* | Every component emits traces, metrics and structured logs with OpenTelemetry; correlation ID from IF-001 carried in events |
| Service level objectives *(Example)* | Order capture availability and latency SLOs per NFR-RE-001 and NFR-PE-001, see SLO Document (`dev/slo-doc`) |
| Alerting *(Example)* | Burn-rate alerts on SLOs page the Orders on-call; component alerts create tickets |
| Journey monitoring *(Example)* | Synthetic order placed every five minutes in production using a test product |
| Runbooks *(Example)* | One runbook per alert, stored with the code; failover runbook owned by Platform |
| Support model *(Example)* | Level 1 service desk, level 2 application support, level 3 component teams |
| Capacity management *(Example)* | Monthly review of peak usage against limits, see Capacity Plan (`ops/capacity-plan`) |
| [Aspect] | [Design] |

Full telemetry design: Observability Specification
(`ops/observability-spec`). Handover to run teams: Operations Handover
(`ops/operations-handover`).

## 13. Transition, migration and rollout

<!-- Guidance: Describe how the solution goes live: coexistence with the legacy system, data migration, feature flags and the order of releases. Pitfall: a design that works only after the big-bang cutover, with no path for the months of coexistence. -->

| Step | What changes | Coexistence approach | Rollback | Plan |
|---|---|---|---|---|
| 1 *(Example)* | Order Hub live for partner channel only | Legacy system keeps web and mobile | Route partners back via gateway | Cutover Plan (`project/cutover-plan`) |
| 2 *(Example)* | Open orders migrated from legacy | Legacy read-only for migrated orders | Restore legacy write flag | Data Migration Strategy (`architecture/data-migration-strategy`) |
| 3 *(Example)* | Web and mobile switched behind feature flag | Percentage rollout 5, 25, 100 | Flag off | Release plan |
| [Step] | [Change] | [Approach] | [Rollback] | [Plan] |

## 14. Design decisions

<!-- Guidance: List the decisions that shaped this design with their status; the rationale lives in the ADRs. Pitfall: decisions made in meetings that never reach the log, then get reopened at every review. -->

| Decision ID | Decision | Status | Affects | Record |
|---|---|---|---|---|
| ADR-002 *(Example)* | Use a managed relational database for order data | Accepted | CMP-002 | ADR file |
| ADR-003 *(Example)* | Publish events with the transactional outbox pattern | Accepted | CMP-002, IF-003 | ADR file |
| ADR-004 *(Example)* | Create payment intents synchronously with a 350 ms p95 budget and 450 ms timeout | Accepted | CMP-002, CMP-003, IF-002, IF-005, NFR-PE-001 | ADR file |
| ADR-007 *(Example)* | Use the managed message broker service (supersedes ADR-001) | Accepted | IF-003 | ADR file |
| [ADR-NNN] | [Decision] | [Status] | [IDs] | [Link] |

Full list and status history: Architecture Decision Log
(`architecture/architecture-decision-log`). Record format: ADR (Full)
(`architecture/adr-full`) or MADR (`dev/madr`).

## 15. Risks, assumptions and open issues

<!-- Guidance: Keep only design risks and open design questions here; programme risks belong in the RAID log. Each open issue needs a date by which it must be closed, which is usually when the first LLD depends on it. -->

| ID | Type | Description | Impact | Response or next step | Owner | Due |
|---|---|---|---|---|---|---|
| RSK-001 *(Example)* | Risk | Payment provider intent latency exceeds 320 ms p95, or more than 1 % of IF-005 calls hit the 450 ms timeout | NFR-PE-001 missed, failed submissions | Early performance spike against sandbox; measure p95 and p99 | @payments-lead | YYYY-MM-DD |
| RSK-002 *(Example)* | Risk | Warehouse system cannot consume events at peak | Fulfilment delays | Adapter buffers and throttles; capacity test with logistics | @integration-lead | YYYY-MM-DD |
| ISS-001 *(Example)* | Open issue | Retention period for notification logs not agreed | DF-003 design | Decision by data protection officer | @dpo | YYYY-MM-DD |
| ISS-002 *(Example)* | Open issue | Serial availability product (about 99.91 %) is below the 99.95 % target | NFR-RE-001 target | Negotiate provider SLA or assess a second provider | @payments-lead | YYYY-MM-DD |
| [ID] | [Risk / Issue] | [Description] | [Impact] | [Response] | [@owner] | YYYY-MM-DD |

Programme-level items: RAID Log (`project/raid-log`).

## 16. Traceability matrix

<!-- Guidance: Show that every driver reaches a component, an interface and a test. Gaps in this matrix are the first thing a review board checks. -->

| Driver or requirement | Component | Interface | Decision | Verification |
|---|---|---|---|---|
| DRV-001 *(Example)* | CMP-001, CMP-002 | IF-001 | ADR-002 | API contract tests per channel |
| NFR-PE-001 *(Example)* | CMP-001, CMP-002, CMP-003 | IF-001, IF-005, IF-002 | ADR-004 | Performance test PT-01 |
| NFR-RE-001 *(Example)* | CMP-001, CMP-002, CMP-003, database | IF-001, IF-005, IF-002 | ADR-003, ADR-008 | SLO report, game day GD-01 |
| NFR-RE-002 *(Example)* | Database, platform | Not applicable | ADR-002 | Failover test DR-01 |
| DRV-004 *(Example)* | CMP-003 | IF-002 | [ADR ID] | Payment page review, scope check |
| [ID] | [CMP IDs] | [IF IDs] | [ADR IDs] | [Test ID] |

Requirement-level traceability: Traceability Matrix
(`requirements/traceability-matrix`).

## 17. Design review checklist and LLD hand-off

<!-- Guidance: Use the checklist before submitting for review, then give each component team the hand-off list so their LLD is consistent with this HLD. -->

### 17.1 Review checklist

- [ ] Every component has one owner, one responsibility and an LLD ID.
- [ ] Every interface has a provider, a consumer, a contract reference,
      a security method and a versioning rule.
- [ ] Every Must NFR is allocated, and latency or availability budgets
      fit within the minimum acceptable value.
- [ ] Every synchronous call has a timeout above the provider's measured
      p99 and below the caller's deadline, and the timeout path still
      fits the minimum.
- [ ] Every store has an owner, a classification, a retention period and
      a backup method.
- [ ] Every external dependency has a failure row in section 11.
- [ ] Personal data flows and any cross-border transfer are listed.
- [ ] The deployment view matches the environments that will be tested.
- [ ] Decisions are in the log with status; no open issue blocks an LLD
      without a due date.

### 17.2 Hand-off to each low-level design

Each LLD must take, as fixed inputs: its component row from 5.1, the
interfaces it provides and consumes from section 6, the NFR budgets
allocated to it in section 9, the security controls assigned in 10.2,
its tier and degraded mode from section 11 and the telemetry rules in
section 12. If an LLD needs to change any of these, the change comes back
to this HLD as a new version, not as a silent deviation.

## 18. Glossary and references

<!-- Guidance: Define the terms readers outside the team may not know and list the sources you relied on, with the version and the date you checked them. -->

### 18.1 Glossary

| Term | Meaning |
|---|---|
| HLD | High-level design: solution-wide structure, interfaces, deployment and NFR allocation |
| LLD | Low-level design: build specification for one component |
| Container | Separately deployable or runnable unit, such as a service, front end or database (C4 sense) |
| View | Part of an architecture description that addresses chosen stakeholder concerns |
| Viewpoint | Conventions for building and reading one kind of view |
| Outbox | Pattern where events are written in the same database transaction as the state change and relayed later |
| RTO and RPO | Maximum tolerated time to restore service and maximum tolerated data loss, measured in time |
| [Term] | [Meaning] |

### 18.2 References

| ID | Reference | Version or date checked | Use |
|---|---|---|---|
| REF-01 | ISO/IEC/IEEE 42010:2022, Software, systems and enterprise: Architecture description | Edition 2, November 2022 | Stakeholders, concerns, viewpoints, views |
| REF-02 | The C4 model, Simon Brown, c4model.com | Checked 2026-10-23 | Context, container and deployment diagram style |
| REF-03 | ISO/IEC 25010:2023, Product quality model | Edition 2, November 2023 | Quality characteristics used in section 9 |
| REF-04 | OpenAPI Specification, spec.openapis.org | 3.2 line | REST contract format |
| REF-05 | AsyncAPI Specification, asyncapi.com | 3.1.0 | Event contract format |
| REF-06 | [Solution Architecture Document] | [Version] | Parent document |
| REF-07 | [NFR Catalogue] | [Version] | Requirements allocated in section 9 |

## Standard and licence note

Structure aligned with ISO/IEC/IEEE 42010:2022 (stakeholders, concerns,
viewpoints and views in an architecture description) and drawing on the
C4 model by Simon Brown (c4model.com, CC BY 4.0) for the context,
container and deployment diagram style. Only concept names and clause
topics are used; no text, definitions or tables are reproduced from ISO
standards, and no C4 material is copied. This template is original text
written for this collection. Check the current editions at iso.org and
c4model.com, and obtain the standards for their normative requirements.
Template licence: MIT.