From f9aa6bc9f63e4b844727eb1c547d1d5bffae0a41 Mon Sep 17 00:00:00 2001
From: narawat <narawat@gmail.com>
Date: Fri, 13 Mar 2026 07:49:51 +0700
Subject: [PATCH] add sdd file

---
 docs/SDD_FRAMEWORK.md | 152 ++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 152 insertions(+)
 create mode 100644 docs/SDD_FRAMEWORK.md

diff --git a/docs/SDD_FRAMEWORK.md b/docs/SDD_FRAMEWORK.md
new file mode 100644
index 0000000..fde8c7d
--- /dev/null
+++ b/docs/SDD_FRAMEWORK.md
@@ -0,0 +1,152 @@
+# 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/)
\ No newline at end of file