4.6 KiB
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
- Start with Requirements — Define the business context and decision records
- Define The Spec — Create the source of truth for data and endpoints
- Design Architecture — Visualize how components connect
- Implement — Generate or write code based on the spec
- Validate — Run contract tests to ensure alignment
- 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/
- OpenAPI Specification: https://spec.openapis.org/
- Protocol Buffers: https://protobuf.dev/
- Mermaid.js: https://mermaid.js.org/
- Schemathesis: https://schemathesis.io/