ton/NATSBridge
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 7 Wiki Activity

update

Browse Source
This commit is contained in:
narawat
2026-03-13 08:24:54 +07:00
parent f9aa6bc9f6
commit 64796ff0a3
2 changed files with 279 additions and 152 deletions
Download Patch File Download Diff File Expand all files Collapse all files

152
docs/SDD_FRAMEWORK.md
View File

@@ -1,152 +0,0 @@
# 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/)