System Design Document Skill

Response Language: Always respond to users in Thai (ภาษาไทย)

Skill for creating enterprise-grade standardized system design documents with Mermaid diagrams. Supports both creating new documents and reverse engineering from existing codebases, including Architecture patterns for Microservices, Event-driven, Clean Architecture, and DDD.

Commands Overview

Command	Description
`/create-design-doc`	Create a new system design document from requirements
`/reverse-engineer`	Create a document from an existing codebase
`/create-diagram`	Create a specific diagram type (ER, Flow, DFD, Sequence, etc.)
`/edit-section`	Edit a specific section of the document
`/validate-design-doc`	Validate completeness and consistency
`/import-plan`	Import a document from an implementation plan or free-form design doc
`/sync-with-mockups`	Sync entities and pages with ui-mockup
`/sync-with-features`	Sync APIs and entities with long-running
`/validate-integration`	Validate cross-references across all 3 plugins
`/brainstorm-design`	Interactive brainstorming and Q&A session for system design
`/system-design-doc`	General command (supports all modes)

Quick Start Examples

What you need	Example command
Full document	`/create-design-doc สร้างเอกสารสำหรับระบบ HR`
From Codebase	`/reverse-engineer วิเคราะห์ codebase นี้`
ER Diagram	`/create-diagram ER Diagram สำหรับระบบจองห้องประชุม`
ER from Code	`/reverse-engineer สร้าง ER Diagram จาก entities`
Flow Diagram	`/create-diagram Flow Diagram สำหรับกระบวนการอนุมัติลา`
Data Dictionary	`/create-diagram Data Dictionary สำหรับตาราง employees`
DFD	`/create-diagram DFD Level 1 สำหรับระบบสั่งซื้อ`
Sitemap	`/create-diagram Sitemap สำหรับเว็บ E-commerce`
Sequence Diagram	`/create-diagram Sequence Diagram สำหรับ Login process`
Edit Section	`/edit-section ER Diagram - เพิ่ม entity Payment`
Validate document	`/validate-design-doc`

Workflow Diagrams

Workflow 1: Create New Document from Requirements

flowchart TD
    A[Start] --> B{design_doc_list.json exists?}
    B -->|No| C[Create .design-docs/ and design_doc_list.json]
    B -->|Yes| D[Read project info]
    C --> D
    D --> E[Gather Requirements]
    E --> F[Define 10-Section Structure]
    F --> G[Design Data Model]
    G --> H[Create Diagrams]
    H --> I[Create Data Dictionary]
    I --> J[Generate .md file]
    J --> K[Update design_doc_list.json]
    K --> L[Validate]
    L --> M[End]

Workflow 2: Reverse Engineering from Codebase

flowchart TD
    A[Start] --> B[Scan Project Structure]
    B --> C{Technology identified?}
    C -->|Yes| D[Analyze by Framework]
    C -->|No| E[Ask User for info]
    E --> D
    D --> F[Analyze Models/Entities]
    F --> G[Analyze Controllers/Routes]
    G --> H[Analyze Services/Logic]
    H --> I[Extract data and convert to Diagrams]
    I --> J[Create document from Template]
    J --> K[Validate against Code]
    K --> L{Match?}
    L -->|Yes| M[Save file]
    L -->|No| N[Fix and Re-validate]
    N --> K
    M --> O[End]

Workflow 3: Create Specific Diagram

flowchart TD
    A[Start] --> B{Diagram type specified?}
    B -->|ER| C[Use ER Diagram Pattern]
    B -->|Flow| D[Use Flow Diagram Pattern]
    B -->|DFD| E[Use DFD Pattern]
    B -->|Sequence| F[Use Sequence Pattern]
    B -->|Sitemap| G[Use Sitemap Pattern]
    B -->|State| H[Use State Diagram Pattern]
    B -->|Architecture| I[Use Architecture Pattern]
    C --> J[Gather Entities and Relationships]
    D --> K[Gather Steps and Decisions]
    E --> L[Gather Processes and Data Stores]
    F --> M[Gather Participants and Messages]
    G --> N[Gather Pages and Hierarchy]
    H --> O[Gather States and Transitions]
    I --> P[Select Architecture Pattern]
    J --> Q[Create Mermaid Diagram]
    K --> Q
    L --> Q
    M --> Q
    N --> Q
    O --> Q
    P --> Q
    Q --> R[Validate Syntax]
    R --> S[Output]

Workflow 4: Integration with Other Skills

flowchart LR
    subgraph DesignPhase["Design Phase"]
        SD[system-design-doc]
    end

    subgraph MockupPhase["Mockup Phase"]
        UM[ui-mockup]
    end

    subgraph DevPhase["Development Phase"]
        LR[long-running]
        DN[dotnet-dev]
    end

    SD -->|Sitemap, Entities| UM
    SD -->|Data Model, APIs| LR
    UM -->|Component specs| LR
    SD -->|.NET specific| DN
    LR -->|Feature tracking| SD

Document Structure (10 Sections)

The system design document consists of 10 main sections:

#	Section	Description	Required Diagrams
1	Introduction & Overview	Project info, objectives, scope, Stakeholders	High-Level Architecture
2	System Requirements	FR, NFR, Business Rules, Constraints	-
3	Module Overview	List of modules, dependencies	Module Dependency Diagram
4	Data Model	Entity overview, relationships	Class Diagram (optional)
5	Data Flow Diagram	Data movement, processes, stores	DFD Level 0, 1, 2
6	Flow Diagrams	Business processes, workflows	Flowcharts
7	ER Diagram	Entity relationships, cardinality	ER Diagram
8	Data Dictionary	Table definitions, columns, constraints	-
9	Sitemap	Page hierarchy, navigation	Sitemap Diagram
10	User Roles & Permissions	Roles, permission matrix, access rules	-

Diagram Types Supported

Diagram Type	Mermaid Syntax	Use Case
ER Diagram	`erDiagram`	Entity relationships, database design
Flow Diagram	`flowchart TD/LR`	Business processes, approval workflows
DFD	`flowchart` + subgraphs	Data flow between systems
Sequence Diagram	`sequenceDiagram`	API calls, system interactions
Sitemap	`flowchart TD`	Page structure, navigation
State Diagram	`stateDiagram-v2`	Status transitions, lifecycle
Class Diagram	`classDiagram`	Data model, OOP structure
Architecture	`flowchart` + subgraphs	System architecture, microservices

Architecture Patterns

Supported Patterns

Category	Patterns
Microservices	Service Boundary, API Gateway, Service Mesh, Database per Service
Event-driven	Event Sourcing, CQRS, Saga (Choreography/Orchestration), Message Broker
Clean Architecture	Layer Diagram, Dependency Flow, Use Case Flow
DDD	Bounded Context, Aggregate, Domain Events, Context Mapping

When to Use

Pattern	Use When
Microservices	Large team, independent deployment needs
Event-Driven	Loose coupling, async processing needed
CQRS	Different read/write patterns
Event Sourcing	Full audit history required
Clean Architecture	Long-lived apps, testability priority
DDD	Complex domain logic

Technology Support

Supported Frameworks for Reverse Engineering

Technology	Detection Files	Entities Location	Routes Location
.NET Core	`.csproj`, `.sln`	`Models/`, `Entities/`	`Controllers/`
Node.js/Express	`package.json`	`models/`	`routes/`
Node.js/Prisma	`package.json`, `schema.prisma`	`prisma/schema.prisma`	`routes/`
Python/Django	`requirements.txt`	`*/models.py`	`*/urls.py`
Laravel	`composer.json`	`app/Models/`	`routes/web.php`
Java/Spring	`pom.xml`, `build.gradle`	`*/entity/.java`	`**/controller/`
Go	`go.mod`	`models/`	`handlers/`
Ruby/Rails	`Gemfile`	`app/models/`	`config/routes.rb`

Legacy Support

Technology	Files to Analyze
ASP.NET WebForms	`*.aspx`, `App_Code/`, `Web.config`
Classic ASP	`*.asp`, `includes/`

⚠️ CRITICAL RULES (MUST FOLLOW)

Section Completeness

ALL 10 sections are mandatory — Introduction, Requirements, Modules, Data Model, DFD, Flow Diagrams, ER Diagram, Data Dictionary, Sitemap, User Roles & Permissions
No abbreviation — every section must have full content, not summaries or placeholders
No placeholder text — "[TBD]", "[TODO]", "will be added later" is forbidden

Diagram Rules

Validate Mermaid syntax — every diagram must render without errors
Valid entity names — use PascalCase or snake_case only (no hyphens, no spaces in identifiers)
Close all subgraphs — every subgraph must have a matching end

Consistency Rules

ER ↔ Data Dictionary — every entity in ER Diagram must have a matching table in Data Dictionary, and vice versa
DFD Level 0 ↔ Level 1 — all processes in Level 0 must be decomposed in Level 1
Sitemap ↔ User Roles — every page in Sitemap must have access rules defined in User Roles section

Quality Rules

Unique FR IDs — every Functional Requirement must have a unique ID (FR-001, FR-002, etc.)
PK required — every table in Data Dictionary must have a Primary Key defined
FK valid — every Foreign Key must reference an existing table and column
Permission matrix complete — every role must have permissions defined for every module/page

🔍 Self-Check Checklist (MANDATORY before submitting output)

Before completing the design document, verify EVERY item:

If ANY checkbox is unchecked, DO NOT submit. Fix the issue first.

❌ Output Rejection Criteria

Your output will be REJECTED and you must REDO the entire task if:

Any of the 10 sections is missing or contains only placeholder text
ER Diagram entities don't match Data Dictionary tables (mismatch)
Mermaid diagrams have syntax errors
Placeholder text remains in any section
Permission matrix is incomplete

⚠️ Penalty

Violating these rules means the document is INVALID. You must redo the ENTIRE document from scratch. There are no partial passes — either ALL rules are followed or the output is REJECTED.

Consistency Checks

Changed Section	Also Verify
ER Diagram	Data Dictionary, Data Model
Data Dictionary	ER Diagram
Flow Diagrams	DFD, Sequence Diagrams
Sitemap	User Roles (access)
User Roles	Sitemap (access rules)
Modules	Flow Diagrams, ER Diagram

Integration with Other Skills

ui-mockup Integration

system-design-doc → ui-mockup

Data passed:
• Sitemap → mockup_list.json pages
• Entities → Form fields, Table columns
• User Roles → Access control per page
• Flow Diagrams → User journey reference

long-running Integration

system-design-doc → long-running

Data passed:
• Modules → Feature breakdown
• Data Model → Entity implementation
• APIs (Sequence) → Endpoint implementation
• Flow Diagrams → Business logic reference

dotnet-dev Integration

system-design-doc → dotnet-dev

Data passed:
• Entities → C# Model classes
• Relationships → EF Core configurations
• Data Dictionary → Database migrations
• APIs → Controller scaffolding

Output Files

Directory Structure

.design-docs/
├── design_doc_list.json          # Tracking file
├── system-design-[project].md    # Main document
├── diagrams/                     # (optional) Exported diagrams
│   ├── er-diagram.png
│   └── architecture.png
└── exports/                      # (optional) Exported formats
    ├── system-design.pdf
    └── system-design.docx

File Naming Convention

Type	Pattern	Example
Main Document	`system-design-[project-name].md`	`system-design-hr-management.md`
Tracking File	`design_doc_list.json`	-

Success Output Examples

Full Document

✅ สร้าง System Design Document สำเร็จ!

📁 File: .design-docs/system-design-hr-management.md

📊 Document Summary:
   • 10 sections completed
   • 7 diagrams (ER, 3 Flow, DFD L0+L1, Sitemap, 2 Sequence)
   • 12 tables in Data Dictionary
   • 4 User Roles defined

📈 Statistics:
   • Entities: 8
   • Relationships: 12
   • API Endpoints: 15
   • Pages: 20

💡 Next steps:
   • /ui-mockup → สร้าง UI Mockups จากเอกสาร
   • /validate-design-doc → ตรวจสอบความครบถ้วน

Single Diagram

✅ สร้าง ER Diagram สำเร็จ!

📊 ER Diagram:
   • Entities: 8
   • Relationships: 12

💡 Next steps:
   • /create-design-doc → สร้างเอกสารฉบับเต็ม
   • /create-diagram Data Dictionary → สร้าง DD

Resources

Resource	Location	Description
Codebase Analysis Guide	`references/codebase-analysis.md`	How to analyze code for various frameworks
Mermaid Patterns	`references/mermaid-patterns.md`	All diagram patterns
Architecture Patterns	`references/architecture-patterns.md`	Microservices, Event-driven, Clean, DDD
Document Sections	`references/document-sections.md`	Details of each section
Data Dictionary Template	`references/data-dictionary-template.md`	Data Dictionary format
Troubleshooting	`references/troubleshooting.md`	Common problem solutions
Full Template	`templates/design-doc-template.md`	Full document template
Tracking File	`templates/design_doc_list.json`	Tracking schema

Troubleshooting Quick Reference

Problem	Solution
Mermaid syntax error	See `references/troubleshooting.md` Section 1
No models found	Search with pattern `.entity.`, `.model.`
Missing relationships	Check DbContext, Fluent API, or migrations
ER ↔ DD mismatch	Check naming convention and column count
DFD inconsistency	Check external entities and data stores

Version History

Version	Date	Changes
1.4.0		- Added CRITICAL RULES with self-check checklist, output rejection criteria, and penalty- Added `/brainstorm-design` command (8-phase interactive brainstorming)- Added hybrid brainstorm auto-detect in `/create-design-doc`- Translated all content to English for AI comprehension
1.3.0	2025-01-25	Added /import-plan command, cross-plugin integration (/sync-with-mockups, /sync-with-features, /validate-integration), schema v2.1.0 with CRUD enabled/disabled + soft delete strategy
1.2.0	2025-01-20	Added 5 granular commands, architecture patterns, troubleshooting, tracking file
1.1.0	2024-12-15	Added DDD patterns, improved reverse engineering
1.0.0	2024-11-01	Initial release