# Software Design Description: [System or component name]

> Complete software design description (SDD) for one software system or
> component. The structure follows the concepts of IEEE 1016-2009: design
> stakeholders raise design concerns, design viewpoints frame those
> concerns, and each viewpoint is realised by one design view. Replace
> every `[bracketed]` value and every row marked *Example*.

<!--
Guidance: How to use this template
- Fill sections 1 and 2 first. The concerns you list in 2.2 decide which
  viewpoints in section 3 you need; delete viewpoints that frame no concern
  and say why in 3.1.
- Each design view in section 4 must name the viewpoint that governs it and
  the concerns it answers. A view that answers no concern is noise.
- Keep rationale (section 5) next to the decisions it explains, with links
  to requirements in section 7, so reviewers can trace "why" back to "what".
- Diagrams use Mermaid and render in the preview and exports.
-->

## Document control

<!-- Guidance: Identify the SDD itself (not the software). Version it with the software release whose design it describes. -->

| Field | Value |
|---|---|
| Document ID | [SDD-SYSTEM-001] |
| Design subject | [System or component name] |
| Software release described | [vX.Y] |
| Version | [0.1] |
| Status | [Draft / In review / Approved / Superseded] |
| Issuing organisation | [Organisation or team] |
| Author / design owner | [@designer] |
| Classification | [Internal / Confidential / Public] |
| Date of issue | YYYY-MM-DD |

### Approvals

| Role | Name | Decision | Date |
|---|---|---|---|
| Lead designer | [@name] | [Approved / Approved with comments / Rejected] | YYYY-MM-DD |
| Software architect | [@name] | [Decision] | YYYY-MM-DD |
| Quality assurance | [@name] | [Decision] | YYYY-MM-DD |
| Product owner | [@name] | [Decision] | YYYY-MM-DD |

## Revision history

<!-- Guidance: Record design changes by view and decision, so a reader can see what moved between releases. -->

| Version | Date | Author | Change summary |
|---|---|---|---|
| 0.1 | YYYY-MM-DD | [@name] | Initial design description |
| 0.2 | YYYY-MM-DD | [@name] | *Example:* Added state dynamics view for order lifecycle; rationale DR-003 |
| 1.0 | YYYY-MM-DD | [@name] | *Example:* Baselined after design review DRV-02 |

## Contents

1. [Identification and overview](#1-identification-and-overview)
2. [Design stakeholders and concerns](#2-design-stakeholders-and-concerns)
3. [Design viewpoints](#3-design-viewpoints)
4. [Design views](#4-design-views)
5. [Design rationale](#5-design-rationale)
6. [Design overlays](#6-design-overlays)
7. [Traceability to requirements](#7-traceability-to-requirements)
8. [Glossary and references](#8-glossary-and-references)

## 1. Identification and overview

<!-- Guidance: Say what is designed, for which release, who issued the SDD, and what the reader needs to know before the views. -->

### 1.1 Identification

| Item | Value |
|---|---|
| Design subject | [System or component name and short identifier] |
| Version of the design subject | [vX.Y] |
| Date of issue and status | YYYY-MM-DD, [status] |
| Scope of this SDD | [Whole system / subsystem / single component] |
| Issuing organisation | [Organisation] |
| Authorship | [@name, @name] |
| Change history | See Revision history |

### 1.2 Purpose and scope

This SDD describes how [System name] is designed to satisfy the
requirements in [SRS reference]. It is the main communication vehicle
between [designers, developers, testers, maintainers and reviewers] and the
baseline for [implementation, verification and maintenance]. It covers
[the components in scope] and excludes [items described elsewhere].

### 1.3 Design context

[Two or three paragraphs: the problem the software solves, the users and
neighbouring systems, the platform it runs on, and the major constraints
(regulation, legacy interfaces, team, schedule) that shaped the design.]

### 1.4 Design languages used

| Language or notation | Used for | Conventions |
|---|---|---|
| *Example:* Mermaid flowchart | Context, composition, dependency views | Arrows point from user to provider |
| *Example:* Mermaid classDiagram | Logical and structure views | One diagram per package |
| *Example:* Mermaid stateDiagram-v2 | State dynamics view | States in PascalCase, events in lower case |
| *Example:* Pseudocode | Algorithm view | Indented, no language-specific syntax |
| [Language] | [Purpose] | [Conventions] |

## 2. Design stakeholders and concerns

<!-- Guidance: A design concern is a question a stakeholder needs the design to answer. Phrase each concern as a question. Every concern must be framed by at least one viewpoint in section 3. -->

### 2.1 Design stakeholders

| ID | Stakeholder | Interest in the design |
|---|---|---|
| DS-01 | *Example:* Developers | How to implement and extend each component |
| DS-02 | *Example:* Testers | Interfaces, states and error paths to verify |
| DS-03 | *Example:* Maintainers | Dependencies, impact of change |
| DS-04 | *Example:* Operations | Resource needs, deployment, failure behaviour |
| DS-05 | *Example:* Security reviewer | Trust boundaries, data handling |
| [DS-nn] | [Stakeholder] | [Interest] |

### 2.2 Design concerns

| ID | Design concern | Raised by | Priority |
|---|---|---|---|
| DC-01 | *Example:* What are the system boundaries and external interfaces? | DS-01, DS-05 | High |
| DC-02 | *Example:* How is the software decomposed and what does each part do? | DS-01, DS-03 | High |
| DC-03 | *Example:* Which components depend on which, and what breaks if one changes? | DS-03 | High |
| DC-04 | *Example:* What data is stored, in what form, and who may access it? | DS-01, DS-05 | High |
| DC-05 | *Example:* How does an order move through its lifecycle? | DS-02 | Medium |
| DC-06 | *Example:* How much memory, CPU and storage does the system need? | DS-04 | Medium |
| [DC-nn] | [Concern as a question] | [DS IDs] | [High / Medium / Low] |

## 3. Design viewpoints

<!-- Guidance: A viewpoint defines the language, elements and analysis rules for one view. The twelve below are the commonly used set; keep the ones whose concerns you listed and record why others are omitted. -->

### 3.1 Viewpoint selection

| Viewpoint | Concerns framed | Design elements | Notation | Selected |
|---|---|---|---|---|
| Context | DC-01 | Design subject, actors, external entities, services | Flowchart | Yes |
| Composition | DC-02 | Subsystems, components, modules | Flowchart, table | Yes |
| Logical | DC-02 | Classes, interfaces, types | Class diagram | Yes |
| Dependency | DC-03 | Uses and depends-on relations | Flowchart, matrix | Yes |
| Information | DC-04 | Entities, attributes, data stores | ER diagram, table | Yes |
| Patterns use | DC-02, DC-03 | Design patterns, frameworks | Table | Yes |
| Interface | DC-01, DC-03 | Provided and required interfaces | Table, signatures | Yes |
| Structure | DC-02 | Internal structure of components | Class diagram | Yes |
| Interaction | DC-05 | Messages between components | Sequence diagram | Yes |
| State dynamics | DC-05 | States, events, transitions | State diagram | Yes |
| Algorithm | DC-02 | Procedures, logic, complexity | Pseudocode, table | [Yes / No, reason] |
| Resource | DC-06 | CPU, memory, storage, network, licences | Table, formula | Yes |

### 3.2 Viewpoint specification conventions

Each view in section 4 states: the viewpoint that governs it, the concerns
it addresses, the design elements it shows, the diagrams and tables it
contains, and any known open issues. Elements carry stable identifiers
(`CMP-nn` for components, `IF-nn` for interfaces, `ENT-nn` for entities) so
other views and the traceability matrix in section 7 can refer to them.

## 4. Design views

<!-- Guidance: One subsection per selected viewpoint. Write for the stakeholders who raised the concerns, keep diagrams small, and put detail in tables. -->

### 4.1 Context view

<!-- Guidance: Show the software as a black box: who uses it, which systems it talks to, which services it offers. -->

Governs: Context viewpoint. Addresses: DC-01. The diagram below shows
[System name] and its external entities.

```mermaid
flowchart LR
  clerk([Sales clerk]) -->|creates orders| sys[[Order management software]]
  cust([Customer]) -->|tracks orders| sys
  sys -->|charges cards| pay[Payment provider]
  sys -->|posts invoices| erp[(ERP)]
  sys -->|sends notifications| mail[Email gateway]
```

| External entity | Service used or offered | Interface |
|---|---|---|
| *Example:* Payment provider | Card authorisation and capture | IF-03 (HTTPS REST) |
| *Example:* ERP | Invoice posting | IF-04 (message queue) |
| [Entity] | [Service] | [IF-nn] |

### 4.2 Composition view

<!-- Guidance: Decompose the design subject into its constituent parts and state each part's responsibility. -->

Governs: Composition viewpoint. Addresses: DC-02. The software is
decomposed into the following components.

```mermaid
flowchart TB
  ui[CMP-01 Web UI] --> api[CMP-02 API layer]
  api --> ord[CMP-03 Order module]
  api --> cat[CMP-04 Catalogue module]
  ord --> pay[CMP-05 Payment adapter]
  ord --> notif[CMP-06 Notification module]
  ord --> repo[(CMP-07 Persistence)]
  cat --> repo
```

| ID | Component | Responsibility | Realised as |
|---|---|---|---|
| CMP-03 | *Example:* Order module | Validate orders, compute totals, drive lifecycle | Package `orders` |
| CMP-05 | *Example:* Payment adapter | Wrap provider API, map errors, retry idempotently | Package `payments` |
| [CMP-nn] | [Component] | [Responsibility] | [Package / service / library] |

### 4.3 Logical view

<!-- Guidance: Show the key types, their attributes and relationships. Only types that matter for the design decisions; generated or trivial types can be omitted. -->

Governs: Logical viewpoint. Addresses: DC-02. Core domain types:

```mermaid
classDiagram
  class Order {
    +OrderId id
    +OrderStatus status
    +Money total()
    +submit()
    +cancel(reason)
  }
  class OrderLine {
    +Sku sku
    +int quantity
    +Money unitPrice
  }
  class PaymentPort {
    <<interface>>
    +authorise(amount) AuthResult
  }
  Order "1" *-- "1..*" OrderLine
  Order ..> PaymentPort : uses
```

| Type | Kind | Purpose | Invariants |
|---|---|---|---|
| *Example:* Order | Aggregate root | Holds lines and lifecycle | Total equals sum of lines; status changes only through methods |
| [Type] | [Entity / value / service / interface] | [Purpose] | [Invariants] |

### 4.4 Dependency view

<!-- Guidance: Show which components use which, including shared libraries. Highlight cycles and the impact of changing a heavily used component. -->

Governs: Dependency viewpoint. Addresses: DC-03. Dependency matrix (row
depends on column):

| Depends on: | CMP-02 | CMP-03 | CMP-04 | CMP-05 | CMP-06 | CMP-07 |
|---|---|---|---|---|---|---|
| CMP-01 Web UI | X | | | | | |
| CMP-02 API layer | | X | X | | | |
| CMP-03 Order module | | | X | X | X | X |
| CMP-04 Catalogue module | | | | | | X |

Change impact notes: [for example "CMP-07 is used by two modules; schema
changes need a migration and review by both owners"]. Cycles found: [none
/ list with remediation].

### 4.5 Information view

<!-- Guidance: Describe persistent data: entities, keys, relationships, stores, classification and retention. -->

Governs: Information viewpoint. Addresses: DC-04.

```mermaid
erDiagram
  CUSTOMER ||--o{ ORDER : places
  ORDER ||--|{ ORDER_LINE : contains
  PRODUCT ||--o{ ORDER_LINE : "listed in"
  ORDER ||--o| PAYMENT : "paid by"
```

| ID | Entity | Key attributes | Store | Classification | Retention |
|---|---|---|---|---|---|
| ENT-01 | *Example:* Customer | id, email, name | PostgreSQL `customers` | Confidential (personal data) | 6 years after last order |
| ENT-04 | *Example:* Payment | id, order_id, provider_ref, status | PostgreSQL `payments` | Confidential (no card numbers stored) | 10 years |
| [ENT-nn] | [Entity] | [Attributes] | [Store] | [Class] | [Retention] |

### 4.6 Patterns use view

<!-- Guidance: Name the design patterns and frameworks reused, where they apply and why. This saves readers from reverse-engineering intent from code. -->

Governs: Patterns use viewpoint. Addresses: DC-02, DC-03.

| Pattern or framework | Applied in | Purpose |
|---|---|---|
| *Example:* Ports and adapters | CMP-03, CMP-05 | Keep domain logic independent of the payment provider |
| *Example:* Repository | CMP-07 | Isolate SQL from domain types |
| *Example:* Outbox | CMP-03 to ERP | Publish events atomically with database writes |
| [Pattern] | [Components] | [Purpose] |

### 4.7 Interface view

<!-- Guidance: Specify every provided and required interface: operations, inputs, outputs, errors, and the contract (pre- and post-conditions). Link to full API specs rather than copying them. -->

Governs: Interface viewpoint. Addresses: DC-01, DC-03.

| ID | Interface | Provider | Consumers | Operations | Errors | Specification |
|---|---|---|---|---|---|---|
| IF-01 | *Example:* Orders REST API | CMP-02 | CMP-01, partners | `POST /orders`, `GET /orders/{id}` | 400, 404, 409, 503 | [OpenAPI link] |
| IF-03 | *Example:* PaymentPort | CMP-05 | CMP-03 | `authorise(amount, token)` | Declined, Timeout | Section 4.3 |
| [IF-nn] | [Interface] | [CMP] | [CMPs] | [Operations] | [Errors] | [Link] |

### 4.8 Structure view

<!-- Guidance: Show the internal structure of complex components: their parts, how parts connect, and what is reused. Pick the one or two components where this matters. -->

Governs: Structure viewpoint. Addresses: DC-02. Internal structure of
[CMP-03 Order module]:

| Part | Role | Connected to |
|---|---|---|
| *Example:* `OrderService` | Application service; transaction boundary | `OrderRepository`, `PaymentPort`, `Outbox` |
| *Example:* `PricingPolicy` | Computes discounts and tax | `OrderService` |
| [Part] | [Role] | [Connections] |

### 4.9 Interaction view

<!-- Guidance: Show the message flow for the most important or riskiest scenarios, including at least one failure path. -->

Governs: Interaction viewpoint. Addresses: DC-05. Order submission with
payment:

```mermaid
sequenceDiagram
  actor Clerk
  participant API as CMP-02 API
  participant Ord as CMP-03 Order
  participant Pay as CMP-05 Payment adapter
  participant DB as CMP-07 Persistence
  Clerk->>API: POST /orders
  API->>Ord: submit(order)
  Ord->>Pay: authorise(total)
  Pay-->>Ord: Authorised(ref)
  Ord->>DB: save order + outbox event
  Ord-->>API: OrderId
  API-->>Clerk: 201 Created
```

| Scenario | Trigger | Failure path described |
|---|---|---|
| *Example:* Submit order | Clerk submits | Payment declined returns 402 and order stays Draft |
| [Scenario] | [Trigger] | [Failure path] |

### 4.10 State dynamics view

<!-- Guidance: Model the lifecycle of entities whose behaviour depends on state. List every event that causes a transition and what is forbidden. -->

Governs: State dynamics viewpoint. Addresses: DC-05. Lifecycle of an Order:

```mermaid
stateDiagram-v2
  [*] --> Draft
  Draft --> Submitted : submit
  Submitted --> Paid : payment authorised
  Submitted --> Draft : payment declined
  Paid --> Shipped : dispatch
  Paid --> Cancelled : cancel
  Draft --> Cancelled : cancel
  Shipped --> Delivered : delivery confirmed
  Delivered --> [*]
  Cancelled --> [*]
```

| Transition | Guard | Action |
|---|---|---|
| *Example:* Paid to Cancelled | Not yet dispatched | Refund via CMP-05; notify customer |
| [Transition] | [Guard] | [Action] |

### 4.11 Algorithm view

<!-- Guidance: Describe the non-obvious algorithms: inputs, outputs, steps, complexity and edge cases. Skip CRUD logic. -->

Governs: Algorithm viewpoint. Addresses: DC-02. Order total calculation:

```text
total(order):
  subtotal = sum(line.quantity * line.unitPrice for line in order.lines)
  discount = PricingPolicy.discount(order.customer, subtotal)
  tax      = round_half_even((subtotal - discount) * taxRate(order.address), 2)
  return subtotal - discount + tax
```

The cost is linear in the number of lines, $O(n)$. Rounding happens once,
at the end, to avoid accumulated error. Edge cases: [zero lines rejected,
negative discount rejected, currency mismatch rejected].

### 4.12 Resource view

<!-- Guidance: State the resources the design consumes and how you estimated them. Show the formula so reviewers can challenge the inputs. -->

Governs: Resource viewpoint. Addresses: DC-06. Storage growth estimate:

$$
S_{year} = N_{orders/day} \times 365 \times \bar{s}_{order} = 20\,000 \times 365 \times 4\ \text{KB} \approx 29\ \text{GB}
$$

| Resource | Budget | Estimate | Basis |
|---|---|---|---|
| *Example:* API memory per instance | 512 MB | 380 MB peak | Load test LT-04 |
| *Example:* Database storage | 100 GB over 3 years | 87 GB | Formula above |
| *Example:* Payment provider calls | 50 per second contract limit | 12 per second peak | Peak hour forecast |
| [Resource] | [Budget] | [Estimate] | [Basis] |

## 5. Design rationale

<!-- Guidance: Record the significant design decisions, the options considered, and why the chosen option won. Rationale is what lets maintainers change the design safely years later. -->

| ID | Decision | Options considered | Rationale | Concerns | Views affected |
|---|---|---|---|---|---|
| DR-001 | *Example:* Use an outbox table to publish ERP events | Direct queue publish; distributed transaction; outbox | Avoids lost or phantom events without a two-phase commit | DC-03, DC-04 | 4.5, 4.6, 4.9 |
| DR-002 | *Example:* Hide the payment provider behind a port | Call SDK directly; port and adapter | Provider may change; enables tests with a fake | DC-03 | 4.3, 4.6 |
| [DR-nnn] | [Decision] | [Options] | [Rationale] | [DC IDs] | [Views] |

Assumptions the rationale depends on: [list, for example "order volume
stays below 50,000 per day until YYYY"]. If an assumption fails, revisit
the linked decisions.

## 6. Design overlays

<!-- Guidance: An overlay adds information to an existing view without changing its viewpoint, for example security zones, ownership or deployment on top of the composition view. Use overlays instead of duplicating a view. -->

| ID | Overlay | Applies to view | What it adds |
|---|---|---|---|
| OV-01 | *Example:* Security zones | 4.2 Composition | Marks CMP-01 as untrusted zone and CMP-05, CMP-07 as restricted zone |
| OV-02 | *Example:* Team ownership | 4.2 Composition | Owner team per component |
| [OV-nn] | [Overlay] | [View] | [Added information] |

Overlay OV-01, security zones on the composition view:

| Component | Zone | Controls at boundary |
|---|---|---|
| CMP-01 Web UI | Untrusted (browser) | Input validation in CMP-02, CSRF tokens |
| CMP-02 API layer | DMZ | Authentication, rate limiting |
| CMP-05, CMP-07 | Restricted | Network policy, secrets from vault |

## 7. Traceability to requirements

<!-- Guidance: Every requirement must map to at least one design element, and every design element should exist for a requirement. Gaps in either direction are review findings. -->

| Requirement | Summary | Design elements | View | Verification |
|---|---|---|---|---|
| *Example:* SRS-FR-012 | Customer can cancel an unshipped order | CMP-03, Order state machine | 4.10 | Test TC-112 |
| *Example:* SRS-NFR-004 | p95 order submission under 800 ms | CMP-02, CMP-03, CMP-05 | 4.9, 4.12 | Load test LT-04 |
| *Example:* SRS-SEC-002 | No card numbers stored | ENT-04, IF-03 | 4.5, 4.7 | Code review checklist CR-SEC |
| [Requirement ID] | [Summary] | [CMP / IF / ENT IDs] | [View] | [Test or review] |

Untraced design elements: [list or "none"]. Unallocated requirements:
[list or "none"].

## 8. Glossary and references

<!-- Guidance: Define terms used in a specific sense in this SDD and list the documents it depends on. -->

### 8.1 Glossary

| Term | Meaning in this document |
|---|---|
| Design subject | The software whose design this SDD describes |
| Design concern | A question about the design that matters to a stakeholder |
| Design viewpoint | Conventions for building and reading one kind of design view |
| Design view | The design described from one viewpoint |
| Design overlay | Extra information layered on an existing view |
| [Term] | [Meaning] |

### 8.2 References

| ID | Document | Version |
|---|---|---|
| REF-01 | [Software requirements specification] | [x.y] |
| REF-02 | [Architecture description] | [x.y] |
| REF-03 | [API specifications] | [x.y] |
| REF-04 | IEEE 1016-2009, Software Design Descriptions | 2009 |

## Standard and licence note

Structure aligned with IEEE 1016-2009, *IEEE Standard for Information
Technology: Systems Design, Software Design Descriptions*: identification,
design stakeholders and concerns, design viewpoints, design views, design
overlays and design 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.