# 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/)