Initial commit
This commit is contained in:
Zhongwei Li
@@ -0,0 +1,189 @@
|
||||
# Best Practices
|
||||
|
||||
Guidelines for creating clear, effective ASCII diagrams.
|
||||
|
||||
## Formatting Rules
|
||||
|
||||
### Width Constraints
|
||||
|
||||
**Maximum line width: 80 characters**
|
||||
|
||||
This ensures compatibility with:
|
||||
- Terminal windows
|
||||
- Code review tools
|
||||
- Markdown rendering
|
||||
- Email clients
|
||||
|
||||
```
|
||||
# Good - fits in 80 chars
|
||||
┌──────────────────────────────────────────────────────────────────────────┐
|
||||
|
||||
# Bad - exceeds 80 chars, will wrap
|
||||
┌────────────────────────────────────────────────────────────────────────────────────┐
|
||||
```
|
||||
|
||||
### Alignment
|
||||
|
||||
**Vertical alignment** creates visual hierarchy:
|
||||
|
||||
```
|
||||
# Good - aligned centers
|
||||
┌─────────┐
|
||||
│ Step 1 │
|
||||
└─────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────┐
|
||||
│ Step 2 │
|
||||
└─────────┘
|
||||
|
||||
# Bad - misaligned
|
||||
┌─────────┐
|
||||
│ Step 1 │
|
||||
└─────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────┐
|
||||
│ Step 2 │
|
||||
└─────────┘
|
||||
```
|
||||
|
||||
**Horizontal alignment** for side-by-side comparisons:
|
||||
|
||||
```
|
||||
# Good - columns aligned
|
||||
BEFORE: AFTER:
|
||||
├── file1.js ──► ├── file1.ts
|
||||
└── file2.js ──► └── file2.ts
|
||||
|
||||
# Bad - uneven columns
|
||||
BEFORE: AFTER:
|
||||
├── file1.js ──► ├── file1.ts
|
||||
└── file2.js ──► └── file2.ts
|
||||
```
|
||||
|
||||
### Spacing
|
||||
|
||||
Use blank lines to separate logical sections:
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────┐
|
||||
│ MIGRATION PLAN │
|
||||
└─────────────────────────────────────────────┘
|
||||
|
||||
PHASE 1: Analysis
|
||||
┌──────────────────┐
|
||||
│ Analyze current │
|
||||
└──────────────────┘
|
||||
|
||||
PHASE 2: Migration
|
||||
┌──────────────────┐
|
||||
│ Execute changes │
|
||||
└──────────────────┘
|
||||
```
|
||||
|
||||
## Clarity Guidelines
|
||||
|
||||
### Use Consistent Box Sizes
|
||||
|
||||
Keep related boxes the same width:
|
||||
|
||||
```
|
||||
# Good - consistent widths
|
||||
┌──────────────────┐ ┌──────────────────┐
|
||||
│ Component A │ │ Component B │
|
||||
└──────────────────┘ └──────────────────┘
|
||||
|
||||
# Bad - inconsistent
|
||||
┌────────┐ ┌────────────────────────┐
|
||||
│ Comp A │ │ Component B │
|
||||
└────────┘ └────────────────────────┘
|
||||
```
|
||||
|
||||
### Include Legends
|
||||
|
||||
When using symbols, explain them:
|
||||
|
||||
```
|
||||
┌──────────────────┐
|
||||
│ ✓ Database │
|
||||
│ ⏳ API │
|
||||
│ ✗ Legacy │
|
||||
└──────────────────┘
|
||||
|
||||
Legend:
|
||||
✓ = Complete
|
||||
⏳ = In Progress
|
||||
✗ = Removed
|
||||
```
|
||||
|
||||
### Group Related Items
|
||||
|
||||
Use visual proximity to show relationships:
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────┐
|
||||
│ FRONTEND LAYER │
|
||||
├─────────────────────────────────────────┤
|
||||
│ • React Components │
|
||||
│ • State Management │
|
||||
│ • Routing │
|
||||
└─────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────┐
|
||||
│ BACKEND LAYER │
|
||||
├─────────────────────────────────────────┤
|
||||
│ • API Endpoints │
|
||||
│ • Business Logic │
|
||||
│ • Database Access │
|
||||
└─────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Information Density
|
||||
|
||||
### Include Status Indicators
|
||||
|
||||
Show progress at a glance:
|
||||
|
||||
```
|
||||
│ ✓ Step 1: Setup │
|
||||
│ ✓ Step 2: Configuration │
|
||||
│ ⏳ Step 3: Migration │
|
||||
│ Step 4: Validation │
|
||||
```
|
||||
|
||||
### Show Counts When Relevant
|
||||
|
||||
Provide context with numbers:
|
||||
|
||||
```
|
||||
┌──────────────────┐
|
||||
│ Current State │
|
||||
│ 11 directories │
|
||||
│ 47 files │
|
||||
│ 3 duplicates │
|
||||
└──────────────────┘
|
||||
```
|
||||
|
||||
### Add Brief Descriptions
|
||||
|
||||
Clarify purpose without cluttering:
|
||||
|
||||
```
|
||||
┌──────────────────┐
|
||||
│ Auth Service │──► Handles JWT tokens
|
||||
│ 3 endpoints │──► Login, logout, refresh
|
||||
└──────────────────┘
|
||||
```
|
||||
|
||||
## Common Mistakes to Avoid
|
||||
|
||||
| Mistake | Problem | Solution |
|
||||
|---------|---------|----------|
|
||||
| Exceeding 80 chars | Wrapping breaks diagram | Split or abbreviate |
|
||||
| No legend | Symbols are confusing | Always include legend |
|
||||
| Inconsistent boxes | Looks unprofessional | Standardize widths |
|
||||
| Too much detail | Overwhelming | Simplify or split |
|
||||
| No spacing | Hard to read | Add blank lines |
|
||||
| Misaligned arrows | Confusing flow | Check alignment |
|
||||
237
skills/planning/ascii-diagram-creator/reference/diagram-types.md
Normal file
237
skills/planning/ascii-diagram-creator/reference/diagram-types.md
Normal file
@@ -0,0 +1,237 @@
|
||||
# Diagram Type Templates
|
||||
|
||||
Ready-to-use templates for each diagram type.
|
||||
|
||||
## 1. Architecture Diagram
|
||||
|
||||
**Purpose**: Show system components and their relationships.
|
||||
|
||||
### Basic Template
|
||||
|
||||
```
|
||||
┌─────────────────────────────────┐
|
||||
│ COMPONENT NAME │
|
||||
├─────────────────────────────────┤
|
||||
│ • Feature 1 │
|
||||
│ • Feature 2 │
|
||||
│ • Feature 3 │
|
||||
└─────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────┐
|
||||
│ CONNECTED COMPONENT │
|
||||
└─────────────────────────────────┘
|
||||
```
|
||||
|
||||
### Multi-Component Template
|
||||
|
||||
```
|
||||
┌───────────────┐ ┌───────────────┐
|
||||
│ Frontend │ │ Backend │
|
||||
├───────────────┤ ├───────────────┤
|
||||
│ • React │────►│ • Node.js │
|
||||
│ • Redux │ │ • Express │
|
||||
└───────────────┘ └───────────────┘
|
||||
│
|
||||
▼
|
||||
┌───────────────┐
|
||||
│ Database │
|
||||
├───────────────┤
|
||||
│ • PostgreSQL │
|
||||
└───────────────┘
|
||||
```
|
||||
|
||||
### When to Use
|
||||
|
||||
- Documenting service architecture
|
||||
- Explaining module relationships
|
||||
- Showing system overview
|
||||
- Onboarding new team members
|
||||
|
||||
---
|
||||
|
||||
## 2. Before/After Diagram
|
||||
|
||||
**Purpose**: Compare current vs proposed state.
|
||||
|
||||
### Basic Template
|
||||
|
||||
```
|
||||
BEFORE: AFTER:
|
||||
old/structure/ ──► new/structure/
|
||||
├── file1 KEPT ├── file1
|
||||
├── file2 MOVED ├── relocated/
|
||||
│ │ └── file2
|
||||
└── file3 DELETED
|
||||
```
|
||||
|
||||
### With Status Indicators
|
||||
|
||||
```
|
||||
CURRENT STATE: TARGET STATE:
|
||||
src/ src/
|
||||
├── components/ ✓ ├── components/
|
||||
│ ├── old.js ──► │ └── new.tsx
|
||||
│ └── legacy.js ✗ ├── features/
|
||||
├── utils/ 🔄 │ └── auth/
|
||||
│ └── helpers.js ──► └── shared/
|
||||
└── tests/ ✓ └── utils/
|
||||
```
|
||||
|
||||
### File Transformation
|
||||
|
||||
```
|
||||
BEFORE: AFTER:
|
||||
src/ src/
|
||||
├── Button.js ──► ├── Button.tsx ✓
|
||||
├── Button.css ──► │ (styles included)
|
||||
├── Form.js ──► ├── Form.tsx ✓
|
||||
├── Form.css ──► │ (styles included)
|
||||
└── utils.js ──► └── utils.ts ✓
|
||||
|
||||
Legend: ✓ = TypeScript conversion complete
|
||||
```
|
||||
|
||||
### When to Use
|
||||
|
||||
- Planning directory restructuring
|
||||
- Showing migration scope
|
||||
- Documenting refactoring changes
|
||||
- Creating PR descriptions
|
||||
|
||||
---
|
||||
|
||||
## 3. Phased Migration Diagram
|
||||
|
||||
**Purpose**: Show step-by-step progression with status.
|
||||
|
||||
### Basic Template
|
||||
|
||||
```
|
||||
┌────────────────────────────────┐
|
||||
│ PHASE 1: Description │
|
||||
│ Status: COMPLETE ✓ │
|
||||
│ Action: Specific task │
|
||||
└────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌────────────────────────────────┐
|
||||
│ PHASE 2: Description │
|
||||
│ Status: IN PROGRESS ⏳ │
|
||||
│ Action: Specific task │
|
||||
└────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌────────────────────────────────┐
|
||||
│ PHASE 3: Description │
|
||||
│ Status: PENDING │
|
||||
│ Action: Specific task │
|
||||
└────────────────────────────────┘
|
||||
```
|
||||
|
||||
### Detailed Migration Plan
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────┐
|
||||
│ SYSTEM CONSOLIDATION PLAN │
|
||||
└─────────────────────────────────────────────────────────┘
|
||||
|
||||
PHASE 1: Analysis ✓
|
||||
┌──────────────────┐
|
||||
│ Current State │──► Identify duplicates
|
||||
│ 11 directories │──► Find dependencies
|
||||
│ 3 systems │──► Check references
|
||||
└──────────────────┘
|
||||
│
|
||||
▼
|
||||
PHASE 2: Migration ⏳
|
||||
┌──────────────────┐
|
||||
│ Moving Data │
|
||||
│ ✓ Memory files │
|
||||
│ ✓ Pattern files │
|
||||
│ ⏳ Script updates │
|
||||
└──────────────────┘
|
||||
│
|
||||
▼
|
||||
PHASE 3: Validation
|
||||
┌──────────────────┐
|
||||
│ Final State │
|
||||
│ 2 directories │──► All tests passing
|
||||
│ 1 unified system │──► No duplicates
|
||||
└──────────────────┘
|
||||
```
|
||||
|
||||
### When to Use
|
||||
|
||||
- Tracking multi-phase projects
|
||||
- Showing progress through stages
|
||||
- Planning sequential changes
|
||||
- Sprint/milestone planning
|
||||
|
||||
---
|
||||
|
||||
## 4. Data Flow Diagram
|
||||
|
||||
**Purpose**: Illustrate how data moves through the system.
|
||||
|
||||
### Basic Template
|
||||
|
||||
```
|
||||
Input ──► Process ──► Output
|
||||
▲ │ │
|
||||
│ ▼ ▼
|
||||
Feedback Storage Display
|
||||
```
|
||||
|
||||
### API Request Flow
|
||||
|
||||
```
|
||||
┌────────┐ ┌────────────┐ ┌──────────┐
|
||||
│ Client │────►│ API Gateway│────►│ Service │
|
||||
└────────┘ └────────────┘ └──────────┘
|
||||
▲ │
|
||||
│ ▼
|
||||
│ ┌──────────┐
|
||||
└────────────────────────────│ Database │
|
||||
Response with data └──────────┘
|
||||
```
|
||||
|
||||
### Authentication Flow
|
||||
|
||||
```
|
||||
User Input
|
||||
│
|
||||
▼
|
||||
┌──────────────┐
|
||||
│ Login Form │
|
||||
└──────────────┘
|
||||
│
|
||||
▼
|
||||
┌──────────────┐ ┌──────────────┐
|
||||
│ Auth Service │────►│ Token Store │
|
||||
└──────────────┘ └──────────────┘
|
||||
│ │
|
||||
▼ │
|
||||
┌──────────────┐ │
|
||||
│ JWT Token │◄───────────┘
|
||||
└──────────────┘
|
||||
│
|
||||
▼
|
||||
Protected Resources
|
||||
```
|
||||
|
||||
### Data Pipeline
|
||||
|
||||
```
|
||||
Raw Data ──► Validate ──► Transform ──► Store ──► Display
|
||||
│ │ │
|
||||
▼ ▼ ▼
|
||||
Errors Logs Analytics
|
||||
```
|
||||
|
||||
### When to Use
|
||||
|
||||
- Explaining API request/response flow
|
||||
- Documenting data pipelines
|
||||
- Showing processing steps
|
||||
- Illustrating system integrations
|
||||
@@ -0,0 +1,233 @@
|
||||
# Mermaid Export Guide
|
||||
|
||||
Convert ASCII diagrams to Mermaid syntax for graphical rendering in GitHub, GitLab, Notion, and other platforms that support Mermaid.
|
||||
|
||||
## When to Use Mermaid Export
|
||||
|
||||
- Documentation that will be viewed in GitHub/GitLab (renders automatically)
|
||||
- Presentations where graphical output is preferred
|
||||
- Teams that prefer visual diagrams over text-based
|
||||
- When you need to iterate on diagrams in a visual editor
|
||||
|
||||
## Conversion Rules
|
||||
|
||||
### Basic Elements
|
||||
|
||||
| ASCII Element | Mermaid Syntax | Example |
|
||||
|---------------|----------------|---------|
|
||||
| `┌─────┐` Box | `[Label]` | `A[Component]` |
|
||||
| `(( ))` Circle | `((Label))` | `A((Start))` |
|
||||
| `{ }` Diamond | `{Label}` | `A{Decision}` |
|
||||
| `──►` Arrow | `-->` | `A --> B` |
|
||||
| `◄──` Reverse | `<--` | `A <-- B` |
|
||||
| `◄─►` Bidirectional | `<-->` | `A <--> B` |
|
||||
| `──✗` Blocked | `-.-x` | `A -.-x B` |
|
||||
| Text on arrow | `-- text -->` | `A -- calls --> B` |
|
||||
|
||||
### Container Elements
|
||||
|
||||
| ASCII Pattern | Mermaid Equivalent |
|
||||
|--------------|-------------------|
|
||||
| Nested boxes | `subgraph` |
|
||||
| Grouped components | `subgraph "Name"` |
|
||||
| Layers | Multiple subgraphs |
|
||||
|
||||
### Status Indicators
|
||||
|
||||
Use Mermaid classes for status styling:
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
A[Complete]:::done
|
||||
B[In Progress]:::pending
|
||||
C[Blocked]:::blocked
|
||||
|
||||
classDef done fill:#90EE90
|
||||
classDef pending fill:#FFE4B5
|
||||
classDef blocked fill:#FFB6C1
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Conversion Examples
|
||||
|
||||
### Architecture Diagram
|
||||
|
||||
**ASCII Input**:
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ APPLICATION ARCHITECTURE │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
|
||||
│ │ app/ │ │ features/ │ │ shared/ │ │
|
||||
│ │ (routes) │────►│ (domains) │────►│ (common) │ │
|
||||
│ └─────────────┘ └─────────────┘ └─────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
**Mermaid Output**:
|
||||
```mermaid
|
||||
graph LR
|
||||
subgraph "Application Architecture"
|
||||
A[app/<br/>routes] --> B[features/<br/>domains]
|
||||
B --> C[shared/<br/>common]
|
||||
end
|
||||
```
|
||||
|
||||
### Before/After Diagram
|
||||
|
||||
**ASCII Input**:
|
||||
```
|
||||
BEFORE AFTER
|
||||
┌──────────────┐ ┌──────────────┐
|
||||
│ Monolith │ │ Service A │
|
||||
│ All-in-one │ ──► ├──────────────┤
|
||||
│ │ │ Service B │
|
||||
└──────────────┘ └──────────────┘
|
||||
```
|
||||
|
||||
**Mermaid Output**:
|
||||
```mermaid
|
||||
graph LR
|
||||
subgraph Before
|
||||
A[Monolith<br/>All-in-one]
|
||||
end
|
||||
|
||||
subgraph After
|
||||
B[Service A]
|
||||
C[Service B]
|
||||
end
|
||||
|
||||
A -.-> B
|
||||
A -.-> C
|
||||
```
|
||||
|
||||
### Phased Migration Diagram
|
||||
|
||||
**ASCII Input**:
|
||||
```
|
||||
PHASE 1: Analysis PHASE 2: Migration PHASE 3: Validation
|
||||
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
|
||||
│ ✓ Complete │───────►│ ⏳ In Progress│────────►│ ○ Pending │
|
||||
└──────────────┘ └──────────────┘ └──────────────┘
|
||||
```
|
||||
|
||||
**Mermaid Output**:
|
||||
```mermaid
|
||||
graph LR
|
||||
A[Phase 1<br/>Analysis]:::done --> B[Phase 2<br/>Migration]:::pending
|
||||
B --> C[Phase 3<br/>Validation]:::future
|
||||
|
||||
classDef done fill:#90EE90,stroke:#228B22
|
||||
classDef pending fill:#FFE4B5,stroke:#FF8C00
|
||||
classDef future fill:#E0E0E0,stroke:#808080
|
||||
```
|
||||
|
||||
### Data Flow Diagram
|
||||
|
||||
**ASCII Input**:
|
||||
```
|
||||
┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐
|
||||
│ User │────►│ API │────►│ Service │────►│ DB │
|
||||
└─────────┘ └─────────┘ └─────────┘ └─────────┘
|
||||
▲ │
|
||||
└──────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
**Mermaid Output**:
|
||||
```mermaid
|
||||
graph LR
|
||||
A[User] --> B[API]
|
||||
B --> C[Service]
|
||||
C --> D[DB]
|
||||
D --> A
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Direction Options
|
||||
|
||||
Choose the flow direction based on diagram type:
|
||||
|
||||
| Direction | Syntax | Best For |
|
||||
|-----------|--------|----------|
|
||||
| Left to Right | `graph LR` | Data flows, pipelines |
|
||||
| Top to Bottom | `graph TD` | Hierarchies, architecture |
|
||||
| Bottom to Top | `graph BT` | Bottom-up structures |
|
||||
| Right to Left | `graph RL` | Reverse flows |
|
||||
|
||||
---
|
||||
|
||||
## Advanced Features
|
||||
|
||||
### Subgraph Nesting
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
subgraph "Frontend"
|
||||
subgraph "Components"
|
||||
A[Button]
|
||||
B[Form]
|
||||
end
|
||||
subgraph "Pages"
|
||||
C[Home]
|
||||
D[Dashboard]
|
||||
end
|
||||
end
|
||||
|
||||
C --> A
|
||||
D --> B
|
||||
```
|
||||
|
||||
### Click Events (for interactive diagrams)
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
A[Component]
|
||||
click A "https://github.com/repo/component" "View source"
|
||||
```
|
||||
|
||||
### Notes and Comments
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
A[Start] --> B[Process]
|
||||
B --> C[End]
|
||||
|
||||
%% This is a comment
|
||||
%% Comments don't render
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Platform Support
|
||||
|
||||
| Platform | Support | Notes |
|
||||
|----------|---------|-------|
|
||||
| GitHub | ✓ Native | Renders in markdown files and issues |
|
||||
| GitLab | ✓ Native | Renders in markdown |
|
||||
| Notion | ✓ Native | Use `/mermaid` block |
|
||||
| VS Code | ✓ Extension | Mermaid Preview extension |
|
||||
| Obsidian | ✓ Native | Built-in support |
|
||||
| Confluence | ⚠️ Plugin | Requires Mermaid plugin |
|
||||
|
||||
---
|
||||
|
||||
## Conversion Tips
|
||||
|
||||
1. **Keep it simple**: ASCII diagrams with many nested elements may not convert cleanly
|
||||
2. **Use subgraphs sparingly**: More than 2-3 levels of nesting gets hard to read
|
||||
3. **Add line breaks**: Use `<br/>` in node labels for multi-line text
|
||||
4. **Test rendering**: Preview in GitHub/GitLab before committing
|
||||
5. **Preserve ASCII version**: Keep both formats for different use cases
|
||||
|
||||
---
|
||||
|
||||
## Quick Conversion Checklist
|
||||
|
||||
- [ ] Identify all boxes → Convert to nodes `[Label]`
|
||||
- [ ] Identify all arrows → Convert to connections `-->`
|
||||
- [ ] Identify groupings → Convert to `subgraph`
|
||||
- [ ] Identify status indicators → Add `classDef` styles
|
||||
- [ ] Choose direction (`LR` vs `TD`)
|
||||
- [ ] Test rendering in target platform
|
||||
@@ -0,0 +1,237 @@
|
||||
# Project-Type Templates
|
||||
|
||||
Pre-built architecture diagram templates for common project types. Use these as starting points after auto-discovery detects the project type.
|
||||
|
||||
## Template Selection
|
||||
|
||||
| Project Type | Detection Signals | Template |
|
||||
|--------------|-------------------|----------|
|
||||
| Bulletproof React | `src/features/*`, eslint-plugin-import | [bulletproof-react](#bulletproof-react) |
|
||||
| Next.js App Router | `src/app/**/page.tsx`, next.config.* | [next-app-router](#nextjs-app-router) |
|
||||
| Express API | express in deps, `routes/*` or `controllers/*` | [express-api](#express-api) |
|
||||
| Monorepo (Nx/Turborepo) | `packages/*` or `apps/*`, workspace config | [monorepo](#monorepo) |
|
||||
| Generic Full-Stack | Mixed patterns | [generic-fullstack](#generic-full-stack) |
|
||||
|
||||
---
|
||||
|
||||
## Bulletproof React
|
||||
|
||||
**Detection**: `src/features/*/index.{ts,tsx}` + eslint-plugin-import
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ APPLICATION ARCHITECTURE │
|
||||
├─────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
|
||||
│ │ app/ │ │ features/ │ │ shared/ │ │
|
||||
│ │ (routes) │────►│ (domains) │────►│ (common) │ │
|
||||
│ └─────────────┘ └─────────────┘ └─────────────┘ │
|
||||
│ │ │ │ │
|
||||
│ ▼ ▼ ▼ │
|
||||
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
|
||||
│ │ routes/ │ │ components/ │ │ lib/ │ │
|
||||
│ │ layouts/ │ │ hooks/ │ │ types/ │ │
|
||||
│ │ │ │ api/ │ │ utils/ │ │
|
||||
│ └─────────────┘ └─────────────┘ └─────────────┘ │
|
||||
│ │
|
||||
├─────────────────────────────────────────────────────────────────┤
|
||||
│ Import Rules: app → features → shared (unidirectional) │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
**Populate with**:
|
||||
- Features from `glob: src/features/*/index.ts`
|
||||
- Routes from `glob: src/app/**`
|
||||
- Cross-feature deps from `grep: import.*from '@/features`
|
||||
|
||||
---
|
||||
|
||||
## Next.js App Router
|
||||
|
||||
**Detection**: `app/**/page.tsx` + `next.config.*`
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ NEXT.JS APP STRUCTURE │
|
||||
├─────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ ┌──────────────────────────────────────────────────────┐ │
|
||||
│ │ app/ │ │
|
||||
│ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ │
|
||||
│ │ │ layout │ │ page │ │ loading │ │ error │ │ │
|
||||
│ │ └─────────┘ └─────────┘ └─────────┘ └─────────┘ │ │
|
||||
│ │ │ │ │ │
|
||||
│ │ ▼ ▼ │ │
|
||||
│ │ ┌─────────────────────────────────────────────┐ │ │
|
||||
│ │ │ Route Groups │ │ │
|
||||
│ │ │ (auth)/ (dashboard)/ (public)/ │ │ │
|
||||
│ │ └─────────────────────────────────────────────┘ │ │
|
||||
│ └──────────────────────────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
|
||||
│ │ components/ │ │ lib/ │ │ types/ │ │
|
||||
│ │ (UI) │ │ (server) │ │ (shared) │ │
|
||||
│ └─────────────┘ └─────────────┘ └─────────────┘ │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
**Populate with**:
|
||||
- Route groups from `glob: src/app/(*)/`
|
||||
- Dynamic routes from `glob: src/app/**/[*]`
|
||||
- Server actions from `grep: "use server"`
|
||||
|
||||
---
|
||||
|
||||
## Express API
|
||||
|
||||
**Detection**: `express` in dependencies + `routes/*` or `controllers/*`
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ EXPRESS API LAYERS │
|
||||
├─────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ Request ──► ┌──────────────────────────────────┐ │
|
||||
│ │ Middleware Layer │ │
|
||||
│ │ auth │ validation │ rate-limit │ │
|
||||
│ └──────────────┬───────────────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌──────────────────────────────────┐ │
|
||||
│ │ Routes Layer │ │
|
||||
│ │ /api/users │ /api/products │ │
|
||||
│ └──────────────┬───────────────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌──────────────────────────────────┐ │
|
||||
│ │ Controllers Layer │ │
|
||||
│ │ userController │ productCtrl │ │
|
||||
│ └──────────────┬───────────────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌──────────────────────────────────┐ │
|
||||
│ │ Services Layer │ │
|
||||
│ │ userService │ productService │ │
|
||||
│ └──────────────┬───────────────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌──────────────────────────────────┐ │
|
||||
│ │ Data Layer │ │
|
||||
│ │ models │ repositories │ db │ │
|
||||
│ └──────────────────────────────────┘ │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
**Populate with**:
|
||||
- Routes from `glob: routes/*.js` or `grep: router\.(get|post|put|delete)`
|
||||
- Controllers from `glob: controllers/*.js`
|
||||
- Models from `glob: models/*.js`
|
||||
|
||||
---
|
||||
|
||||
## Monorepo
|
||||
|
||||
**Detection**: `packages/*` or `apps/*` + workspace config (nx.json, turbo.json, pnpm-workspace.yaml)
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ MONOREPO STRUCTURE │
|
||||
├─────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────┐ │
|
||||
│ │ apps/ │ │
|
||||
│ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ │
|
||||
│ │ │ web │ │ admin │ │ api │ │ │
|
||||
│ │ └────┬────┘ └────┬────┘ └────┬────┘ │ │
|
||||
│ └────────┼─────────────┼────────────┼──────────────────┘ │
|
||||
│ │ │ │ │
|
||||
│ └─────────────┼────────────┘ │
|
||||
│ ▼ │
|
||||
│ ┌─────────────────────────────────────────────────────┐ │
|
||||
│ │ packages/ │ │
|
||||
│ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ │
|
||||
│ │ │ ui │ │ utils │ │ types │ │ │
|
||||
│ │ └─────────┘ └─────────┘ └─────────┘ │ │
|
||||
│ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ │
|
||||
│ │ │ config │ │ api │ │ eslint │ │ │
|
||||
│ │ └─────────┘ └─────────┘ └─────────┘ │ │
|
||||
│ └─────────────────────────────────────────────────────┘ │
|
||||
│ │
|
||||
├─────────────────────────────────────────────────────────────────┤
|
||||
│ Dependency Flow: apps → packages (unidirectional) │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
**Populate with**:
|
||||
- Apps from `glob: apps/*/package.json`
|
||||
- Packages from `glob: packages/*/package.json`
|
||||
- Internal deps from each package.json dependencies
|
||||
|
||||
---
|
||||
|
||||
## Generic Full-Stack
|
||||
|
||||
**Detection**: Mixed patterns or undetected project type
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ FULL-STACK APPLICATION │
|
||||
├─────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ ┌─────────────────────┐ ┌─────────────────────┐ │
|
||||
│ │ Frontend │ │ Backend │ │
|
||||
│ │ ┌───────────┐ │ │ ┌───────────┐ │ │
|
||||
│ │ │ UI │ │ │ │ API │ │ │
|
||||
│ │ │Components │ │ ──► │ │ Routes │ │ │
|
||||
│ │ └───────────┘ │ │ └───────────┘ │ │
|
||||
│ │ ┌───────────┐ │ │ ┌───────────┐ │ │
|
||||
│ │ │ State │ │ │ │ Services │ │ │
|
||||
│ │ │Management │ │ │ │ Business │ │ │
|
||||
│ │ └───────────┘ │ │ └───────────┘ │ │
|
||||
│ │ ┌───────────┐ │ │ ┌───────────┐ │ │
|
||||
│ │ │ API │ │ │ │ Data │ │ │
|
||||
│ │ │ Client │ │ │ │ Layer │ │ │
|
||||
│ │ └───────────┘ │ │ └───────────┘ │ │
|
||||
│ └─────────────────────┘ └─────────────────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌─────────────────────┐ │
|
||||
│ │ Database │ │
|
||||
│ └─────────────────────┘ │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
**Populate with**:
|
||||
- Manual discovery based on directory structure
|
||||
- `ls src/` or `tree -L 2` for structure overview
|
||||
|
||||
---
|
||||
|
||||
## Usage Instructions
|
||||
|
||||
1. **Auto-detect project type** using Phase 0 discovery commands
|
||||
2. **Select matching template** from this reference
|
||||
3. **Run populate commands** to fill in actual component names
|
||||
4. **Customize** by adding/removing boxes based on actual architecture
|
||||
5. **Add diagram metadata** for versioning (see below)
|
||||
|
||||
### Adding Diagram Metadata
|
||||
|
||||
Include this comment block at the top of generated diagrams:
|
||||
|
||||
```markdown
|
||||
<!-- diagram-meta
|
||||
type: [template-name]
|
||||
created: YYYY-MM-DD
|
||||
last-verified: YYYY-MM-DD
|
||||
source-patterns: [glob patterns used]
|
||||
stale-after: 30d
|
||||
-->
|
||||
```
|
||||
|
||||
This enables automated staleness detection when the codebase structure changes.
|
||||
@@ -0,0 +1,162 @@
|
||||
# Visual Elements Reference
|
||||
|
||||
Complete reference for all ASCII diagram visual elements.
|
||||
|
||||
## Box Drawing Characters
|
||||
|
||||
### Basic Box
|
||||
|
||||
```
|
||||
┌─────────────────┐
|
||||
│ Content │
|
||||
└─────────────────┘
|
||||
```
|
||||
|
||||
### Box with Header
|
||||
|
||||
```
|
||||
┌─────────────────┐
|
||||
│ HEADER │
|
||||
├─────────────────┤
|
||||
│ Content │
|
||||
└─────────────────┘
|
||||
```
|
||||
|
||||
### Box with Multiple Sections
|
||||
|
||||
```
|
||||
┌─────────────────┐
|
||||
│ Section 1 │
|
||||
├─────────────────┤
|
||||
│ Section 2 │
|
||||
├─────────────────┤
|
||||
│ Section 3 │
|
||||
└─────────────────┘
|
||||
```
|
||||
|
||||
### Character Reference
|
||||
|
||||
| Character | Name | Usage |
|
||||
|-----------|------|-------|
|
||||
| `┌` | Top-left corner | Start of box |
|
||||
| `┐` | Top-right corner | End of top border |
|
||||
| `└` | Bottom-left corner | Start of bottom border |
|
||||
| `┘` | Bottom-right corner | End of box |
|
||||
| `─` | Horizontal line | Top/bottom borders |
|
||||
| `│` | Vertical line | Side borders |
|
||||
| `├` | Left T-junction | Left side divider |
|
||||
| `┤` | Right T-junction | Right side divider |
|
||||
| `┬` | Top T-junction | Top divider |
|
||||
| `┴` | Bottom T-junction | Bottom divider |
|
||||
| `┼` | Cross junction | Grid intersection |
|
||||
|
||||
## Arrows
|
||||
|
||||
### Directional Arrows
|
||||
|
||||
| Arrow | Name | Meaning |
|
||||
|-------|------|---------|
|
||||
| `──►` | Right arrow | Forward flow, transformation |
|
||||
| `◄──` | Left arrow | Reverse flow, feedback |
|
||||
| `◄─►` | Bidirectional | Two-way communication |
|
||||
| `│` + `▼` | Down arrow | Vertical flow downward |
|
||||
| `│` + `▲` | Up arrow | Vertical flow upward |
|
||||
|
||||
### Status Arrows
|
||||
|
||||
| Arrow | Meaning | Example Use |
|
||||
|-------|---------|-------------|
|
||||
| `──✓` | Approved/kept | Retained items in migration |
|
||||
| `──✗` | Blocked/removed | Deleted items |
|
||||
|
||||
### Creating Vertical Flow
|
||||
|
||||
```
|
||||
┌─────────┐
|
||||
│ Step 1 │
|
||||
└─────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────┐
|
||||
│ Step 2 │
|
||||
└─────────┘
|
||||
```
|
||||
|
||||
## Status Indicators
|
||||
|
||||
### Progress Symbols
|
||||
|
||||
| Symbol | Meaning | When to Use |
|
||||
|--------|---------|-------------|
|
||||
| `✓` | Complete/done | Finished tasks, kept items |
|
||||
| `✗` | Removed/failed | Deleted items, blocked tasks |
|
||||
| `⏳` | In progress | Currently active work |
|
||||
| `🔄` | Migrated/moved | Relocated items |
|
||||
|
||||
### Alert Symbols
|
||||
|
||||
| Symbol | Meaning | When to Use |
|
||||
|--------|---------|-------------|
|
||||
| `⚠️` | Warning | Needs attention |
|
||||
| `🔴` | Critical | Urgent issue |
|
||||
|
||||
### Using Status in Diagrams
|
||||
|
||||
```
|
||||
┌──────────────────┐
|
||||
│ Migration Status │
|
||||
├──────────────────┤
|
||||
│ ✓ Database │
|
||||
│ ✓ API endpoints │
|
||||
│ ⏳ Frontend │
|
||||
│ ✗ Legacy cleanup │
|
||||
└──────────────────┘
|
||||
```
|
||||
|
||||
## Tree Structures
|
||||
|
||||
### Directory Tree
|
||||
|
||||
```
|
||||
project/
|
||||
├── src/
|
||||
│ ├── components/
|
||||
│ │ ├── Button.tsx
|
||||
│ │ └── Form.tsx
|
||||
│ └── utils/
|
||||
│ └── helpers.ts
|
||||
└── tests/
|
||||
└── unit/
|
||||
```
|
||||
|
||||
### Tree Characters
|
||||
|
||||
| Character | Usage |
|
||||
|-----------|-------|
|
||||
| `├──` | Branch with more siblings below |
|
||||
| `└──` | Last branch (no more siblings) |
|
||||
| `│` | Vertical continuation |
|
||||
|
||||
## Combining Elements
|
||||
|
||||
### Architecture with Status
|
||||
|
||||
```
|
||||
┌─────────────────────┐
|
||||
│ API Gateway ✓ │
|
||||
└─────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────┐
|
||||
│ Auth Service ⏳ │
|
||||
└─────────────────────┘
|
||||
```
|
||||
|
||||
### Before/After with Arrows
|
||||
|
||||
```
|
||||
BEFORE: AFTER:
|
||||
├── old.js ──► ├── new.ts ✓
|
||||
├── temp.js ──✗ └── utils.ts ✓
|
||||
└── legacy.js ──✗
|
||||
```
|
||||
Reference in New Issue
Block a user