system-design
Produce a professional Software Design Description (SDD) compliant with IEEE 1016 standard, with strict requirement traceability, locked tech stack adherence, database ERD/DDL, OpenAPI specifications, and layered architecture design.
- License 许可
- MIT
- 最近更新
- 2026-09-15
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- system-design
- author
- Hermes Agent Team
- license
- MIT
- version
- 2.0.0
- metadata
- { "hermes": { "tags": [ "architecture", "sdd", "ieee-1016", "system-design", "database", "erd", "openapi", "adr" ], "related_skills": [ "srs-specifier", "test-planner", "delegate-software-engineering-team" ] } }
- platforms
- [ "linux", "macos", "windows" ]
- description
- Produce a professional Software Design Description (SDD) compliant with IEEE 1016 standard, with strict requirement traceability, locked tech stack adherence, database ERD/DDL, OpenAPI specifications, and layered architecture design.
03 SKILL.md 正文
Software Design Description (SDD) Skill (IEEE 1016)
Overview
Produce a comprehensive Software Design Description (SDD) document that translates requirements from docs/srs.md into concrete, implementable software blueprints.
Standards Compliance
- IEEE 1016-2009: IEEE Standard for Information Technology — Systems Design — Software Design Descriptions.
When to Use
- Phase 3 Architecture Design (dispatched by
dev-pmtodev-architech). - Mid-development Tier 2 architectural revisions when database schema or cross-module boundaries change.
- Replaces legacy lightweight
system_design.mdwith an IEEE 1016 compliant specification.
Target Output Path
/opt/data/workspace/{project_name}/docs/sdd.md
/opt/data/workspace/{project_name}/docs/adr/ADR-XXX-{title}.md (for major architectural decisions)
🔒 Ironclad Tech Stack Adherence Rule
[!CAUTION] Strict Compliance with
docs/srs.mdSection 3:dev-architechMUST readdocs/srs.mdfirst. The architectural design MUST 100% follow the exact language, framework, database engine, and ORM specified indocs/srs.mdSection 3. DO NOT switch tech stacks (e.g. never substitute TypeScript/Express for Python/FastAPI or vice-versa) unless explicitly authorized by the user via an approved ADR.
🛠️ Step-by-Step Procedure
Step 1: Ingest SRS Specification
- Read
/opt/data/workspace/{project_name}/docs/srs.md. - Extract all Use Cases (
UC-001~UC-NNN), Technical Constraints (TC), and Non-Functional Requirements (NFR).
Step 2: Design Layered Software Architecture
Establish a clean separation of concerns:
- Presentation Layer (Frontend): React Components, Custom Hooks, Zustand/Context Stores, Axios/Fetch API Clients.
- Interface Layer (Routers / Controllers): FastAPI APIRouter, request validation via Pydantic schemas, HTTP status mapping, dependency injection (DB sessions, current user).
- Domain & Service Layer: Business logic, workflow validation, domain events, transaction orchestration.
- Data Access Layer (Persistence & Repositories): SQLAlchemy 2.0 Async declarative models, async queries, transaction boundaries.
Step 3: Complete Data Architecture & ERD / DDL
- Provide a Mermaid ERD diagram showing all entities, cardinality (1:1, 1:N, N:M), foreign keys, and cascading rules.
- Provide complete, copy-paste ready SQL DDL statements for all tables with exact data types, constraints, default values, and indexes.
Step 4: Interface & API Specification (OpenAPI 3.0 Standard)
For every API endpoint:
- HTTP Method and Route Path (e.g.
POST /api/v1/meetings). - Authentication & Authorization requirements (e.g. Bearer JWT, required role).
- Request Headers, Query Parameters, Path Parameters.
- Request Body JSON schema with data types and validation rules.
- Response Body JSON schemas for HTTP 200/201 (Success) and HTTP 400/401/403/404/422/500 (Error).
Step 5: Requirement Traceability Matrix (RTM)
Construct an exhaustive bidirectional Traceability Matrix mapping:
SRS Use Case ID $\rightarrow$ API Endpoints $\rightarrow$ Database Models $\rightarrow$ Service Functions $\rightarrow$ Frontend Views $\rightarrow$ Test Cases.
Step 6: Security & Cross-Cutting Architecture
- JWT lifecycle (Issuance, Expiration, Claims:
sub,email,role,exp). - Password hashing configuration (bcrypt with work factor 12).
- Global Exception Handler & Standard Error Response Envelope.
- CORS middleware configuration and allowed origins/methods.
Step 7: Output SDD & Report
- Write
/opt/data/workspace/{project_name}/docs/sdd.md. - If major architectural trade-offs occurred, write
/opt/data/workspace/{project_name}/docs/adr/ADR-001-{title}.md. - Commit and push to git:
git add docs/ && git commit -m "docs(architecture): IEEE 1016 SDD specification (refs #{issue})" && git push origin main. - Call
kanban_complete()to notify PM.
📄 SDD Document Template Structure
# Software Design Description (SDD)
## Project: {Project Name}
**Standard**: IEEE 1016-2009
**Version**: 1.0.0
**Status**: Baseline
**SRS Reference**: `docs/srs.md` (v1.0.0)
---
## 1. System Overview & Architectural Style
### 1.1 Architectural Pattern
- **Style**: Layered Clean Architecture (Client-Server over REST API)
- **Frontend Architecture**: SPA with React, TypeScript, Component-Driven Design.
- **Backend Architecture**: Layered Modular Architecture (Routers -> Services -> Repositories/Models).
### 1.2 System Topology Diagram
```mermaid
graph TD
Client[React Frontend / Browser] -->|HTTP REST / JSON| Gateway[FastAPI Backend Application]
Gateway --> Router[API Routers / Controllers]
Router --> Service[Domain Business Services]
Service --> Repo[Data Access / Repositories]
Repo --> DB[(PostgreSQL 16 Database)]
2. Requirement Traceability Matrix (RTM)
| SRS UC ID | Description | API Endpoint(s) | Database Tables | Backend Service / Model | Frontend Component | Test Suite Ref |
|---|---|---|---|---|---|---|
UC-001 |
User Registration | POST /api/v1/auth/register |
users |
AuthService.register / User |
RegisterPage, AuthForm |
tests/unit/test_auth.py |
UC-002 |
User Login | POST /api/v1/auth/login |
users |
AuthService.login / User |
LoginPage |
tests/unit/test_auth.py |
3. Data Architecture & Database Design
3.1 Entity Relationship Diagram (ERD)
erDiagram
USERS ||--o{ MEETINGS : creates
MEETINGS ||--o{ MINUTES : contains
MEETINGS ||--o{ ACTION_ITEMS : assigns
USERS {
uuid id PK
string email UK
string hashed_password
string full_name
string role
timestamp created_at
}
3.2 SQL DDL Schema
CREATE EXTENSION IF NOT EXISTS "uuid-ossp";
CREATE TABLE users (
id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
email VARCHAR(255) UNIQUE NOT NULL,
hashed_password VARCHAR(255) NOT NULL,
full_name VARCHAR(100) NOT NULL,
role VARCHAR(50) NOT NULL DEFAULT 'member',
is_active BOOLEAN NOT NULL DEFAULT TRUE,
created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
updated_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP
);
CREATE INDEX idx_users_email ON users(email);
4. API & Interface Specifications
4.1 Authentication & Base URL
- Base URL:
/api/v1 - Security Scheme:
Authorization: Bearer <JWT_TOKEN>
4.2 Endpoint Specifications
POST /api/v1/auth/register
- Description: Registers a new user account.
- Request Body:
{ "email": "user@example.com", "password": "SecurePassword123!", "full_name": "Roy Shao" } - Responses:
201 Created:{"id": "uuid", "email": "user@example.com", "full_name": "Roy Shao"}400 Bad Request:{"detail": "Email already registered", "code": "EMAIL_EXISTS"}422 Unprocessable Entity: Field validation error.
5. Security & Session Architecture
- Password Hashing: Passlib bcrypt context with
rounds=12. - JWT Issuance:
jwt.encode({"sub": str(user.id), "email": user.email, "role": user.role, "exp": ...}, SECRET_KEY, algorithm="HS256"). - CORS Configuration: Allowed origins configured via
CORS_ORIGINSenvironment variable.
6. Architecture Decision Records (ADRs)
docs/adr/ADR-001-postgresql-async-orm.mddocs/adr/ADR-002-jwt-stateless-authentication.md
04 同仓库更多 Skills
srs-specifier
Generate professional Software Requirements Specification (SRS) compliant with ISO/IEC/IEEE 29148 and IEEE 830 standards, focusing purely on requirements (WHAT the system does) with granular use-case decomposition, high-level technology constraints, non-functional requirements, and strict exclusion of design details (no API routes, no ERD/DDL, no response envelopes).
test-planner
Author comprehensive Test Plan specifications compliant with ISO/IEC/IEEE 29119-3 standard (superseding IEEE 829) and E2E Testing Patterns, establishing testing pyramid ratios, fixture strategies, boundary edge cases, headless containerized E2E acceptance suites, and triple-gate quality metrics.
writing-plans
Write a markdown plan to .hermes/plans/; no execution.
system-design
Produce a comprehensive system design document for a software project.
srs-specifier
Generate professional Software Requirements Specification (SRS) compliant with ISO/IEC/IEEE 29148 and IEEE 830 standards, focusing purely on requirements (WHAT the system does) with granular use-case decomposition, high-level technology constraints, non-functional requirements, and strict exclusion of design details (no API routes, no ERD/DDL, no response envelopes).
sdd-architect
Author comprehensive Software Design Description (SDD) specifications compliant with IEEE 1016-2009 standard, translating SRS requirements into layered clean architectures, explicit Business Service method signatures, domain exceptions, ERDs, REST APIs, and ADRs.