@@ -23,12 +23,13 @@ design to implementation:
2323
2424``` text
2525docs/design/
26- ├── introduction.md # Design overview with software structure
27- ├── system.md # System-level design documentation
28- ├── {subsystem-name}/ # Subsystem design documents (kebab-case folder names)
29- │ ├── {subsystem-name}.md # Subsystem overview and design
30- │ └── {unit-name}.md # Unit-level design documents
31- └── {unit-name}.md # Top-level unit design documents (if not in subsystem)
26+ ├── introduction.md # Design overview with software structure
27+ └── {system-name}/ # System-level design folder (one per system)
28+ ├── {system-name}.md # System-level design documentation
29+ ├── {subsystem-name}/ # Subsystem design documents (kebab-case folder names)
30+ │ ├── {subsystem-name}.md # Subsystem overview and design
31+ │ └── {unit-name}.md # Unit-level design documents
32+ └── {unit-name}.md # Top-level unit design documents (if not in subsystem)
3233```
3334
3435## introduction.md (MANDATORY)
@@ -56,13 +57,16 @@ to understand these classifications before creating this section.
5657Example format:
5758
5859``` text
59- ProjectName (System)
60+ Project1Name (System)
6061├── ComponentA (Subsystem)
6162│ ├── ClassX (Unit)
6263│ └── ClassY (Unit)
6364├── ComponentB (Subsystem)
6465│ └── ClassZ (Unit)
6566└── UtilityClass (Unit)
67+
68+ Project2Name (System)
69+ └── HelperClass (Unit)
6670```
6771
6872### Folder Layout Section (MANDATORY)
@@ -73,34 +77,39 @@ mirror the software structure, with file paths and brief descriptions.
7377Example format:
7478
7579``` text
76- src/ProjectName /
80+ src/Project1Name /
7781├── ComponentA/
78- │ ├── ClassX.cs — brief description
79- │ └── ClassY.cs — brief description
82+ │ ├── ClassX.cs — Core business logic handler
83+ │ └── ClassY.cs — Data validation service
8084├── ComponentB/
81- │ └── ClassZ.cs — brief description
82- └── UtilityClass.cs — brief description
85+ │ └── ClassZ.cs — Integration interface
86+ └── UtilityClass.cs — Common utility functions
87+
88+ src/Project2Name/
89+ └── HelperClass.cs — Helper functions
8390```
8491
85- ## system.md (MANDATORY)
92+ ## System Design Documentation (MANDATORY)
8693
87- The ` system.md ` file contains system-level design documentation including :
94+ For each system identified in the repository :
8895
89- - System architecture and major components
90- - External interfaces and dependencies
91- - Data flow and control flow
92- - System-wide design constraints and decisions
93- - Integration patterns and communication protocols
96+ - Create a kebab-case folder matching the system name
97+ - Include ` {system-name}.md ` with system-level design documentation such as:
98+ - System architecture and major components
99+ - External interfaces and dependencies
100+ - Data flow and control flow
101+ - System-wide design constraints and decisions
102+ - Integration patterns and communication protocols
94103
95104## Subsystem and Unit Design Documents
96105
97106For each subsystem identified in the software structure:
98107
99108- Create a kebab-case folder matching the subsystem name (enables automated tooling)
100109- Include ` {subsystem-name}.md ` with subsystem overview and design
101- - Include unit design documents for complex units within the subsystem
110+ - Include unit design documents for ALL units within the subsystem
102111
103- For significant units requiring detailed design :
112+ For every unit identified in the software structure :
104113
105114- Document data models, algorithms, and key methods
106115- Describe interactions with other units
@@ -124,19 +133,21 @@ implementation specification for formal code review:
124133- ** Implementation Detail** : Provide sufficient detail for code review and implementation
125134- ** Architectural Clarity** : Clearly define component boundaries and interfaces
126135- ** Traceability** : Link to requirements where applicable using ReqStream patterns
127- - ** Concrete Examples** : Use actual class names, method signatures, and data structures
128- - ** Current Information** : Keep synchronized with code changes and refactoring
136+
137+ # Mermaid Diagram Integration
138+
139+ Use Mermaid diagrams to supplement text descriptions (diagrams must not replace text content).
129140
130141# Quality Checks
131142
132143Before submitting design documentation, verify:
133144
134145- [ ] ` introduction.md ` includes both Software Structure and Folder Layout sections
135146- [ ] Software structure correctly categorizes items as System/Subsystem/Unit per ` software-items.md `
136- - [ ] Folder layout matches actual source code organization
137- - [ ] ` system.md ` provides comprehensive system-level design
147+ - [ ] Folder layout mirrors software structure organization
148+ - [ ] Design documents provide sufficient detail for code review
149+ - [ ] System documentation provides comprehensive system-level design
138150- [ ] Subsystem documentation folders use kebab-case names while mirroring source subsystem names and structure
139- - [ ] Design documents contain sufficient implementation detail
140151- [ ] All documents follow technical documentation formatting standards
141152- [ ] Content is current with implementation and requirements
142153- [ ] Documents are integrated into ReviewMark review-sets for formal review
0 commit comments