Design Document

This template defines the format for design documents produced during architecture and planning sessions. See Complex Project Planning for the workflow that produces this document.

A design document captures the technical architecture of a feature or component — structural diagrams, behavioral specifications, decision traceability, and testing strategy. It is a living document updated iteratively as design decisions are made and recorded in the accompanying decision log.

When to Create a Design Document

Create a design document when:

• A new component, module, or significant feature is being designed.
• The implementation spans multiple classes, files, or repositories.
• You are following the Complex Project Planning workflow — a design document is mandatory in that case.

For simpler changes where the specification itself describes the implementation, specification.md per the Project Planning Workflow is sufficient.

---

Template

---
author: <!-- REPLACE: your name -->
title: "Design: <!-- REPLACE: feature or component name -->"
created: <!-- REPLACE: YYYY-MM-DD -->
---

# Design: <!-- REPLACE: Feature/Component Name -->

## Overview

<!-- REPLACE: 2-3 paragraphs describing the purpose, scope, and key design choices.
Reference the decision log for detailed rationale rather than repeating it here. -->

## Decision Summary

| # | Decision | Chosen Option |
|---|----------|---------------|
| DQ-001 | <!-- REPLACE: question summary --> | <!-- REPLACE: option chosen --> |
| DQ-002 | | |

> Full rationale in [Decision Log](./decision-log.md).

---

## Platform Conventions

<!-- REQUIRED. The published patterns this design conforms to. Link each one — do not
paraphrase, and do not name a skill without linking the page behind it. A design that
names no patterns is not "pattern-neutral"; it is unreviewed on this axis, and a reviewer
should ask for this section before reviewing anything below it. -->

| Pattern | Applies to |
|---------|------------|
| <!-- REPLACE: e.g. [Endpoint Definition DSL](…) --> | <!-- REPLACE: e.g. the REST surface in §API Contract --> |
| <!-- REPLACE: e.g. [Kotlin Coding Standards](…) --> | <!-- REPLACE: e.g. every code sketch in this document --> |

**Deliberate departures**

<!-- Any place this design departs from a published pattern, with the reason and who
agreed to it. A departure listed here is a decision; an unlisted one is a defect. If this
list is empty, say "None" — an omitted list reads as "not considered". -->

| Departure | Pattern | Why | Agreed with |
|-----------|---------|-----|-------------|
| <!-- REPLACE --> | <!-- REPLACE --> | <!-- REPLACE --> | <!-- REPLACE --> |

---

## Structural Design

### Class Diagram

```plantuml
@startuml
<!-- REPLACE: class diagram source -->
@enduml
```

<!-- REPLACE: Brief narrative explaining the key classes, their responsibilities,
and relationships. Reference DQ numbers for design choices that shaped the structure.
Example: "Per DQ-002, the repository layer is separated from the service layer to
enable independent testing." -->

### Key Classes and Interfaces

<!-- For each significant class or interface, add a subsection: -->

#### `<!-- REPLACE: ClassName -->`

- **Package**: `<!-- REPLACE: fully.qualified.package -->`
- **Responsibility**: <!-- REPLACE: single sentence -->
- **Key fields/properties**: <!-- REPLACE: list -->
- **Key methods**: <!-- REPLACE: list with signatures -->
- **Design decision**: <!-- REPLACE: DQ-00N -->

---

## Behavioral Design

### Sequence Diagrams

<!-- One sequence diagram per key interaction flow. -->

```plantuml
@startuml
hide footbox
title <!-- REPLACE: Flow Name -->
<!-- REPLACE: sequence diagram source -->
@enduml
```

<!-- REPLACE: Narrative explaining the flow, entry points, and error paths.
Lead with the happy path; note error paths in the narrative. -->

### API Contract

<!-- Include this section only if the design includes a REST endpoint or external interface. -->

- **Method**: `<!-- REPLACE: GET / POST / PUT / DELETE -->`
- **Path**: `<!-- REPLACE: /path -->`
- **Authentication**: <!-- REPLACE: mechanism (e.g., Bearer token, API key) -->
- **Request schema**: <!-- REPLACE: inline schema or reference to a schema file -->
- **Response schema**: <!-- REPLACE: inline schema or reference -->
- **Error responses**:
  - `400` — <!-- REPLACE: condition -->
  - `404` — <!-- REPLACE: condition -->
  - `500` — <!-- REPLACE: condition -->

---

## Implementation Scope

### Files to Create

| File | Package/Path | Purpose |
|------|-------------|---------|
| `<!-- REPLACE: FileName -->` | `<!-- REPLACE: package or path -->` | <!-- REPLACE: purpose --> |

### Files to Modify

| File | Change Description |
|------|-------------------|
| `<!-- REPLACE: existing file -->` | <!-- REPLACE: what changes and why --> |

### Out of Scope

<!-- REPLACE: Explicitly list what this design does NOT cover. This prevents scope
creep during implementation and sets clear boundaries.
Example:
- Authentication and authorization (handled by the existing security layer)
- Pagination (out of scope for v1; tracked in DQ-007 as Deferred)
- Bulk mutation endpoints (separate feature) -->

---

## Testing Strategy

### Unit Tests

| Test | Target | Validates |
|------|--------|-----------|
| `<!-- REPLACE: test description -->` | `<!-- REPLACE: class/function -->` | <!-- REPLACE: what behavior --> |

### Integration Tests

| Test | Setup | Validates |
|------|-------|-----------|
| `<!-- REPLACE: test description -->` | <!-- REPLACE: dependencies/fixtures --> | <!-- REPLACE: end-to-end behavior --> |

### API Tests

<!-- Include only if the design includes a REST endpoint. -->

| Test | Method | Path | Expected |
|------|--------|------|----------|
| `<!-- REPLACE: test description -->` | `GET` | `<!-- REPLACE: /path -->` | <!-- REPLACE: response/status --> |

---

## References

- [Decision Log](./decision-log.md)
- [Project Plan](./project-plan.md)
- <!-- REPLACE: Additional references to existing code, documentation, or specs -->

---

__________
Copyright: (c) Arda Systems 2025-2026, All rights reserved

---

Conventions

Diagrams

Use PlantUML for class diagrams and sequence diagrams. Embed diagrams directly in the document using fenced plantuml code blocks — see the PlantUML Guide for syntax, conventions, and common pitfalls.

Sequence diagrams should focus on the happy path first, with error paths described in the accompanying narrative rather than in the diagram.

Platform Conformance

The Platform Conventions section is required, and it is required early — before Structural Design — because a design that specifies package layout, type names, a REST surface, or a persistence shape has already made conformance decisions by the time those sections are written.

Cite the pattern pages, not their names. kotlin-coding in code-span is a reference a reader cannot follow; Kotlin Coding Standards is one they can. For a backend design the usual set is:

• Data Authority Module Pattern — module shape.
• DAG Package Discipline — package layout.
• Naming Conventions — package, type, route, and table names.
• Endpoint Definition DSL — how a REST surface is declared.
• API Design — URL shape, headers, error contract.
• Kotlin Coding Standards — return types, error channel, construction.
• Universe Design — persistence shape.

Naming a departure is not a concession; it is the point. A design that departs for a good reason and says so gets that reason reviewed. A design that departs silently gets the departure discovered in code review, by which time someone has implemented it — and the implementer is then judged against conventions their design never mentioned. That has happened, and the cost was a rewrite plus an amendment to a merged design.

Two consequences worth internalizing:

• If a pattern is wrong, say so here rather than working around it. Pattern pages are written after the fact by whoever hit the problem and are occasionally stale. A departure entry reading “this pattern is out of date, see X” is a valid entry and has led to pages being corrected.
• This section survives into implementation. A reviewer of the resulting pull request should be able to read it and know what the code was supposed to conform to.

Decision Traceability

• Every significant design choice must reference a DQ number from the Decision Log template.
• The Decision Summary table at the top provides a quick reference to all decisions affecting this design.
• Inline references in section text (e.g., “Per DQ-003, we use…”) provide contextual traceability within the document.

This traceability makes it possible to answer “why does the design look this way?” long after the design session has ended.

Iterative Updates

Design documents are updated after each decision log round:

1. Reviewers make decisions in the decision log.
2. The design document is updated to reflect each decision (diagrams, class descriptions, scope).
3. The Decision Summary table is updated.
4. The updated document is reviewed for new ambiguities, which are fed back into the decision log as a new round.

Scope Management

The Out of Scope section is mandatory. It prevents scope creep during implementation by making exclusions explicit. An implementing engineer who hits an ambiguous case should be able to consult this section to determine whether the case is in or out of scope — rather than guessing or expanding the work unilaterally.

---

Integration with Other Documents

Document	Relationship
decision-log.md	Design choices reference DQ numbers; the Decision Summary table mirrors the Decision Log’s resolution
project-plan.md	The design document provides the architectural context; the project plan references design sections when describing tasks
specification.md	For simpler changes, the specification subsumes the design document; for complex work, the design document is separate

---

Copyright: (c) Arda Systems 2025-2026, All rights reserved