152 lines
4.6 KiB
Markdown
152 lines
4.6 KiB
Markdown
# Software Design Document (SDD) Framework
|
|
|
|
A structured taxonomy of artifacts for comprehensive software documentation and design.
|
|
|
|
---
|
|
|
|
## Overview
|
|
|
|
This framework categorizes Software Design Document artifacts by their purpose in the software development lifecycle. Each artifact type serves a specific role in defining **what** we build, **how** it works, and **how** we verify and document it.
|
|
|
|
---
|
|
|
|
## Artifact Taxonomy
|
|
|
|
| Document Type | "Artifact" Type | Purpose in SDD | Tooling Examples |
|
|
|---------------|-----------------|----------------|------------------|
|
|
| Requirements | User Stories / ADRs | Defines the "Business Contract" — why are we building this? | GitHub Issues, Jira, Architecture Decision Records (ADRs) |
|
|
| The Spec | Schema Definition | The Source of Truth — defines data structures, types, and endpoints | OpenAPI (YAML), Protobuf, Apache Arrow Schemas |
|
|
| Architecture | System Blueprint | Defines how the specs connect (e.g., Service A talks to B via NATS) | Mermaid.js (Diagrams-as-code), IcePanel, Structurizr |
|
|
| Implementation | Generated Code | The code "fills in" the logic defined by the Spec | OpenAPI Generator, TypeSafe clients (Zod, TypeScript) |
|
|
| Validation | Contract Tests | Automatically checks if the code matches the Spec | Prism (Mocking), Dredd, Schemathesis |
|
|
| Tutorial | Interactive Sandbox | Allows others to "play" with the spec without writing code | Swagger UI, Redoc, Postman Collections |
|
|
|
|
---
|
|
|
|
## Purpose by Artifact Type
|
|
|
|
### 1. Requirements (User Stories / ADRs)
|
|
|
|
**Purpose:** Defines the "Business Contract" — why are we building this?
|
|
|
|
**Key Questions Answered:**
|
|
- What problem are we solving?
|
|
- Who are the stakeholders?
|
|
- What are the success criteria?
|
|
|
|
**Examples:**
|
|
- GitHub Issues
|
|
- Jira tickets
|
|
- Architecture Decision Records (ADRs)
|
|
|
|
---
|
|
|
|
### 2. The Spec (Schema Definition)
|
|
|
|
**Purpose:** The Source of Truth — defines data structures, types, and endpoints.
|
|
|
|
**Key Questions Answered:**
|
|
- What data structures do we use?
|
|
- What are the API endpoints?
|
|
- What are the message formats?
|
|
|
|
**Examples:**
|
|
- OpenAPI (YAML) specifications
|
|
- Protocol Buffers (Protobuf)
|
|
- Apache Arrow Schemas
|
|
|
|
---
|
|
|
|
### 3. Architecture (System Blueprint)
|
|
|
|
**Purpose:** Defines how the specs connect — the high-level structure and communication patterns.
|
|
|
|
**Key Questions Answered:**
|
|
- How do services communicate?
|
|
- What is the deployment topology?
|
|
- What are the system boundaries?
|
|
|
|
**Examples:**
|
|
- Mermaid.js diagrams (Diagrams-as-code)
|
|
- IcePanel
|
|
- Structurizr
|
|
|
|
---
|
|
|
|
### 4. Implementation (Generated Code)
|
|
|
|
**Purpose:** The code "fills in" the logic defined by the Spec.
|
|
|
|
**Key Questions Answered:**
|
|
- How do we implement the spec?
|
|
- What libraries/frameworks do we use?
|
|
- How do we ensure type safety?
|
|
|
|
**Examples:**
|
|
- OpenAPI Generator
|
|
- TypeSafe clients (Zod, TypeScript)
|
|
|
|
---
|
|
|
|
### 5. Validation (Contract Tests)
|
|
|
|
**Purpose:** Automatically checks if the code matches the Spec.
|
|
|
|
**Key Questions Answered:**
|
|
- Does the implementation match the spec?
|
|
- Are there breaking changes?
|
|
- Is the contract upheld?
|
|
|
|
**Examples:**
|
|
- Prism (Mocking)
|
|
- Dredd
|
|
- Schemathesis
|
|
|
|
---
|
|
|
|
### 6. Tutorial (Interactive Sandbox)
|
|
|
|
**Purpose:** Allows others to "play" with the spec without writing code.
|
|
|
|
**Key Questions Answered:**
|
|
- How do I use this API?
|
|
- What are the expected inputs/outputs?
|
|
- How can I experiment safely?
|
|
|
|
**Examples:**
|
|
- Swagger UI
|
|
- Redoc
|
|
- Postman Collections
|
|
|
|
---
|
|
|
|
## Usage Guidelines
|
|
|
|
1. **Start with Requirements** — Define the business context and decision records
|
|
2. **Define The Spec** — Create the source of truth for data and endpoints
|
|
3. **Design Architecture** — Visualize how components connect
|
|
4. **Implement** — Generate or write code based on the spec
|
|
5. **Validate** — Run contract tests to ensure alignment
|
|
6. **Tutorial** — Provide interactive documentation for users
|
|
|
|
---
|
|
|
|
## Relationship to NATSBridge
|
|
|
|
This NATSBridge project implements a NATS-based messaging bridge that can be used with all artifact types in this framework:
|
|
|
|
- **Architecture:** NATS as the communication backbone
|
|
- **Spec:** Message schemas for bridge operations
|
|
- **Implementation:** Generated code for NATS message handling
|
|
- **Validation:** Contract tests for message format compliance
|
|
- **Tutorial:** Interactive examples for bridge configuration
|
|
|
|
---
|
|
|
|
## References
|
|
|
|
- Architecture Decision Records (ADRs): [http://adr.cascadely.com/](http://adr.cascadely.com/)
|
|
- OpenAPI Specification: [https://spec.openapis.org/](https://spec.openapis.org/)
|
|
- Protocol Buffers: [https://protobuf.dev/](https://protobuf.dev/)
|
|
- Mermaid.js: [https://mermaid.js.org/](https://mermaid.js.org/)
|
|
- Schemathesis: [https://schemathesis.io/](https://schemathesis.io/) |