diagram — Skillopedia

Diagram Driven Development (DDD) Skill Maintain the directory as the single source of truth for system understanding. All diagrams follow DDD principles, connecting Front-Stage (user experience) to Back-Stage (technical implementation) with clear impact annotations. Capabilities 1. Create Diagrams - Generate new diagrams for features, architectures, journeys, tests, and refactorings 2. Update Diagrams - Synchronize existing diagrams with code changes 3. Audit Diagrams - Identify outdated, missing, or low-quality diagrams 4. Organize Diagrams - Maintain consistent structure and naming conventi…

&& echo \"Bad name: $file\"\ndone\n\n# Find files in wrong directories\nfind ai/diagrams/features -name \"*.md\" | while read file; do\n basename \"$file\" | grep -vE '^feature-' && echo \"Wrong directory: $file\"\ndone\n```\n\n### Step 3: Check Index Completeness\n\nCompare diagrams on filesystem with README.md index:\n\n```bash\n# List all diagrams\nfind ai/diagrams -name \"*.md\" -not -name \"README.md\" | sort > /tmp/all-diagrams.txt\n\n# Extract diagrams from README\ngrep -oP '\\[.*?\\]\\(\\K[^)]+' ai/diagrams/README.md | sort > /tmp/indexed-diagrams.txt\n\n# Find diagrams not in index\ncomm -23 /tmp/all-diagrams.txt /tmp/indexed-diagrams.txt\n```\n\n### Step 4: Create Organization Report\n\n```markdown\n# Diagram Organization Audit Report\n\n**Date:** YYYY-MM-DD\n\n## Directory Structure\n\n- ✅ All expected directories exist\n- ⚠️ Found unexpected directory: `ai/diagrams/old/`\n - Action: Review and move or delete\n\n## File Naming Issues\n\n1. ❌ `ai/diagrams/features/checkout.md`\n - Issue: Missing type prefix\n - Should be: `feature-checkout-flow.md`\n\n2. ❌ `ai/diagrams/journeys/UserAuthenticationFlow.md`\n - Issue: Wrong case\n - Should be: `sequence-user-authentication-journey.md`\n\n3. ❌ `ai/diagrams/arch-microservices.md`\n - Issue: Not in correct directory\n - Should be: `ai/diagrams/architecture/arch-microservices.md`\n\n## Index Completeness\n\n### Missing from Index\n\n1. `features/feature-notification-system.md`\n2. `refactoring/feature-add-caching-layer.md`\n\n### Broken Links in Index\n\n1. `[User Auth](journeys/auth-flow.md)` → File doesn't exist\n\n## Recommendations\n\n1. Rename files to follow convention\n2. Move misplaced files to correct directories\n3. Update README.md index\n4. Delete obsolete directories\n5. Fix broken links\n```\n\n## Automated Audit Script\n\n```bash\n#!/bin/bash\n# audit-diagrams.sh\n\necho \"=== DIAGRAM AUDIT ===\"\necho \"\"\n\n# Quality Check\necho \"## Quality Checks\"\necho \"\"\necho \"Checking for diagrams missing key sections...\"\nfor file in ai/diagrams/**/*.md; do\n if [ \"$file\" = \"ai/diagrams/README.md\" ]; then continue; fi\n\n echo \"Checking: $file\"\n\n # Check for required sections\n grep -q \"^## Purpose\" \"$file\" || echo \" ❌ Missing Purpose section\"\n grep -q \"^## Diagram\" \"$file\" || echo \" ❌ Missing Diagram section\"\n grep -q \"^## Key Insights\" \"$file\" || echo \" ❌ Missing Key Insights\"\n grep -q \"^## Change History\" \"$file\" || echo \" ❌ Missing Change History\"\n\n # Check for Front-Stage/Back-Stage\n grep -q \"Front-Stage\" \"$file\" || echo \" ⚠️ No Front-Stage mention\"\n grep -q \"Back-Stage\" \"$file\" || echo \" ⚠️ No Back-Stage mention\"\n\n # Check for impact annotations\n grep -q \"[⚡💾🛡️✅⏱️🔄📊🎯]\" \"$file\" || echo \" ⚠️ No impact annotation symbols found\"\n\n echo \"\"\ndone\n\n# Coverage Check\necho \"## Coverage Check\"\necho \"\"\necho \"Features/Services:\"\nfind src/features -type d -depth 1 | while read dir; do\n feature=$(basename \"$dir\")\n if ! grep -q \"$feature\" ai/diagrams/**/*.md; then\n echo \" ❌ No diagram for: $feature\"\n fi\ndone\n\n# Sync Check\necho \"## Synchronization Check\"\necho \"\"\necho \"Diagrams with outdated timestamps:\"\nfind ai/diagrams -name \"*.md\" -not -name \"README.md\" | while read file; do\n # Extract last updated date\n date=$(grep -oP '^\\*\\*Last Updated:\\*\\* \\K[0-9-]+' \"$file\")\n\n if [ -z \"$date\" ]; then\n echo \" ❌ $file: No last updated date\"\n continue\n fi\n\n # Check if older than 90 days\n date_seconds=$(date -d \"$date\" +%s)\n now_seconds=$(date +%s)\n age_days=$(( ($now_seconds - $date_seconds) / 86400 ))\n\n if [ $age_days -gt 90 ]; then\n echo \" ⚠️ $file: $age_days days old\"\n fi\ndone\n\necho \"\"\necho \"=== AUDIT COMPLETE ===\"\n```\n\n## Best Practices\n\n1. **Schedule regular audits** - Monthly for active projects\n2. **Automate what you can** - Use scripts to catch obvious issues\n3. **Prioritize fixes** - Focus on high-impact diagrams first\n4. **Track improvements** - Measure quality over time\n5. **Make it a habit** - Include audits in sprint reviews\n6. **Document findings** - Create actionable reports\n7. **Set standards** - Define acceptable quality thresholds\n8. **Continuous improvement** - Learn from audit findings\n\n## Audit Frequency\n\n### Weekly\n- Quick sync check (are recent code changes reflected?)\n- Index completeness check\n\n### Monthly\n- Full quality audit\n- Coverage audit for new features\n- Organization audit\n\n### Quarterly\n- Comprehensive audit of all diagrams\n- Review and update DDD standards\n- Analyze audit trend data\n\n## Metrics to Track\n\nTrack these over time:\n- Total number of diagrams\n- Percentage meeting DDD criteria\n- Average diagram age\n- Feature coverage percentage\n- Time from code change to diagram update\n- Number of broken links\n- Number of naming violations\n\nExample metrics dashboard:\n\n```markdown\n# Diagram Health Metrics\n\n**Period:** Q1 2025\n\n| Metric | Value | Trend |\n|--------|-------|-------|\n| Total Diagrams | 42 | +8 ↗️ |\n| DDD Compliant | 85% | +5% ↗️ |\n| Avg Age (days) | 30 | -10 ↗️ |\n| Feature Coverage | 78% | +12% ↗️ |\n| Outdated | 3 | -2 ↗️ |\n| Broken Links | 0 | -1 ↗️ |\n\n**Overall Health:** 🟢 GOOD\n```\n\n## Next Steps After Audit\n\n1. **Create action items** from findings\n2. **Prioritize** high-impact fixes\n3. **Assign ownership** for updates\n4. **Set deadlines** for critical fixes\n5. **Track progress** on improvements\n6. **Schedule next audit** to verify fixes\n7. **Update processes** to prevent issues\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":13680,"content_sha256":"803ec2a504666a1590b4a05bfb338ceb61e147de413972beb7087d34ca7b174a"},{"filename":"references/CREATE.md","content":"# Creating Diagrams\n\nComprehensive guide for creating new diagrams following DDD principles.\n\n## Before You Start\n\n**REQUIRED**: Read `DDD_PRINCIPLES.md` before creating any diagram. Understanding DDD methodology is essential.\n\n## Creation Process\n\n### 1. Understand the User Need\n\nBefore writing any Mermaid code, answer these questions:\n- What user problem does this solve?\n- What value does it deliver to users?\n- What user actions trigger this flow?\n- What user outcomes result from this flow?\n\n### 2. Choose the Right Diagram Type\n\n**Feature Diagrams** (`feature-*.md`)\n- Use for: Specific features or user workflows\n- Shows: How a feature delivers user value\n- Format: Flowchart with Front-Stage/Back-Stage subgraphs\n\n**Sequence Diagrams** (`sequence-*.md`)\n- Use for: Time-based user journeys\n- Shows: Step-by-step interaction over time\n- Format: Sequence diagram with user as primary actor\n\n**Architecture Diagrams** (`arch-*.md`)\n- Use for: System-level organization\n- Shows: Major components and their relationships\n- Format: High-level flowchart with impact annotations\n\n**Flow Diagrams** (`flow-*.md`)\n- Use for: Process flows and decision trees\n- Shows: Branching logic and outcomes\n- Format: Flowchart with decision nodes\n\n**Test Coverage Diagrams** (`test-*.md`)\n- Use for: Documenting test strategy\n- Shows: What user scenarios are protected by tests\n- Format: Flowchart connecting tests to user value\n\n**Refactoring Diagrams** (in `refactoring/`)\n- Use for: Before/After comparisons\n- Shows: Improvements to user experience\n- Format: Side-by-side diagrams with changes in #90EE90\n\n### 3. Determine the Directory\n\n```\nai/diagrams/\n├── features/ # Feature-specific user flows\n├── architecture/ # System-level diagrams\n├── journeys/ # User journey sequences\n├── tests/ # Test coverage and strategy\n└── refactoring/ # Before/After improvements\n```\n\n### 4. Create the File Structure\n\nUse this template for all diagrams:\n\n```markdown\n# [Clear, User-Focused Title]\n\n**Type:** [Feature Diagram | Sequence Diagram | Architecture Diagram | Flow Diagram | Test Coverage]\n**Last Updated:** [YYYY-MM-DD]\n**Related Files:**\n- `path/to/implementation.ts`\n- `path/to/component.tsx`\n- `path/to/test.spec.ts`\n\n## Purpose\n\n[1-2 sentences describing what user value this diagram illustrates. Focus on user benefit, not technical implementation.]\n\n## Diagram\n\n\\`\\`\\`mermaid\n[Mermaid code here - see patterns below]\n\\`\\`\\`\n\n## Key Insights\n\n- **User Impact 1:** [How this affects user experience]\n- **User Impact 2:** [What value this delivers]\n- **Technical Enabler:** [What makes the above possible]\n\n## Change History\n\n- **YYYY-MM-DD:** Initial creation\n```\n\n### 5. Write the Mermaid Code\n\nFollow these patterns based on diagram type:\n\n## Diagram Patterns\n\n### Feature Diagram Pattern\n\n```mermaid\ngraph TD\n subgraph \"Front-Stage (User Experience)\"\n User[User Action] --> UI[UI Response ⚡ Impact]\n UI --> Feedback[User Feedback ✅ Impact]\n end\n\n subgraph \"Back-Stage (Implementation)\"\n UI --> Service[Service Layer 🛡️ Impact]\n Service --> DB[(Database 💾 Impact)]\n Service --> Cache[Cache Layer ⚡ Impact]\n end\n\n DB --> Success[Success State]\n Service -->|Error| ErrorHandler[Error Handler 🔄 Impact]\n ErrorHandler --> Retry[User Can Retry]\n\n Cache --> UI\n Success --> Feedback\n```\n\n**Key elements:**\n- User is entry point\n- Front-Stage/Back-Stage separation\n- Impact annotations on every Back-Stage component\n- Error path with recovery\n- User outcome is clear\n\n### Sequence Diagram Pattern\n\n```mermaid\nsequenceDiagram\n actor User\n participant UI as UI Component (Front-Stage)\n participant API as API Service (Back-Stage)\n participant DB as Database\n\n User->>UI: User Action\n Note over UI: UI updates ⚡ Instant feedback\n\n UI->>API: API Request\n Note over API: Validates input ✅ Prevents errors\n\n API->>DB: Database Query\n Note over DB: Persists data 💾 Guarantees save\n\n DB-->>API: Response\n API-->>UI: Data\n UI-->>User: Success Message ⚡ Confirmation\n\n alt Error Path\n API-->>UI: Error Response\n Note over UI: Shows error 🔄 User can fix\n UI-->>User: Error Message with Action\n end\n```\n\n**Key elements:**\n- User as actor\n- Notes with impact annotations\n- Request/response pairs\n- Alt block for errors\n- Clear resolution\n\n### Architecture Diagram Pattern\n\n```mermaid\ngraph TB\n subgraph \"User Layer (Front-Stage)\"\n Browser[Web Browser]\n Mobile[Mobile App]\n end\n\n subgraph \"Application Layer (Back-Stage)\"\n API[API Gateway 🛡️ Secures requests]\n Auth[Auth Service ✅ Validates users]\n Features[Feature Services ⚡ Core functionality]\n end\n\n subgraph \"Data Layer\"\n Primary[(Primary DB 💾 Source of truth)]\n Cache[(Redis Cache ⚡ Fast reads)]\n Queue[Job Queue ⏱️ Async processing]\n end\n\n Browser --> API\n Mobile --> API\n API --> Auth\n API --> Features\n Features --> Primary\n Features --> Cache\n Features --> Queue\n\n Queue --> Primary\n Cache --> Features\n```\n\n**Key elements:**\n- Layered structure\n- User touchpoints clear\n- Impact annotations explain why each layer exists\n- Data flow is evident\n\n### Flow Diagram Pattern\n\n```mermaid\ngraph TD\n Start[User Initiates Action] --> Validate{Input Valid?}\n\n Validate -->|Yes| Process[Process Request ⚡ \u003c100ms]\n Validate -->|No| Error1[Show Validation Errors ✅]\n\n Process --> Check{Auth OK?}\n Check -->|Yes| Execute[Execute Action 💾 Saves data]\n Check -->|No| Error2[Show Auth Error 🛡️]\n\n Execute --> Success{Successful?}\n Success -->|Yes| Confirm[Show Success ✅]\n Success -->|No| Retry[Show Retry Option 🔄]\n\n Error1 --> End1[User Can Correct]\n Error2 --> End2[User Can Login]\n Retry --> End3[User Can Retry]\n Confirm --> End4[User Sees Confirmation]\n```\n\n**Key elements:**\n- Decision diamonds for branching\n- Multiple end states\n- Error paths with recovery\n- Impact annotations on operations\n\n### Test Coverage Pattern\n\n```mermaid\ngraph TD\n subgraph \"User Scenarios (What We Protect)\"\n S1[User Can Login Successfully]\n S2[User Cannot Login with Bad Credentials]\n S3[User Can Recover Password]\n end\n\n subgraph \"Test Types (How We Protect)\"\n Unit[Unit Tests ⚡ Fast feedback]\n Int[Integration Tests 💾 DB interactions]\n E2E[E2E Tests ✅ Full user flow]\n end\n\n S1 --> E2E\n S1 --> Int\n S1 --> Unit\n\n S2 --> E2E\n S2 --> Unit\n\n S3 --> E2E\n S3 --> Int\n\n Unit --> Coverage[85% Coverage 🎯]\n Int --> Coverage\n E2E --> Coverage\n\n Coverage --> UserValue[Protected User Experience 🛡️]\n```\n\n**Key elements:**\n- User scenarios as primary focus\n- Tests connected to scenarios\n- Coverage metrics\n- Clear value proposition\n\n### Refactoring (Before/After) Pattern\n\n**Before:**\n```mermaid\ngraph TD\n User[User Action] --> API[API Call]\n API --> Process[Process Data]\n Process --> DB[(Database)]\n DB --> Response[Response to User]\n\n Note1[⏱️ Takes 2-3 seconds]\n```\n\n**After:**\n```mermaid\ngraph TD\n User[User Action] --> API[API Call]\n API --> Cache{Cache Check}\n Cache -->|Hit| Fast[Cached Response ⚡ \u003c50ms]\n Cache -->|Miss| Process[Process Data]\n Process --> DB[(Database)]\n DB --> Store[Store in Cache 💾]\n Store --> Response[Response to User]\n\n Fast --> User\n Response --> User\n\n style Cache fill:#90EE90\n style Fast fill:#90EE90\n style Store fill:#90EE90\n\n Note1[⚡ Now \u003c100ms for cached requests]\n```\n\n**Key elements:**\n- Before shows current state\n- After highlights improvements in #90EE90\n- Impact annotations show user benefit\n- Performance improvements quantified\n\n## Naming Files\n\nFollow this pattern: `{type}-{descriptive-name}.md`\n\n### Good Names\n- `feature-checkout-payment-flow.md`\n- `sequence-user-authentication-journey.md`\n- `arch-microservices-overview.md`\n- `flow-error-recovery-process.md`\n- `test-payment-security-coverage.md`\n\n### Bad Names\n- `diagram1.md` (not descriptive)\n- `payment.md` (missing type)\n- `UserAuthenticationJourneySequenceDiagram.md` (wrong case)\n- `feature_checkout.md` (underscore instead of hyphen)\n\n## Impact Annotation Guide\n\n### Choosing the Right Symbol\n\n**⚡ Speed/Performance** - Use when:\n- Reducing latency\n- Improving response time\n- Optimizing load speed\n- Caching for faster access\n\nExamples:\n- `API Call ⚡ Responds in \u003c100ms`\n- `Image CDN ⚡ Loads 3x faster`\n- `Cached Results ⚡ Instant search`\n\n**💾 Storage/Persistence** - Use when:\n- Saving user data\n- Guaranteeing data persistence\n- Database operations\n- State management\n\nExamples:\n- `Save to Database 💾 Preserves user work`\n- `Session Storage 💾 Maintains login`\n- `Auto-save 💾 Never lose progress`\n\n**🛡️ Security/Safety** - Use when:\n- Authentication/authorization\n- Data validation\n- Encryption\n- Preventing vulnerabilities\n\nExamples:\n- `Auth Check 🛡️ Protects user data`\n- `Input Validation 🛡️ Prevents XSS`\n- `HTTPS Only 🛡️ Encrypted connection`\n\n**✅ Validation/Correctness** - Use when:\n- Input validation\n- Data verification\n- Ensuring accuracy\n- Preventing invalid states\n\nExamples:\n- `Validate Form ✅ Prevents errors`\n- `Check Inventory ✅ Accurate stock`\n- `Verify Email ✅ Valid address`\n\n**⏱️ Responsiveness/UX** - Use when:\n- Keeping UI responsive\n- Async operations\n- Non-blocking operations\n- Smooth interactions\n\nExamples:\n- `Async Upload ⏱️ UI stays responsive`\n- `Background Sync ⏱️ No blocking`\n- `Debounce Input ⏱️ Smooth typing`\n\n**🔄 Reliability/Recovery** - Use when:\n- Error recovery\n- Retry logic\n- Fallback behavior\n- Graceful degradation\n\nExamples:\n- `Retry Logic 🔄 Handles failures`\n- `Fallback Content 🔄 Always shows something`\n- `Error Boundary 🔄 Prevents crashes`\n\n**📊 Data Accuracy** - Use when:\n- Ensuring data quality\n- Maintaining consistency\n- Preventing data corruption\n- Accurate reporting\n\nExamples:\n- `Transaction 📊 Guarantees consistency`\n- `Validation 📊 Clean data`\n- `Reconciliation 📊 Accurate totals`\n\n**🎯 Feature Enablement** - Use when:\n- Enabling functionality\n- Making features possible\n- Core capabilities\n\nExamples:\n- `WebSockets 🎯 Enables real-time chat`\n- `Search Index 🎯 Powers instant search`\n- `Payment Gateway 🎯 Accepts payments`\n\n## Validation Checklist\n\nBefore saving, verify:\n\n### Structure\n- [ ] File is in correct directory (features/, architecture/, etc.)\n- [ ] File name follows `{type}-{name}.md` pattern\n- [ ] All template sections are present\n- [ ] Related files are documented\n\n### DDD Compliance\n- [ ] Both Front-Stage and Back-Stage are shown\n- [ ] User is the entry point\n- [ ] Impact annotations on all Back-Stage components\n- [ ] Error paths are included\n- [ ] Recovery options are shown\n\n### Content Quality\n- [ ] Purpose explains user value (not technical details)\n- [ ] Key insights focus on user impact\n- [ ] Mermaid syntax is valid\n- [ ] No custom colors (except #90EE90 for Before/After)\n- [ ] Last updated date is current\n\n### User-Centricity\n- [ ] Starts with user action\n- [ ] Ends with user outcome\n- [ ] Every technical component connects to user value\n- [ ] Error scenarios include user perspective\n\n## Update the Index\n\nAfter creating a diagram, add it to `ai/diagrams/README.md`:\n\n```markdown\n## [Category]\n\n- [Diagram Title](category/filename.md) - Brief description focusing on user value\n```\n\n## Common Mistakes to Avoid\n\n### ❌ Missing User Context\nDon't create purely technical diagrams. Every diagram must show user value.\n\n### ❌ No Impact Annotations\nDon't assume user value is obvious. Make it explicit with annotations.\n\n### ❌ Only Happy Path\nDon't ignore errors. Show what happens when things go wrong.\n\n### ❌ Wrong Directory\nDon't put all diagrams in root. Use subdirectories for organization.\n\n### ❌ Poor File Names\nDon't use generic names like \"diagram1.md\". Be descriptive.\n\n### ❌ Outdated Metadata\nDon't forget to fill in \"Related Files\" and \"Last Updated\" fields.\n\n### ❌ Technical Jargon in Purpose\nDon't write: \"REST API with JWT authentication\"\nDo write: \"Secure login that protects user accounts\"\n\n## Examples\n\n### Example 1: E-commerce Checkout Feature\n\n**File**: `features/feature-checkout-payment-flow.md`\n\n```markdown\n# E-commerce Checkout Payment Flow\n\n**Type:** Feature Diagram\n**Last Updated:** 2025-01-15\n**Related Files:**\n- `src/features/checkout/CheckoutPage.tsx`\n- `src/services/payment/paymentService.ts`\n- `src/services/order/orderService.ts`\n\n## Purpose\n\nEnables users to securely complete purchases with real-time feedback and error recovery options, ensuring they never lose their cart data.\n\n## Diagram\n\n\\`\\`\\`mermaid\ngraph TD\n subgraph \"Front-Stage (User Experience)\"\n User[User Clicks 'Pay Now'] --> Loading[Loading Spinner ⏱️ Shows progress]\n Loading --> Success[Order Confirmation ✅]\n end\n\n subgraph \"Back-Stage (Implementation)\"\n Loading --> Validate[Validate Cart ✅ Prevents invalid orders]\n Validate --> Payment[Payment Gateway 🛡️ Secure transaction]\n Payment --> Order[Create Order 💾 Guarantees delivery]\n Order --> Email[Send Receipt ⚡ Immediate confirmation]\n end\n\n Payment -->|Success| Order\n Payment -->|Failed| ErrorHandler[Payment Error Handler 🔄]\n ErrorHandler --> RetryUI[Show Retry Options]\n RetryUI --> User\n\n Order --> Success\n Email --> Success\n\\`\\`\\`\n\n## Key Insights\n\n- **Secure Payment**: PCI-compliant payment gateway protects user financial data\n- **Never Lose Orders**: Order creation guaranteed even if email fails\n- **Error Recovery**: Clear retry options if payment fails, cart is preserved\n- **Instant Feedback**: Loading spinner and immediate receipt reduce anxiety\n\n## Change History\n\n- **2025-01-15:** Initial creation\n```\n\n### Example 2: Real-time Notification System\n\n**File**: `features/feature-notification-system.md`\n\n```markdown\n# Real-time Notification System\n\n**Type:** Feature Diagram\n**Last Updated:** 2025-01-15\n**Related Files:**\n- `src/components/NotificationBell.tsx`\n- `src/services/websocket/notificationService.ts`\n- `src/hooks/useNotifications.ts`\n\n## Purpose\n\nKeeps users instantly informed of important events without requiring page refreshes, improving engagement and ensuring they never miss critical updates.\n\n## Diagram\n\n\\`\\`\\`mermaid\nsequenceDiagram\n actor User\n participant UI as Notification Bell\n participant WS as WebSocket Service\n participant Server as Notification Server\n participant DB as Database\n\n User->>UI: Opens Application\n Note over UI: Shows unread count ⚡ Instant visibility\n\n UI->>WS: Connect WebSocket\n Note over WS: Establishes connection 🎯 Enables real-time\n\n WS->>Server: Subscribe to Notifications\n\n Server->>DB: Fetch Unread Count\n DB-->>Server: Count\n Server-->>WS: Initial State\n WS-->>UI: Update Badge ⚡\n UI-->>User: Shows Unread Count\n\n loop Real-time Updates\n Server->>WS: New Notification Event\n Note over Server: Pushed instantly ⚡ \u003c100ms delivery\n WS->>UI: Update Notification List\n UI->>UI: Show Toast 📣 Alerts user\n UI-->>User: New Notification Visible\n end\n\n alt Connection Drops\n WS-->>UI: Connection Lost\n Note over UI: Shows offline indicator 🔄\n WS->>WS: Auto-reconnect ⏱️\n WS->>Server: Reconnect & Sync\n Server->>DB: Get Missed Notifications\n DB-->>Server: Missed Events\n Server-->>WS: Catch-up Data 💾\n WS-->>UI: Restore State ✅\n end\n\\`\\`\\`\n\n## Key Insights\n\n- **Instant Updates**: WebSocket enables \u003c100ms notification delivery\n- **Never Miss Anything**: Auto-reconnect and sync ensure reliability\n- **Visual Feedback**: Badge count and toasts keep users informed\n- **Offline Resilience**: Graceful handling when connection drops\n\n## Change History\n\n- **2025-01-15:** Initial creation\n```\n\n## Next Steps\n\nAfter creating a diagram:\n1. Validate against DDD checklist\n2. Update README.md index\n3. Commit with descriptive message\n4. Reference in relevant documentation\n5. Use in code reviews to explain changes\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":16272,"content_sha256":"5f130db2574dbabb9a6ccdeef8116afab959efb6e20a3a38e74ec34ea751fa9d"},{"filename":"references/DDD_PRINCIPLES.md","content":"# Diagram Driven Development (DDD) Principles\n\nCore methodology for creating diagrams that connect user value to technical implementation.\n\n## Philosophy\n\n**Traditional diagrams show WHAT the code does. DDD diagrams show WHY it matters to users.**\n\nEvery diagram must answer:\n1. **What user need does this address?**\n2. **How does the technical implementation deliver that value?**\n3. **What happens when things go wrong?**\n4. **Where can we improve the user experience?**\n\n## The Two Stages\n\n### Front-Stage (User Experience)\nWhat users see, feel, and experience:\n- User actions and decisions\n- UI states and feedback\n- Wait times and delays\n- Error messages and recovery options\n- Success confirmations\n\n### Back-Stage (Technical Implementation)\nHow we deliver the experience:\n- Services and APIs\n- Data processing\n- Caching and optimization\n- Error handling\n- Integration points\n\n**CRITICAL**: Every diagram MUST show BOTH stages and how they connect.\n\n## Impact Annotations\n\nEvery technical component must have an annotation explaining its user impact.\n\n### Good Impact Annotations\n```\nAPI Call [⚡ Loads in \u003c100ms for instant search]\nCaching Layer [💾 Reduces load time by 80%]\nError Handler [🛡️ Prevents data loss during failures]\nValidation [✅ Prevents user frustration from invalid data]\nAsync Processing [⏱️ Keeps UI responsive during heavy operations]\n```\n\n### Bad Annotations (Too Technical)\n```\nAPI Call [REST endpoint using JWT]\nCaching Layer [Redis with 1hr TTL]\nError Handler [Try/catch block with logging]\nValidation [Zod schema validation]\n```\n\n### Annotation Symbols\n- ⚡ Speed/Performance impact\n- 💾 Storage/Caching benefit\n- 🛡️ Security/Safety benefit\n- ✅ Validation/Correctness\n- ⏱️ Responsiveness/UX smoothness\n- 🔄 Reliability/Recovery\n- 📊 Data accuracy/integrity\n- 🎯 Feature enablement\n\n## Error Path Requirements\n\nEvery diagram must show:\n1. **Happy path** - When everything works\n2. **Error paths** - What happens when things fail\n3. **Recovery options** - How users can recover\n4. **Fallback behavior** - Graceful degradation\n\n### Example: Login Flow\n\n**Good (shows error paths):**\n```mermaid\ngraph TD\n User[User Enters Credentials] --> Validate[Validate Input ✅ Prevents errors]\n Validate -->|Valid| Auth[Authenticate 🛡️ Secure login]\n Validate -->|Invalid| Error1[Show Field Errors ⚡ Instant feedback]\n Auth -->|Success| Dashboard[Redirect to Dashboard]\n Auth -->|Failed| Error2[Show Login Error 🔄 Allow retry]\n Error2 --> Retry[User Can Retry or Reset Password]\n```\n\n**Bad (missing error paths):**\n```mermaid\ngraph TD\n User[User Enters Credentials] --> Auth[Authenticate]\n Auth --> Dashboard[Redirect to Dashboard]\n```\n\n## Diagram Types and Standards\n\n### 1. Feature Diagrams\nShow how a feature delivers user value.\n\n**Required elements:**\n- User entry point\n- User journey through feature\n- Technical components with impact annotations\n- Success and error outcomes\n- Performance/UX improvements\n\n**Template:**\n```mermaid\ngraph TD\n subgraph \"Front-Stage (User Experience)\"\n User[User Action] --> UI[UI Feedback]\n end\n\n subgraph \"Back-Stage (Implementation)\"\n UI --> Service[Service ⚡ Impact annotation]\n Service --> DB[Database 💾 Impact annotation]\n end\n\n DB --> Success[Success State ✅]\n Service -->|Error| Fallback[Error Recovery 🔄]\n```\n\n### 2. Sequence Diagrams\nShow user journeys over time.\n\n**Required elements:**\n- User as primary actor\n- Time-based flow\n- Request/response pairs\n- Error scenarios\n- Impact annotations on each interaction\n\n**Template:**\n```mermaid\nsequenceDiagram\n actor User\n participant UI as UI (Front-Stage)\n participant API as API (Back-Stage)\n participant DB as Database\n\n User->>UI: Action\n Note over UI: Impact annotation\n UI->>API: Request\n Note over API: Impact annotation\n API->>DB: Query\n DB-->>API: Response\n API-->>UI: Data\n UI-->>User: Updated View ⚡\n\n alt Error Path\n API-->>UI: Error\n UI-->>User: Error Message 🛡️\n end\n```\n\n### 3. Architecture Diagrams\nShow system-level organization.\n\n**Required elements:**\n- Major system components\n- Data flow between systems\n- User touchpoints\n- Performance/scalability notes\n- Impact of architectural decisions\n\n### 4. Test Coverage Diagrams\nShow how tests protect user value.\n\n**Required elements:**\n- User scenarios being tested\n- Test types (unit, integration, e2e)\n- What user value each test protects\n- Coverage gaps\n\n### 5. Refactoring Diagrams (Before/After)\nShow improvements to user experience.\n\n**Required elements:**\n- Before state\n- After state\n- Changes highlighted in `#90EE90`\n- User impact of changes\n- Performance/UX improvements\n\n## Color Usage Rules\n\n### ALLOWED\n- **Default Mermaid colors only** (no custom fills except below)\n- **#90EE90 (light green)** for highlighting changes in Before/After diagrams\n\n### PROHIBITED\n- Custom fill colors for \"pretty\" diagrams\n- Color coding by type (all blues, all reds, etc.)\n- Rainbow diagrams\n- Theme-based coloring\n\n**Reasoning**: Colors should convey meaning (changes), not decoration. Consistent default colors make diagrams professional and accessible.\n\n## Front-Stage/Back-Stage Separation\n\n### Use Subgraphs\n```mermaid\ngraph TD\n subgraph \"Front-Stage (User Experience)\"\n User[User Action]\n UI[UI Feedback ⚡ Instant updates]\n Success[Success Message]\n end\n\n subgraph \"Back-Stage (Implementation)\"\n API[API Service 🛡️ Validates data]\n DB[Database 💾 Persists changes]\n Cache[Cache Layer ⚡ Speeds up reads]\n end\n\n User --> UI\n UI --> API\n API --> DB\n API --> Cache\n Cache --> UI\n UI --> Success\n```\n\n### Clear Boundaries\n- Front-Stage: What users interact with\n- Back-Stage: What makes it work\n- Connections: How they communicate\n- Annotations: Why it matters\n\n## Quality Validation Checklist\n\nBefore saving any diagram, verify:\n\n### Structure\n- [ ] Both Front-Stage and Back-Stage are present\n- [ ] Subgraphs separate the two stages clearly\n- [ ] User is the primary actor/entry point\n- [ ] Error paths are shown\n- [ ] Recovery options are documented\n\n### Annotations\n- [ ] Every Back-Stage component has impact annotation\n- [ ] Annotations focus on user benefit, not technical detail\n- [ ] Appropriate symbols are used (⚡💾🛡️✅⏱️🔄📊🎯)\n- [ ] Performance impacts are quantified where possible\n\n### Content\n- [ ] Related files are documented\n- [ ] Purpose explains user value\n- [ ] Key insights list user impacts\n- [ ] Change history tracks updates\n- [ ] Last updated date is current\n\n### Technical\n- [ ] Mermaid syntax is valid\n- [ ] No custom colors (except #90EE90 for changes)\n- [ ] Diagram renders correctly\n- [ ] Node labels are clear and concise\n\n### User-Centricity\n- [ ] Diagram starts and ends with user\n- [ ] User value is explicit, not implied\n- [ ] Error scenarios include user recovery\n- [ ] Performance impacts relate to user experience\n\n## Common Anti-Patterns\n\n### ❌ Purely Technical Diagrams\n```mermaid\ngraph TD\n Controller --> Service\n Service --> Repository\n Repository --> Database\n```\n**Problem**: No user context, no impact annotations, no value explanation.\n\n### ✅ DDD-Compliant Diagram\n```mermaid\ngraph TD\n subgraph \"Front-Stage\"\n User[User Saves Settings] --> UI[Settings Page ⚡ Instant save feedback]\n end\n\n subgraph \"Back-Stage\"\n UI --> Controller[Settings Controller 🛡️ Validates input]\n Controller --> Service[Settings Service 💾 Persists to DB]\n Service --> DB[(Database)]\n end\n\n DB --> Success[Settings Saved ✅]\n Controller -->|Invalid| Error[Error Message 🔄 User can correct]\n```\n\n### ❌ Missing Error Paths\nShows only happy path, ignoring what happens when things fail.\n\n### ❌ No Impact Annotations\nTechnical components without explanation of user benefit.\n\n### ❌ Hidden User Context\nUser is implied but not shown in diagram.\n\n### ❌ Custom Colors Everywhere\nRainbow diagrams that distract from content.\n\n## Real-World Examples\n\n### E-commerce Checkout (Good)\n```mermaid\nsequenceDiagram\n actor User\n participant Cart as Shopping Cart\n participant Payment as Payment Service\n participant Order as Order System\n participant Email as Email Notification\n\n User->>Cart: Click \"Checkout\"\n Note over Cart: Validates cart ✅ Prevents empty orders\n\n Cart->>Payment: Process Payment\n Note over Payment: Secure transaction 🛡️ PCI compliant\n\n alt Payment Success\n Payment-->>Order: Confirm Payment\n Note over Order: Creates order 💾 Guarantees delivery\n Order-->>Email: Send Confirmation\n Note over Email: Immediate receipt ⚡ Peace of mind\n Email-->>User: Order Confirmed ✅\n else Payment Failed\n Payment-->>Cart: Payment Error\n Cart-->>User: Show Error & Retry Option 🔄\n end\n```\n\n**Why this is good:**\n- Shows user as primary actor\n- Front-Stage/Back-Stage implicit but clear\n- Impact annotations on every step\n- Error path with recovery\n- User outcome is clear\n\n### Search Feature (Good)\n```mermaid\ngraph TD\n subgraph \"Front-Stage (User Experience)\"\n User[User Types Query] --> UI[Search Input ⚡ Live suggestions]\n UI --> Results[Results Page]\n Results --> Click[User Clicks Result]\n end\n\n subgraph \"Back-Stage (Implementation)\"\n UI --> Debounce[Debounce ⏱️ Reduces API calls]\n Debounce --> Cache[Check Cache 💾 Instant for common searches]\n Cache -->|Cache Hit| UI\n Cache -->|Cache Miss| API[Search API 📊 Full-text search]\n API --> Rank[Ranking Algorithm 🎯 Most relevant first]\n Rank --> Cache\n Rank --> Results\n end\n\n API -->|Error| Fallback[Show Cached Results 🔄 Never blank page]\n```\n\n**Why this is good:**\n- Clear Front-Stage/Back-Stage separation\n- Every technical component has impact annotation\n- Error path shows graceful fallback\n- User starts and ends the flow\n- Performance optimizations are explained\n\n## Implementation Guidelines\n\n### When Creating Diagrams\n\n1. **Start with user need**\n - What problem does this solve?\n - What value does it deliver?\n\n2. **Map the user journey**\n - Entry point\n - Actions and decisions\n - Success outcome\n - Error scenarios\n\n3. **Add technical components**\n - How do we deliver the experience?\n - What makes it fast/secure/reliable?\n\n4. **Add impact annotations**\n - Why does each component matter?\n - What user benefit does it provide?\n\n5. **Show error paths**\n - What can go wrong?\n - How do users recover?\n\n6. **Validate quality**\n - Run through DDD checklist\n - Ensure Front-Stage/Back-Stage balance\n - Verify all annotations explain user value\n\n### When Updating Diagrams\n\n1. **Identify what changed in code**\n2. **Determine user impact of changes**\n3. **Update diagram to reflect new flow**\n4. **Update impact annotations**\n5. **Add change history entry**\n6. **Update \"Last Updated\" date**\n7. **Re-validate against DDD checklist**\n\n### When Auditing Diagrams\n\n1. **Check structural quality**\n - Front-Stage/Back-Stage present?\n - Error paths shown?\n - User-centric?\n\n2. **Check annotation quality**\n - Do they explain user value?\n - Are they specific enough?\n - Do they use appropriate symbols?\n\n3. **Check synchronization**\n - Does diagram match current code?\n - Is \"Last Updated\" recent?\n - Are related files still correct?\n\n4. **Check completeness**\n - Are there features without diagrams?\n - Are there outdated diagrams?\n - Are there purely technical diagrams that need upgrading?\n\n## DDD in Practice\n\n### Before DDD\nDeveloper creates diagram showing technical architecture with boxes and arrows. Diagram shows service layers, databases, APIs, but no mention of what user problem it solves.\n\n### After DDD\nDeveloper creates diagram showing:\n- User trying to complete a task\n- How the UI responds to their actions\n- What technical systems enable that response\n- Why each system matters to the user experience\n- What happens when things go wrong\n- How users can recover from errors\n\n**Result**: Non-technical stakeholders can understand the diagram. Developers understand the \"why\" behind technical decisions. Everyone sees how code changes impact users.\n\n## Conclusion\n\nDDD diagrams are not just documentation—they are a tool for thinking about systems from a user-first perspective. Every technical decision should trace back to user value, and diagrams make that connection explicit and visible.\n\n**Remember**: If you can't explain the user value of a technical component, reconsider whether it belongs in the system.\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":12699,"content_sha256":"3e32460c98d02cf97514cba33ef5f6b9da05d9e1fca19501071b11d1ff0efa59"},{"filename":"references/MERMAID_GUIDE.md","content":"# Mermaid Syntax Guide for DDD Diagrams\n\nQuick reference for creating effective diagrams with Mermaid. Focus on patterns used in DDD diagrams.\n\n## Essential Mermaid Patterns\n\n### Flowchart (Most Common for DDD)\n\n```mermaid\ngraph TD\n A[Node] --> B[Another Node]\n B --> C{Decision}\n C -->|Yes| D[Outcome 1]\n C -->|No| E[Outcome 2]\n```\n\n**Direction:**\n- `graph TD` - Top to Down\n- `graph LR` - Left to Right\n- `graph BT` - Bottom to Top\n- `graph RL` - Right to Left\n\n**Node Shapes:**\n```mermaid\ngraph LR\n A[Rectangle - Process/Action]\n B(Rounded - Start/End/State)\n C{Diamond - Decision}\n D[(Database)]\n E[[Subroutine]]\n F([Stadium - Alternative Process])\n```\n\n### Sequence Diagrams (For Journeys)\n\n```mermaid\nsequenceDiagram\n actor User\n participant UI\n participant API\n participant DB\n\n User->>UI: Action\n Note over UI: Processing\n UI->>API: Request\n API->>DB: Query\n DB-->>API: Response\n API-->>UI: Data\n UI-->>User: Result\n\n alt Error Path\n API-->>UI: Error\n UI-->>User: Error Message\n end\n```\n\n**Key Elements:**\n- `actor` - User (human)\n- `participant` - Systems/components\n- `->` Solid line (sync)\n- `-->` Dotted line (async/return)\n- `->>` Solid arrow (message)\n- `-->>` Dotted arrow (return)\n- `Note over` - Annotations\n- `alt`/`else`/`end` - Alternatives\n\n## DDD-Specific Patterns\n\n### Front-Stage/Back-Stage with Subgraphs\n\n```mermaid\ngraph TD\n subgraph \"Front-Stage (User Experience)\"\n direction TB\n User[User Action]\n UI[UI Feedback ⚡ Impact]\n Success[Success State ✅]\n end\n\n subgraph \"Back-Stage (Implementation)\"\n direction TB\n Service[Service Layer 🛡️ Impact]\n DB[(Database 💾 Impact)]\n Cache[Cache ⚡ Impact]\n end\n\n User --> UI\n UI --> Service\n Service --> DB\n Service --> Cache\n Cache --> UI\n UI --> Success\n```\n\n**Subgraph Tips:**\n- Always label as \"Front-Stage\" and \"Back-Stage\"\n- Use `direction TB` inside subgraphs for vertical layout\n- Place user-facing components in Front-Stage\n- Place technical components in Back-Stage\n\n### Impact Annotations in Nodes\n\n```mermaid\ngraph TD\n API[API Call ⚡ Responds in \u003c100ms]\n DB[(Database 💾 Persists user data)]\n Cache[Cache Layer ⚡ 3x faster]\n Auth[Auth Service 🛡️ Secures requests]\n Validate[Input Validation ✅ Prevents errors]\n```\n\n**Annotation Format:**\n`Component Name [Symbol] Impact description`\n\n### Error Paths\n\n```mermaid\ngraph TD\n Start[User Action] --> Validate{Valid Input?}\n Validate -->|Yes| Process[Process Request]\n Validate -->|No| Error1[Show Error 🔄 User can correct]\n\n Process --> Check{Success?}\n Check -->|Yes| Success[Complete]\n Check -->|No| Error2[Error Handler 🔄]\n Error2 --> Retry[Retry Option]\n```\n\n**Error Path Tips:**\n- Always include error branches\n- Show recovery options\n- Use 🔄 symbol for recovery/retry\n- Make error paths obvious (not hidden)\n\n## Styling\n\n### Highlighting Changes (Before/After Only)\n\n```mermaid\ngraph TD\n A[Old Component]\n B[New Component]\n C[Modified Component]\n\n style B fill:#90EE90\n style C fill:#90EE90\n```\n\n**CRITICAL**: Only use `#90EE90` (light green) for Before/After diagrams showing changes. No other custom colors.\n\n### Node Styling (Avoid)\n\n```mermaid\n# ❌ DON'T DO THIS (custom colors)\ngraph TD\n A[Component]\n style A fill:#ff0000,stroke:#333,stroke-width:4px\n```\n\nUse default Mermaid styles unless highlighting changes.\n\n## Advanced Patterns\n\n### Multiple End States\n\n```mermaid\ngraph TD\n Start[Begin] --> Process{Process}\n Process -->|Path 1| End1[Success ✅]\n Process -->|Path 2| End2[Partial Success ⚠️]\n Process -->|Path 3| End3[Failure - Retry Available 🔄]\n Process -->|Path 4| End4[Fatal Error ❌]\n```\n\n### Parallel Processing\n\n```mermaid\ngraph TD\n Start[User Action] --> Split[Split]\n Split -->|Async 1| Task1[Task 1 ⏱️]\n Split -->|Async 2| Task2[Task 2 ⏱️]\n Split -->|Async 3| Task3[Task 3 ⏱️]\n\n Task1 --> Join[Join Results]\n Task2 --> Join\n Task3 --> Join\n\n Join --> Complete[All Complete ✅]\n```\n\n### Nested Subgraphs\n\n```mermaid\ngraph TD\n subgraph \"Application Layer\"\n direction LR\n subgraph \"Front-Stage\"\n UI[UI Components]\n end\n subgraph \"Back-Stage\"\n API[API Layer]\n Services[Business Logic]\n end\n end\n\n subgraph \"Data Layer\"\n DB[(Primary Database)]\n Cache[(Cache)]\n end\n\n UI --> API\n API --> Services\n Services --> DB\n Services --> Cache\n```\n\n## Sequence Diagram Patterns\n\n### Simple Request/Response\n\n```mermaid\nsequenceDiagram\n User->>API: Request\n Note over API: Process ⚡ \u003c100ms\n API->>DB: Query\n DB-->>API: Data\n API-->>User: Response ✅\n```\n\n### With Authentication\n\n```mermaid\nsequenceDiagram\n User->>UI: Login\n UI->>Auth: Validate Credentials 🛡️\n Auth->>DB: Check User\n DB-->>Auth: User Data\n\n alt Valid Credentials\n Auth-->>UI: Token ✅\n UI-->>User: Logged In\n else Invalid Credentials\n Auth-->>UI: Error 🔄\n UI-->>User: Show Error & Retry\n end\n```\n\n### Multiple Alternatives\n\n```mermaid\nsequenceDiagram\n User->>System: Action\n\n alt Scenario 1\n System-->>User: Outcome 1\n else Scenario 2\n System-->>User: Outcome 2\n else Scenario 3\n System-->>User: Outcome 3\n end\n```\n\n### Loops\n\n```mermaid\nsequenceDiagram\n User->>System: Start Process\n\n loop Until Complete\n System->>System: Process Batch\n System->>DB: Save Progress 💾\n Note over System: Continue next batch\n end\n\n System-->>User: All Complete ✅\n```\n\n## Common Mistakes\n\n### ❌ Too Complex\n\n```mermaid\n# Bad: Too many nodes, hard to follow\ngraph TD\n A --> B --> C --> D --> E --> F --> G --> H --> I --> J\n```\n\n**Solution**: Break into multiple diagrams or use subgraphs to organize.\n\n### ❌ No Labels on Edges\n\n```mermaid\n# Bad: Unclear what each path means\nDecision --> Option1\nDecision --> Option2\n```\n\n```mermaid\n# Good: Clear edge labels\nDecision -->|Valid| Option1\nDecision -->|Invalid| Option2\n```\n\n### ❌ Missing User Context\n\n```mermaid\n# Bad: No user in diagram\nService --> Database --> Cache\n```\n\n```mermaid\n# Good: User is visible\nUser --> Service --> Database --> Cache --> User\n```\n\n### ❌ No Impact Annotations\n\n```mermaid\n# Bad: Just technical names\nAPI --> Database --> Response\n```\n\n```mermaid\n# Good: Impact explained\nAPI --> Database[(Database 💾 Stores order)]\nDatabase --> Response[Response ⚡ \u003c100ms]\n```\n\n## Testing Your Diagram\n\n### Online Editor\nUse [Mermaid Live Editor](https://mermaid.live) to:\n- Validate syntax\n- Preview rendering\n- Test different layouts\n- Export images\n\n### Common Syntax Errors\n\n**Missing Direction:**\n```mermaid\n# ❌ Error\ngraph\n A --> B\n\n# ✅ Correct\ngraph TD\n A --> B\n```\n\n**Invalid Characters in IDs:**\n```mermaid\n# ❌ Error\ngraph TD\n node-1 --> node-2\n\n# ✅ Correct\ngraph TD\n node1[Node 1] --> node2[Node 2]\n```\n\n**Unmatched Brackets:**\n```mermaid\n# ❌ Error\ngraph TD\n A[Node --> B\n\n# ✅ Correct\ngraph TD\n A[Node] --> B\n```\n\n## Quick Reference\n\n### Node Types\n```\n[Text] Rectangle\n(Text) Rounded\n{Text} Diamond\n[(Text)] Database\n[[Text]] Subroutine\n([Text]) Stadium\n```\n\n### Arrow Types\n```\n--> Dotted line\n-> Solid line\n->> Solid with arrow\n-->> Dotted with arrow\n---|Text|--> Labeled line\n```\n\n### Directions\n```\nTD / TB Top to Down/Bottom\nLR Left to Right\nBT Bottom to Top\nRL Right to Left\n```\n\n### Common Symbols\n```\n⚡ Speed/Performance\n💾 Storage/Persistence\n🛡️ Security/Safety\n✅ Validation/Success\n⏱️ Responsiveness\n🔄 Recovery/Retry\n📊 Data Accuracy\n🎯 Feature Enable\n```\n\n## Best Practices\n\n1. **Keep it simple** - If diagram is too complex, split it\n2. **Clear labels** - Every node and edge should be clear\n3. **User-centric** - User should be visible in diagram\n4. **Impact annotations** - Explain user value, not just technical details\n5. **Error paths** - Always show what happens when things fail\n6. **Test syntax** - Use Mermaid Live Editor to validate\n7. **Consistent style** - Use default styles, avoid custom colors\n8. **Front-Stage/Back-Stage** - Always separate user experience from implementation\n9. **Direction matters** - Choose TD or LR based on what's clearer\n10. **Validate rendering** - Check that diagram actually renders correctly\n\n## Resources\n\n- [Mermaid Documentation](https://mermaid.js.org/)\n- [Mermaid Live Editor](https://mermaid.live)\n- [Mermaid Cheat Sheet](https://jojozhuang.github.io/tutorial/mermaid-cheat-sheet/)\n- [Flowchart Syntax](https://mermaid.js.org/syntax/flowchart.html)\n- [Sequence Diagram Syntax](https://mermaid.js.org/syntax/sequenceDiagram.html)\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":8963,"content_sha256":"bb223e0a036819c8ac6a1f70474b1b3ff35c03cae93bab5df398e4c0da6b1ab0"},{"filename":"references/ORGANIZE.md","content":"# Organizing Diagrams\n\nGuide for maintaining clean directory structure and consistent naming conventions.\n\n## Directory Structure\n\n```\nai/diagrams/\n├── README.md # Index of all diagrams (REQUIRED)\n├── features/ # Feature-specific user flows\n│ ├── feature-checkout-payment-flow.md\n│ ├── feature-notification-system.md\n│ └── feature-search-functionality.md\n├── architecture/ # System-level diagrams\n│ ├── arch-system-overview.md\n│ ├── arch-microservices-architecture.md\n│ └── arch-data-flow.md\n├── journeys/ # User journey sequences\n│ ├── sequence-authentication-journey.md\n│ ├── sequence-onboarding-flow.md\n│ └── sequence-purchase-completion.md\n├── tests/ # Test coverage and strategy\n│ ├── test-payment-security-coverage.md\n│ └── test-e2e-critical-paths.md\n└── refactoring/ # Before/After improvements\n ├── feature-add-caching-layer.md\n └── feature-optimize-database-queries.md\n```\n\n## Naming Conventions\n\n### Format: `{type}-{descriptive-name}.md`\n\n**Type Prefixes:**\n- `feature-` → features/\n- `sequence-` → journeys/\n- `arch-` → architecture/\n- `flow-` → features/ or journeys/ (depending on context)\n- `test-` → tests/\n\n**Descriptive Name Rules:**\n- Lowercase only\n- Use hyphens (not underscores or spaces)\n- Be specific and clear\n- 2-5 words is ideal\n- Describe the user value or flow\n\n### Good Examples\n\n```\n✅ feature-checkout-payment-flow.md\n✅ sequence-user-authentication-journey.md\n✅ arch-microservices-overview.md\n✅ test-payment-security-coverage.md\n✅ feature-real-time-notifications.md\n```\n\n### Bad Examples\n\n```\n❌ checkout.md # Missing type prefix\n❌ feature_checkout.md # Underscore instead of hyphen\n❌ FeatureCheckout.md # Wrong case\n❌ diagram1.md # Not descriptive\n❌ feature-checkout-payment-flow-diagram.md # Redundant \"diagram\"\n❌ sequence-user-auth.md # Too abbreviated\n```\n\n## Directory Selection Guide\n\n### features/\n**When to use:**\n- Specific user-facing features\n- Feature workflows\n- Component interactions within a feature\n- User actions within a bounded context\n\n**Examples:**\n- Checkout flow\n- Notification system\n- Search functionality\n- User profile editing\n\n### architecture/\n**When to use:**\n- System-level organization\n- Multiple services/components interaction\n- High-level overviews\n- Infrastructure diagrams\n- Technology stack diagrams\n\n**Examples:**\n- Microservices architecture\n- System overview\n- Data flow across services\n- Deployment architecture\n\n### journeys/\n**When to use:**\n- Time-based user journeys\n- Multi-step processes\n- Cross-feature workflows\n- User onboarding\n- Complete user stories\n\n**Examples:**\n- Authentication journey (login → 2FA → redirect)\n- Purchase journey (browse → cart → checkout → confirmation)\n- Onboarding flow (signup → verification → setup)\n\n### tests/\n**When to use:**\n- Test coverage documentation\n- Test strategy diagrams\n- Connection between tests and user value\n- Critical path testing\n- Security/compliance testing\n\n**Examples:**\n- Payment security test coverage\n- E2E critical paths\n- Integration test strategy\n\n### refactoring/\n**When to use:**\n- Before/After comparisons\n- Performance improvements\n- Architecture changes\n- Code quality improvements\n- Technical debt reduction\n\n**Examples:**\n- Adding caching layer\n- Optimizing database queries\n- Migrating to microservices\n- Improving error handling\n\n## README.md Index Structure\n\nThe index is the entry point for understanding. Keep it organized and current.\n\n### Template\n\n```markdown\n# Unified Impact Diagrams Index\n\nThis directory contains all diagrams for the project, following Diagram Driven Development (DDD) methodology.\n\n**Last Updated:** YYYY-MM-DD\n\n## Quick Links\n\n- [System Architecture](#architecture-overview)\n- [User Journeys](#user-journeys)\n- [Features](#features)\n- [Test Coverage](#test-coverage)\n\n## Architecture Overview\n\nHigh-level system design and component relationships.\n\n- [System Architecture](architecture/arch-system-overview.md) - Complete system with all major services and data flow\n- [Microservices Architecture](architecture/arch-microservices-architecture.md) - Service boundaries and communication patterns\n\n## User Journeys\n\nTime-based user experiences across features.\n\n- [User Authentication](journeys/sequence-authentication-journey.md) - Login, 2FA, and account recovery with security focus\n- [Purchase Flow](journeys/sequence-purchase-completion.md) - Complete buying journey from browse to confirmation\n- [Onboarding](journeys/sequence-onboarding-flow.md) - New user setup and first-time experience\n\n## Features\n\nIndividual features and their user value.\n\n- [Checkout & Payment](features/feature-checkout-payment-flow.md) - Secure payment processing with error recovery\n- [Real-time Notifications](features/feature-notification-system.md) - WebSocket-based instant updates\n- [Search](features/feature-search-functionality.md) - Fast search with autocomplete and caching\n\n## Test Coverage\n\nHow we protect user value through testing.\n\n- [Payment Security](tests/test-payment-security-coverage.md) - Comprehensive payment testing strategy\n- [Critical E2E Paths](tests/test-e2e-critical-paths.md) - Essential user journeys covered by E2E tests\n\n## Refactoring Plans\n\nImprovements and their expected user impact.\n\n- [Caching Layer](refactoring/feature-add-caching-layer.md) - Reduce load time from 2s to \u003c100ms\n- [Query Optimization](refactoring/feature-optimize-database-queries.md) - Improve dashboard performance by 5x\n\n## Diagram Guidelines\n\nAll diagrams follow [Diagram Driven Development (DDD)](../commands/sync-diagrams.md) principles:\n- Show both Front-Stage (user experience) and Back-Stage (implementation)\n- Include impact annotations explaining user value\n- Show error paths and recovery options\n- Connect technical decisions to user benefit\n\n## Contributing\n\nWhen creating or updating diagrams:\n1. Follow DDD principles (see guidelines above)\n2. Use appropriate directory and naming convention\n3. Update this index with new/modified diagrams\n4. Add change history entry in diagram file\n5. Update \"Last Updated\" in this README\n\n## Recent Changes\n\n- **2025-01-16:** Added caching layer refactoring diagram\n- **2025-01-15:** Updated authentication journey with 2FA\n- **2025-01-10:** Created real-time notification system diagram\n```\n\n### Index Best Practices\n\n1. **Keep it current** - Update whenever diagrams change\n2. **Provide context** - Brief descriptions with user value\n3. **Use categories** - Group related diagrams\n4. **Quick links** - Make navigation easy\n5. **Document recent changes** - Help team track updates\n\n## Reorganization Process\n\nWhen structure needs changes:\n\n### 1. Plan the Reorganization\n\n```markdown\n## Reorganization Plan\n\n**Goal:** Consolidate scattered diagrams into proper structure\n\n**Changes:**\n1. Move `diagram1.md` → `features/feature-checkout-flow.md`\n2. Rename `auth.md` → `sequence-authentication-journey.md`\n3. Create `architecture/` directory\n4. Move system diagrams to `architecture/`\n5. Update all links in README.md\n```\n\n### 2. Execute Systematically\n\n```bash\n# Create missing directories\nmkdir -p ai/diagrams/{features,architecture,journeys,tests,refactoring}\n\n# Move and rename files\nmv ai/diagrams/diagram1.md ai/diagrams/features/feature-checkout-flow.md\nmv ai/diagrams/auth.md ai/diagrams/journeys/sequence-authentication-journey.md\n\n# Update the diagram metadata (Related Files paths may change)\n# Update README.md index\n```\n\n### 3. Validate After Reorganization\n\n- [ ] All diagrams in correct directories\n- [ ] All file names follow convention\n- [ ] README.md index is updated\n- [ ] No broken links\n- [ ] Git history is preserved (use `git mv`)\n\n## Common Organization Issues\n\n### Issue 1: Diagrams in Root Directory\n\n**Problem:**\n```\nai/diagrams/\n├── checkout.md\n├── auth.md\n├── system.md\n└── README.md\n```\n\n**Solution:**\n```bash\n# Move to appropriate directories\nmkdir -p ai/diagrams/{features,architecture,journeys}\nmv ai/diagrams/checkout.md ai/diagrams/features/feature-checkout-flow.md\nmv ai/diagrams/auth.md ai/diagrams/journeys/sequence-authentication-journey.md\nmv ai/diagrams/system.md ai/diagrams/architecture/arch-system-overview.md\n```\n\n### Issue 2: Inconsistent Naming\n\n**Problem:**\n```\nfeatures/\n├── feature-checkout.md\n├── checkout-flow.md\n├── Checkout.md\n└── feature_payment.md\n```\n\n**Solution:**\n```bash\n# Standardize names\nmv feature-checkout.md feature-checkout-flow.md\nmv checkout-flow.md feature-checkout-alternate.md # or merge\nmv Checkout.md feature-checkout-main.md # or merge\nmv feature_payment.md feature-payment-processing.md\n```\n\n### Issue 3: Wrong Directory\n\n**Problem:**\n```\nfeatures/arch-system-overview.md # Architecture in features/\njourneys/feature-search.md # Feature in journeys/\n```\n\n**Solution:**\n```bash\n# Move to correct directories\nmv features/arch-system-overview.md architecture/\nmv journeys/feature-search.md features/\n```\n\n### Issue 4: Duplicate Diagrams\n\n**Problem:**\n```\nfeatures/\n├── feature-checkout-flow.md\n├── feature-checkout-payment.md\n└── feature-payment-checkout.md\n```\n\n**Solution:**\n1. Review all three diagrams\n2. Determine if they cover different aspects or duplicate\n3. If duplicate: Merge into single comprehensive diagram\n4. If different: Clarify names to show distinction\n - `feature-checkout-cart-management.md`\n - `feature-checkout-payment-processing.md`\n - `feature-checkout-order-confirmation.md`\n\n## Maintenance Commands\n\n### List All Diagrams by Type\n\n```bash\n# Feature diagrams\nfind ai/diagrams/features -name \"feature-*.md\"\n\n# Sequence diagrams\nfind ai/diagrams/journeys -name \"sequence-*.md\"\n\n# Architecture diagrams\nfind ai/diagrams/architecture -name \"arch-*.md\"\n```\n\n### Find Misplaced Diagrams\n\n```bash\n# Architecture diagrams not in architecture/\nfind ai/diagrams -name \"arch-*.md\" -not -path \"*/architecture/*\"\n\n# Feature diagrams not in features/\nfind ai/diagrams -name \"feature-*.md\" -not -path \"*/features/*\"\n\n# Sequence diagrams not in journeys/\nfind ai/diagrams -name \"sequence-*.md\" -not -path \"*/journeys/*\"\n```\n\n### Validate File Names\n\n```bash\n# Find files not following convention\nfind ai/diagrams -name \"*.md\" -not -name \"README.md\" | while read file; do\n basename \"$file\" | grep -vE '^(feature|sequence|arch|flow|test)-[a-z0-9-]+\\.md

Important: agents should read /llm.txt, /llms.txt, or /.well-known/skills.json to discover the public Skillopedia API.

&& \\\n echo \"Invalid name: $file\"\ndone\n```\n\n### Check for Broken Links in Index\n\n```bash\n# Extract links from README\ngrep -oP '\\]\\(\\K[^)]+' ai/diagrams/README.md | while read link; do\n if [ ! -f \"ai/diagrams/$link\" ]; then\n echo \"Broken link: $link\"\n fi\ndone\n```\n\n## Migration Checklist\n\nWhen reorganizing existing diagrams:\n\n- [ ] Back up current state (git commit)\n- [ ] Create reorganization plan\n- [ ] Create missing directories\n- [ ] Move files with `git mv` (preserves history)\n- [ ] Rename files following convention\n- [ ] Update README.md index\n- [ ] Update internal links in diagrams (if any)\n- [ ] Validate no broken links\n- [ ] Commit with descriptive message\n- [ ] Inform team of changes\n\n## Best Practices\n\n1. **Use `git mv`** - Preserves file history\n2. **One diagram type per directory** - Don't mix feature and architecture\n3. **Consistent prefixes** - Always use type prefix in filename\n4. **Descriptive names** - Name should indicate content\n5. **Keep README current** - Update index immediately after changes\n6. **Validate regularly** - Run organization audits monthly\n7. **Document changes** - Note reorganizations in README\n8. **Team communication** - Inform team of structure changes\n9. **No orphans** - Every diagram should be in index\n10. **Regular cleanup** - Remove obsolete diagrams\n\n## Quick Reference\n\n### Directory Decision Tree\n\n```\nIs it showing system architecture?\n├─ Yes → architecture/arch-{name}.md\n└─ No → Is it a time-based journey?\n ├─ Yes → journeys/sequence-{name}.md\n └─ No → Is it feature-specific?\n ├─ Yes → features/feature-{name}.md\n └─ No → Is it about testing?\n ├─ Yes → tests/test-{name}.md\n └─ No → Is it Before/After comparison?\n ├─ Yes → refactoring/feature-{name}.md\n └─ No → Choose closest match\n```\n\n### Naming Quick Check\n\n1. All lowercase? ✓\n2. Has type prefix? ✓\n3. Uses hyphens? ✓\n4. Descriptive (2-5 words)? ✓\n5. Ends with .md? ✓\n\n### Index Update Template\n\n```markdown\n## [Category]\n\n- [Clear Title](directory/filename.md) - Brief user-value description\n```\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":12806,"content_sha256":"1df7ec93ad85a14273744218bf32281eeacfafbb84135d0dc5757990a2a0b30b"},{"filename":"references/UPDATE.md","content":"# Updating Diagrams\n\nGuide for keeping diagrams synchronized with code changes.\n\n## When to Update\n\nUpdate diagrams when:\n- Code implementation changes\n- User flows are modified\n- New features are added to existing flows\n- Performance improvements are made\n- Error handling is added/changed\n- Dependencies change\n- Related files are renamed/moved\n\n## Update Process\n\n### 1. Identify Affected Diagrams\n\n**Using git history:**\n```bash\n# Find files changed recently\ngit log --since=\"1 week ago\" --name-only --pretty=format: | sort | uniq\n\n# Compare with diagrams to find outdated ones\nfind ai/diagrams -name \"*.md\" -exec grep -l \"path/to/changed/file\" {} \\;\n```\n\n**Using diagram metadata:**\n- Check \"Related Files\" section in diagrams\n- Compare file paths with changed files\n- Look for outdated \"Last Updated\" dates\n\n**Manual review:**\n- List all diagrams: `ls -R ai/diagrams/`\n- Review each diagram's related files\n- Identify diagrams that reference changed code\n\n### 2. Understand the Changes\n\nBefore updating diagrams:\n- Review code changes (git diff)\n- Understand user impact of changes\n- Identify new error paths or flows\n- Note performance improvements\n- Check for new dependencies\n\n### 3. Update the Diagram\n\n#### Update Mermaid Code\n\n**Adding new components:**\n```mermaid\n# Old\nUser --> Service --> DB\n\n# New (add caching layer)\nUser --> Service --> Cache\nCache -->|Hit| User\nCache -->|Miss| DB\nDB --> Cache\n```\n\n**Modifying flows:**\n```mermaid\n# Old\nService --> DB --> Response\n\n# New (add validation)\nService --> Validate[Validate ✅]\nValidate -->|Valid| DB\nValidate -->|Invalid| Error[Error Response 🔄]\nDB --> Response\n```\n\n**Adding error paths:**\n```mermaid\n# Old\nAPI --> Process --> Success\n\n# New (add error handling)\nAPI --> Process\nProcess -->|Success| Success\nProcess -->|Error| ErrorHandler[Error Handler 🔄]\nErrorHandler --> Retry[User Can Retry]\n```\n\n#### Update Impact Annotations\n\nWhen implementation changes affect user experience:\n\n**Before:**\n```\nAPI Call --> Database\n```\n\n**After (added caching):**\n```\nAPI Call --> Cache[Cache Layer ⚡ Reduces load time to \u003c50ms]\nCache -->|Miss| Database\n```\n\n#### Update Related Files\n\nKeep the \"Related Files\" section current:\n\n**Before:**\n```markdown\n**Related Files:**\n- `src/services/userService.ts`\n- `src/components/UserProfile.tsx`\n```\n\n**After (files renamed):**\n```markdown\n**Related Files:**\n- `src/services/user/userService.ts`\n- `src/features/profile/UserProfilePage.tsx`\n- `src/hooks/useUserData.ts` (new)\n```\n\n### 4. Update Metadata\n\n#### Last Updated Date\n```markdown\n**Last Updated:** 2025-01-16\n```\n\n#### Change History\n```markdown\n## Change History\n\n- **2025-01-16:** Added caching layer for improved performance (2s → 50ms)\n- **2025-01-10:** Added error recovery options for failed authentication\n- **2025-01-05:** Initial creation\n```\n\n### 5. Update Key Insights\n\nIf changes affect user value, update insights:\n\n**Before:**\n```markdown\n## Key Insights\n\n- Secure authentication protects user accounts\n- Immediate feedback on login success/failure\n```\n\n**After (added remember me):**\n```markdown\n## Key Insights\n\n- Secure authentication protects user accounts\n- Immediate feedback on login success/failure\n- **Remember me option saves time on return visits**\n- Auto-logout after 30 days balances convenience and security\n```\n\n### 6. Validate Quality\n\nRun through DDD checklist:\n- [ ] Still shows Front-Stage and Back-Stage\n- [ ] New components have impact annotations\n- [ ] Error paths are current\n- [ ] User actions reflect new flows\n- [ ] Related files are accurate\n- [ ] Last updated date is current\n- [ ] Change history explains what changed\n\n## Update Patterns\n\n### Pattern 1: Adding Performance Optimization\n\n**Scenario**: Added Redis caching to reduce database load\n\n**Before:**\n```mermaid\ngraph TD\n User[User Searches] --> API[Search API]\n API --> DB[(Database)]\n DB --> Results[Search Results]\n Results --> User\n```\n\n**After:**\n```mermaid\ngraph TD\n User[User Searches] --> API[Search API]\n API --> Cache{Cache Check}\n Cache -->|Hit| Fast[Cached Results ⚡ \u003c50ms]\n Cache -->|Miss| DB[(Database)]\n DB --> Store[Store in Cache 💾]\n Store --> Results[Search Results]\n\n Fast --> User\n Results --> User\n\n Note[Note: 80% cache hit rate reduces load time from 2s to 50ms]\n```\n\n**Update checklist:**\n- ✅ Added cache layer with impact annotation\n- ✅ Showed cache hit/miss paths\n- ✅ Quantified performance improvement\n- ✅ Updated related files to include cache service\n- ✅ Added change history entry\n- ✅ Updated last updated date\n\n### Pattern 2: Adding Error Handling\n\n**Scenario**: Added retry logic for failed API calls\n\n**Before:**\n```mermaid\nsequenceDiagram\n User->>API: Submit Form\n API->>DB: Save Data\n DB-->>API: Success\n API-->>User: Confirmation\n```\n\n**After:**\n```mermaid\nsequenceDiagram\n User->>API: Submit Form\n API->>DB: Save Data\n\n alt Success Path\n DB-->>API: Success\n API-->>User: Confirmation ✅\n else Failure Path\n DB-->>API: Error\n API->>API: Retry Logic 🔄 3 attempts\n alt Retry Succeeds\n API->>DB: Retry\n DB-->>API: Success\n API-->>User: Confirmation (Delayed) ✅\n else All Retries Fail\n API-->>User: Error Message with Save Draft 💾\n Note over User: User can save locally and retry later\n end\n end\n```\n\n**Update checklist:**\n- ✅ Added error path with retry logic\n- ✅ Showed recovery options (save draft)\n- ✅ Added impact annotations for resilience\n- ✅ Updated key insights about reliability\n- ✅ Updated related files (error handler)\n\n### Pattern 3: Refactoring Flow\n\n**Scenario**: Split monolithic service into microservices\n\n**Before:**\n```mermaid\ngraph TD\n User[User Action] --> Monolith[Monolithic Service]\n Monolith --> DB1[(Users DB)]\n Monolith --> DB2[(Orders DB)]\n Monolith --> DB3[(Inventory DB)]\n\n DB1 --> Response\n DB2 --> Response\n DB3 --> Response\n Response --> User\n```\n\n**After:**\n```mermaid\ngraph TD\n User[User Action] --> Gateway[API Gateway 🛡️ Routes requests]\n\n Gateway --> UserService[User Service ⚡ Independent scaling]\n Gateway --> OrderService[Order Service 💾 Owns order data]\n Gateway --> InventoryService[Inventory Service 📊 Real-time stock]\n\n UserService --> DB1[(Users DB)]\n OrderService --> DB2[(Orders DB)]\n InventoryService --> DB3[(Inventory DB)]\n\n DB1 --> Gateway\n DB2 --> Gateway\n DB3 --> Gateway\n\n Gateway --> Response[Aggregated Response ⚡ \u003c200ms]\n Response --> User\n\n Note[Note: Microservices enable independent deployment and scaling]\n```\n\n**Update checklist:**\n- ✅ Restructured diagram for new architecture\n- ✅ Added gateway with routing annotation\n- ✅ Separated services with clear responsibilities\n- ✅ Added impact annotations (scaling, independence)\n- ✅ Updated all related files (now 3 services)\n- ✅ Updated key insights about scalability\n\n### Pattern 4: Adding New Feature to Existing Flow\n\n**Scenario**: Added two-factor authentication to login\n\n**Before:**\n```mermaid\ngraph TD\n User[Enter Credentials] --> Validate[Validate]\n Validate -->|Valid| Auth[Authenticate 🛡️]\n Validate -->|Invalid| Error1[Show Error]\n\n Auth -->|Success| Dashboard\n Auth -->|Failed| Error2[Login Failed]\n```\n\n**After:**\n```mermaid\ngraph TD\n User[Enter Credentials] --> Validate[Validate ✅]\n Validate -->|Valid| Auth[Check Password 🛡️]\n Validate -->|Invalid| Error1[Show Error 🔄]\n\n Auth -->|Valid| TwoFactor{2FA Enabled?}\n Auth -->|Invalid| Error2[Login Failed 🔄]\n\n TwoFactor -->|Yes| SendCode[Send 2FA Code 🛡️ Extra security]\n TwoFactor -->|No| Dashboard\n\n SendCode --> EnterCode[User Enters Code]\n EnterCode --> VerifyCode[Verify Code ✅]\n\n VerifyCode -->|Valid| Dashboard[Redirect to Dashboard ✅]\n VerifyCode -->|Invalid| Error3[Invalid Code 🔄 Can retry]\n\n Error3 --> Resend[Resend Code Option]\n Resend --> EnterCode\n```\n\n**Update checklist:**\n- ✅ Added 2FA flow branch\n- ✅ Maintained existing non-2FA path\n- ✅ Added error handling for 2FA\n- ✅ Added resend code recovery option\n- ✅ Updated key insights about security\n- ✅ Updated related files (2FA service)\n\n## Common Update Scenarios\n\n### Scenario: File Renamed\n\n**Action**: Update \"Related Files\" section\n\n```markdown\n# Before\n**Related Files:**\n- `src/utils/helpers.ts`\n\n# After\n**Related Files:**\n- `src/utils/stringHelpers.ts`\n```\n\n**Change History:**\n```markdown\n- **2025-01-16:** Updated file path after refactoring utils directory\n```\n\n### Scenario: Performance Improved\n\n**Action**: Update impact annotations with new metrics\n\n```markdown\n# Before\nAPI Call [⚡ Fast response]\n\n# After\nAPI Call [⚡ \u003c100ms response (improved from 500ms)]\n```\n\n**Change History:**\n```markdown\n- **2025-01-16:** Updated performance metrics after optimization - 5x improvement\n```\n\n### Scenario: Error Handling Added\n\n**Action**: Add error path to diagram\n\n```markdown\n# Before (no error path)\nService --> DB --> Success\n\n# After (with error path)\nService --> DB\nDB -->|Success| Success\nDB -->|Error| ErrorHandler[Error Handler 🔄 Prevents data loss]\nErrorHandler --> Retry\n```\n\n**Change History:**\n```markdown\n- **2025-01-16:** Added error handling with automatic retry logic\n```\n\n### Scenario: New Dependency Added\n\n**Action**: Add new component to diagram\n\n```markdown\n# Before\nAPI --> Database\n\n# After\nAPI --> Cache[Cache Layer 💾 New dependency]\nCache --> Database\n```\n\n**Related Files** (add new files):\n```markdown\n- `src/services/cache/cacheService.ts` (new)\n```\n\n**Change History:**\n```markdown\n- **2025-01-16:** Added Redis caching layer for improved performance\n```\n\n## Batch Updates\n\nWhen multiple diagrams need updating:\n\n### 1. Create Update List\n\n```markdown\n## Diagrams to Update\n\n1. **feature-user-authentication.md**\n - Added 2FA flow\n - Update related files\n\n2. **sequence-login-journey.md**\n - Add 2FA steps\n - Update timing annotations\n\n3. **arch-system-overview.md**\n - Add 2FA service component\n - Update dependencies\n```\n\n### 2. Update Systematically\n\nProcess one diagram at a time:\n- Read current diagram\n- Make changes\n- Validate quality\n- Update metadata\n- Test Mermaid rendering\n\n### 3. Update Index\n\nAfter all updates, update `README.md`:\n\n```markdown\n## Last Updated\n\n2025-01-16 - Updated authentication diagrams to include 2FA implementation\n```\n\n## Validation After Updates\n\n### Mermaid Syntax Check\n\nTest diagram renders correctly:\n- Copy Mermaid code\n- Paste into [Mermaid Live Editor](https://mermaid.live)\n- Verify no syntax errors\n- Check layout and readability\n\n### DDD Compliance Check\n\n- [ ] Still shows Front-Stage and Back-Stage?\n- [ ] New components have impact annotations?\n- [ ] Error paths are included?\n- [ ] User value is clear?\n\n### Metadata Check\n\n- [ ] \"Last Updated\" is current date?\n- [ ] \"Related Files\" are accurate?\n- [ ] \"Change History\" has new entry?\n- [ ] \"Key Insights\" reflect changes?\n\n### Content Check\n\n- [ ] Diagram matches current code?\n- [ ] Performance metrics are accurate?\n- [ ] All branches are shown?\n- [ ] No obsolete components remain?\n\n## Troubleshooting\n\n### Diagram Too Complex After Updates\n\n**Problem**: Diagram now has too many components\n\n**Solutions:**\n1. Split into multiple diagrams (e.g., auth-overview + auth-2fa-detail)\n2. Use subgraphs to organize complexity\n3. Create separate Before/After refactoring diagram\n4. Move detailed flows to separate sequence diagrams\n\n### Can't Determine User Impact\n\n**Problem**: Technical change but unclear user benefit\n\n**Solutions:**\n1. Ask: \"What user problem does this solve?\"\n2. Look for performance improvements (speed)\n3. Look for reliability improvements (fewer errors)\n4. Look for security improvements (safer data)\n5. If no user impact, reconsider if change was necessary\n\n### Multiple Diagrams Affected\n\n**Problem**: One code change affects many diagrams\n\n**Solutions:**\n1. Prioritize: Update most important diagrams first\n2. Create checklist of all affected diagrams\n3. Update systematically to avoid missing any\n4. Consider if diagrams are too granular (consolidate?)\n\n### Unsure What Changed\n\n**Problem**: Can't remember what changed in code\n\n**Solutions:**\n```bash\n# View recent changes\ngit log --since=\"1 week ago\" --oneline\n\n# See specific file changes\ngit diff HEAD~5 path/to/file\n\n# Compare with diagram date\n# Diagram last updated: 2025-01-10\ngit log --since=\"2025-01-10\" --name-only path/to/related/files\n```\n\n## Best Practices\n\n1. **Update immediately after code changes** - Don't let diagrams drift\n2. **Be specific in change history** - Future you will thank you\n3. **Update impact annotations** - If performance improved, update metrics\n4. **Test Mermaid syntax** - Validate before committing\n5. **Update related files accurately** - Don't leave outdated paths\n6. **Keep user focus** - Every update should maintain user-centricity\n7. **Validate quality** - Run through DDD checklist\n8. **Batch related updates** - Update all affected diagrams together\n\n## Next Steps\n\nAfter updating diagrams:\n1. Commit changes with descriptive message\n2. Update README.md if needed\n3. Reference in pull request description\n4. Use in code review to explain changes\n5. Share with team in documentation channels\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":13312,"content_sha256":"0b09ef5eef6cc7e9abe9ec6d9891735401a6b5a0fdc3a0176e0e262c7bffe403"}],"content_json":{"type":"doc","content":[{"type":"heading","attrs":{"level":1},"content":[{"text":"Diagram Driven Development (DDD) Skill","type":"text"}]},{"type":"paragraph","content":[{"text":"Maintain the ","type":"text"},{"text":"ai/diagrams","type":"text","marks":[{"type":"code_inline"}]},{"text":" directory as the single source of truth for system understanding. All diagrams follow DDD principles, connecting Front-Stage (user experience) to Back-Stage (technical implementation) with clear impact annotations.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Capabilities","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Create Diagrams","type":"text","marks":[{"type":"strong"}]},{"text":" - Generate new diagrams for features, architectures, journeys, tests, and refactorings","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Update Diagrams","type":"text","marks":[{"type":"strong"}]},{"text":" - Synchronize existing diagrams with code changes","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Audit Diagrams","type":"text","marks":[{"type":"strong"}]},{"text":" - Identify outdated, missing, or low-quality diagrams","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Organize Diagrams","type":"text","marks":[{"type":"strong"}]},{"text":" - Maintain consistent structure and naming conventions","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Index Management","type":"text","marks":[{"type":"strong"}]},{"text":" - Keep README.md index up-to-date with all diagrams","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Quality Validation","type":"text","marks":[{"type":"strong"}]},{"text":" - Ensure all diagrams follow DDD principles","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Quick Reference","type":"text"}]},{"type":"paragraph","content":[{"text":"For detailed instructions on each operation, see:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"CREATE.md","type":"text","marks":[{"type":"link","attrs":{"href":"references/CREATE.md","title":null}}]},{"text":" - Creating new diagrams","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"UPDATE.md","type":"text","marks":[{"type":"link","attrs":{"href":"references/UPDATE.md","title":null}}]},{"text":" - Updating existing diagrams","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"AUDIT.md","type":"text","marks":[{"type":"link","attrs":{"href":"references/AUDIT.md","title":null}}]},{"text":" - Auditing diagram quality and coverage","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"ORGANIZE.md","type":"text","marks":[{"type":"link","attrs":{"href":"references/ORGANIZE.md","title":null}}]},{"text":" - Directory structure and naming","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"DDD_PRINCIPLES.md","type":"text","marks":[{"type":"link","attrs":{"href":"references/DDD_PRINCIPLES.md","title":null}}]},{"text":" - Diagram Driven Development methodology","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"MERMAID_GUIDE.md","type":"text","marks":[{"type":"link","attrs":{"href":"references/MERMAID_GUIDE.md","title":null}}]},{"text":" - Mermaid syntax patterns","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Directory Structure","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":""},"content":[{"text":"ai/diagrams/\n├── README.md # Index of all diagrams\n├── features/ # Feature-specific diagrams\n├── architecture/ # System architecture diagrams\n├── journeys/ # User journey diagrams\n├── tests/ # Test coverage diagrams\n└── refactoring/ # Before/After improvement diagrams","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Common Workflows","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Initial Setup Workflow","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"User starts new project or adds DDD to existing project","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Create ","type":"text"},{"text":"ai/diagrams/","type":"text","marks":[{"type":"code_inline"}]},{"text":" directory structure","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Generate initial system architecture diagram","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Create README.md index","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Document key user journeys","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"New Feature Workflow","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"User requests new feature","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Create feature diagram showing user value","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Connect Front-Stage (UX) to Back-Stage (implementation)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Document related files and components","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Update README.md index","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Code Change Workflow","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Code is modified (new features, refactoring, etc.)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Identify affected diagrams","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Update diagrams to reflect changes","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Update \"Last Updated\" dates","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Add change history entries","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Audit Workflow","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"User requests diagram audit","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Scan all diagrams in ","type":"text"},{"text":"ai/diagrams/","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Check for outdated diagrams (compare dates with git)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Identify missing diagrams (features without diagrams)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Validate DDD quality (Front-Stage/Back-Stage, impact annotations)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Report findings and recommendations","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Refactoring Documentation Workflow","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"User plans code refactoring","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Create \"Before\" diagram showing current state","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Create \"After\" diagram showing improved state (highlight changes in #90EE90)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Add impact annotations explaining user benefits","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Store in ","type":"text"},{"text":"refactoring/","type":"text","marks":[{"type":"code_inline"}]},{"text":" directory","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Critical Instructions","type":"text"}]},{"type":"paragraph","content":[{"text":"REQUIRED","type":"text","marks":[{"type":"strong"}]},{"text":": Before performing ANY diagram operations, you MUST load the relevant reference file(s) using the Read tool. These references contain essential DDD principles, quality standards, and operational procedures that are NOT included in this overview.","type":"text"}]},{"type":"paragraph","content":[{"text":"When the user asks to work with diagrams:","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Identify the operation","type":"text","marks":[{"type":"strong"}]},{"text":" they want to perform (create, update, audit, organize)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"MANDATORY: Load the relevant reference file(s)","type":"text","marks":[{"type":"strong"}]},{"text":" using the Read tool BEFORE executing any operations:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Creating diagrams → Read ","type":"text"},{"text":"references/CREATE.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" AND ","type":"text"},{"text":"references/DDD_PRINCIPLES.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" FIRST","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Updating diagrams → Read ","type":"text"},{"text":"references/UPDATE.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" AND ","type":"text"},{"text":"references/DDD_PRINCIPLES.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" FIRST","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Auditing diagrams → Read ","type":"text"},{"text":"references/AUDIT.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" FIRST","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Organizing/restructuring → Read ","type":"text"},{"text":"references/ORGANIZE.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" FIRST","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Understanding DDD → Read ","type":"text"},{"text":"references/DDD_PRINCIPLES.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" FIRST","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Mermaid syntax help → Read ","type":"text"},{"text":"references/MERMAID_GUIDE.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" FIRST","type":"text"}]}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Execute diagram operations","type":"text","marks":[{"type":"strong"}]},{"text":" following the exact patterns and quality standards from the loaded references","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Validate quality","type":"text","marks":[{"type":"strong"}]},{"text":" using DDD principles checklist","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Update index","type":"text","marks":[{"type":"strong"}]},{"text":" in README.md to reflect changes","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Confirm actions","type":"text","marks":[{"type":"strong"}]},{"text":" and show diagram preview when possible","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"DO NOT attempt to create or modify diagrams without first loading and reading the relevant reference documentation, especially DDD_PRINCIPLES.md.","type":"text","marks":[{"type":"strong"}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"DDD Core Principles (Brief)","type":"text"}]},{"type":"paragraph","content":[{"text":"Every diagram MUST include:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"✅ ","type":"text"},{"text":"Front-Stage","type":"text","marks":[{"type":"strong"}]},{"text":" (user experience) AND ","type":"text"},{"text":"Back-Stage","type":"text","marks":[{"type":"strong"}]},{"text":" (implementation)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"✅ ","type":"text"},{"text":"Impact Annotations","type":"text","marks":[{"type":"strong"}]},{"text":" explaining user value of technical components","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"✅ ","type":"text"},{"text":"User Actions","type":"text","marks":[{"type":"strong"}]},{"text":" as entry/exit points","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"✅ ","type":"text"},{"text":"Error Paths","type":"text","marks":[{"type":"strong"}]},{"text":" and recovery options","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"✅ ","type":"text"},{"text":"Related Files","type":"text","marks":[{"type":"strong"}]},{"text":" documentation","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"❌ NO custom fill colors (except ","type":"text"},{"text":"#90EE90","type":"text","marks":[{"type":"code_inline"}]},{"text":" for Before/After changes)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"❌ NO purely technical diagrams without user context","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Naming Conventions","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"File Names","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Descriptive lowercase with hyphens","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Include diagram type prefix","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Format: ","type":"text"},{"text":"{type}-{descriptive-name}.md","type":"text","marks":[{"type":"code_inline"}]}]}]}]},{"type":"paragraph","content":[{"text":"Examples:","type":"text","marks":[{"type":"strong"}]}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"feature-user-checkout-flow.md","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"sequence-authentication-journey.md","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"arch-system-overview.md","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"flow-payment-processing.md","type":"text","marks":[{"type":"code_inline"}]}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Type Prefixes","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"feature-","type":"text","marks":[{"type":"code_inline"}]},{"text":" - Feature-specific diagrams","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"sequence-","type":"text","marks":[{"type":"code_inline"}]},{"text":" - Sequence/journey diagrams","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"arch-","type":"text","marks":[{"type":"code_inline"}]},{"text":" - Architecture diagrams","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"flow-","type":"text","marks":[{"type":"code_inline"}]},{"text":" - Flow/process diagrams","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"test-","type":"text","marks":[{"type":"code_inline"}]},{"text":" - Test coverage diagrams","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Diagram File Structure","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"markdown"},"content":[{"text":"# [Diagram Title]\n\n**Type:** [Feature Diagram | Sequence Diagram | Architecture Diagram | etc.]\n**Last Updated:** [YYYY-MM-DD]\n**Related Files:**\n- `path/to/implementation.ts`\n- `path/to/component.tsx`\n\n## Purpose\n\n[1-2 sentence description of what user value this diagram illustrates]\n\n## Diagram\n\n\\`\\`\\`mermaid\n[Mermaid diagram code following DDD principles]\n\\`\\`\\`\n\n## Key Insights\n\n- [User impact point 1]\n- [User impact point 2]\n- [Technical enabler point 1]\n\n## Change History\n\n- **YYYY-MM-DD:** [Description of change]","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Quality Checklist","type":"text"}]},{"type":"paragraph","content":[{"text":"Before storing any diagram, verify:","type":"text"}]},{"type":"checkbox_list","attrs":{"id":null},"content":[{"type":"checkbox_item","attrs":{"checked":false},"content":[{"type":"paragraph","content":[{"text":"Shows both Front-Stage (user experience) AND Back-Stage (implementation)","type":"text"}]}]},{"type":"checkbox_item","attrs":{"checked":false},"content":[{"type":"paragraph","content":[{"text":"Impact annotations explain user value","type":"text"}]}]},{"type":"checkbox_item","attrs":{"checked":false},"content":[{"type":"paragraph","content":[{"text":"User actions are clearly visible","type":"text"}]}]},{"type":"checkbox_item","attrs":{"checked":false},"content":[{"type":"paragraph","content":[{"text":"Error paths shown","type":"text"}]}]},{"type":"checkbox_item","attrs":{"checked":false},"content":[{"type":"paragraph","content":[{"text":"NO custom fill colors (except #90EE90 for changes)","type":"text"}]}]},{"type":"checkbox_item","attrs":{"checked":false},"content":[{"type":"paragraph","content":[{"text":"Related code files documented","type":"text"}]}]},{"type":"checkbox_item","attrs":{"checked":false},"content":[{"type":"paragraph","content":[{"text":"Last updated date is current","type":"text"}]}]},{"type":"checkbox_item","attrs":{"checked":false},"content":[{"type":"paragraph","content":[{"text":"Key insights explain user impact","type":"text"}]}]},{"type":"checkbox_item","attrs":{"checked":false},"content":[{"type":"paragraph","content":[{"text":"Mermaid syntax is valid","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Best Practices","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Keep diagrams synchronized","type":"text","marks":[{"type":"strong"}]},{"text":" - Outdated diagrams are worse than no diagrams","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Follow DDD principles","type":"text","marks":[{"type":"strong"}]},{"text":" - Every diagram connects user value to implementation","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Use subdirectories","type":"text","marks":[{"type":"strong"}]},{"text":" - Organize by type to prevent chaos","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Maintain the index","type":"text","marks":[{"type":"strong"}]},{"text":" - README.md is the entry point","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Document changes","type":"text","marks":[{"type":"strong"}]},{"text":" - Update change history when modifying","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Validate quality","type":"text","marks":[{"type":"strong"}]},{"text":" - Run through DDD checklist before saving","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Reference code files","type":"text","marks":[{"type":"strong"}]},{"text":" - Link diagrams to actual implementation","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Show error paths","type":"text","marks":[{"type":"strong"}]},{"text":" - Don't just show happy paths","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Use consistent naming","type":"text","marks":[{"type":"strong"}]},{"text":" - Predictable names enable navigation","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Update after code changes","type":"text","marks":[{"type":"strong"}]},{"text":" - Diagrams must reflect current state","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Integration with Other Skills","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"review","type":"text","marks":[{"type":"strong"}]},{"text":" - Reference diagrams during code reviews to explain impact","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"github","type":"text","marks":[{"type":"strong"}]},{"text":" - Link diagrams in issue descriptions for context","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"chrome-devtools","type":"text","marks":[{"type":"strong"}]},{"text":" - Use diagrams to plan testing flows","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Examples","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Create feature diagram","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":""},"content":[{"text":"User: \"Create a diagram for the new notification system\"\nAgent:\n1. Reads references/CREATE.md and references/DDD_PRINCIPLES.md\n2. Analyzes notification feature code\n3. Creates feature-notification-system.md in features/\n4. Includes user journey and technical implementation\n5. Adds impact annotations\n6. Updates README.md index","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Update after refactoring","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":""},"content":[{"text":"User: \"We just refactored the auth flow, update the diagram\"\nAgent:\n1. Reads references/UPDATE.md\n2. Finds sequence-authentication-journey.md\n3. Compares with new code\n4. Updates diagram with changes\n5. Updates \"Last Updated\" date\n6. Adds change history entry","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Audit all diagrams","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":""},"content":[{"text":"User: \"Audit our diagrams\"\nAgent:\n1. Reads references/AUDIT.md and references/DDD_PRINCIPLES.md\n2. Scans ai/diagrams/ directory\n3. Checks each diagram against DDD checklist\n4. Compares diagram dates with git history\n5. Identifies missing diagrams\n6. Reports findings with recommendations","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Critical Rules","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Diagrams MUST stay synchronized with code","type":"text","marks":[{"type":"strong"}]},{"text":" - Check git history vs diagram dates","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Every diagram MUST follow DDD principles","type":"text","marks":[{"type":"strong"}]},{"text":" - No purely technical diagrams","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Organization is critical","type":"text","marks":[{"type":"strong"}]},{"text":" - Use subdirectories consistently","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Index MUST be maintained","type":"text","marks":[{"type":"strong"}]},{"text":" - README.md reflects all diagrams","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"File naming MUST be consistent","type":"text","marks":[{"type":"strong"}]},{"text":" - Follow type-name pattern","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Quality over quantity","type":"text","marks":[{"type":"strong"}]},{"text":" - Better to have 5 great diagrams than 20 poor ones","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"User value is paramount","type":"text","marks":[{"type":"strong"}]},{"text":" - Every technical detail must connect to user impact","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Always load references first","type":"text","marks":[{"type":"strong"}]},{"text":" - DDD principles are not negotiable","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Workflow Integration","type":"text"}]},{"type":"paragraph","content":[{"text":"This skill integrates with development workflow:","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Before Code Changes","type":"text","marks":[{"type":"strong"}]},{"text":" - Review existing diagrams to understand system","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"During Planning","type":"text","marks":[{"type":"strong"}]},{"text":" - Create proposal diagrams showing planned changes","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"During Implementation","type":"text","marks":[{"type":"strong"}]},{"text":" - Reference diagrams to maintain alignment","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"After Implementation","type":"text","marks":[{"type":"strong"}]},{"text":" - Update diagrams to reflect changes","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"During Review","type":"text","marks":[{"type":"strong"}]},{"text":" - Use diagrams to explain impact and context","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"During Onboarding","type":"text","marks":[{"type":"strong"}]},{"text":" - Diagrams serve as documentation for new team members","type":"text"}]}]}]},{"type":"hr","attrs":{"markup":"---"}}]},"metadata":{"date":"2026-06-05","name":"diagram","author":"@skillopedia","source":{"stars":24,"repo_name":"claude","origin_url":"https://github.com/johnlindquist/claude/blob/HEAD/skills/diagram/SKILL.md","repo_owner":"johnlindquist","body_sha256":"242ee65f8f9e633fee6ca7513c30a82a8daebb8105653081a5a69a1a36a3e64d","cluster_key":"b66a77b2bc1fea68a41881dcc4966a1dd5b7896d93331712aac2383438e4b79a","clean_bundle":{"format":"clean-skill-bundle-v1","source":"johnlindquist/claude/skills/diagram/SKILL.md","attachments":[{"id":"d2713c8c-8408-5234-ad11-d591af0b5da3","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/d2713c8c-8408-5234-ad11-d591af0b5da3/attachment.md","path":"README.md","size":13682,"sha256":"cc89e01a459673bde009c49fa370a6e977108609821a751f08f76d6d469a8925","contentType":"text/markdown; charset=utf-8"},{"id":"4ad6a303-1f7c-510a-b442-af448024b6ca","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/4ad6a303-1f7c-510a-b442-af448024b6ca/attachment.md","path":"references/AUDIT.md","size":13680,"sha256":"803ec2a504666a1590b4a05bfb338ceb61e147de413972beb7087d34ca7b174a","contentType":"text/markdown; charset=utf-8"},{"id":"bbb1de93-b22f-5654-bf6f-140aeb965981","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/bbb1de93-b22f-5654-bf6f-140aeb965981/attachment.md","path":"references/CREATE.md","size":16272,"sha256":"5f130db2574dbabb9a6ccdeef8116afab959efb6e20a3a38e74ec34ea751fa9d","contentType":"text/markdown; charset=utf-8"},{"id":"2dd439d0-53d1-5bf2-8b06-698a7e0685aa","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/2dd439d0-53d1-5bf2-8b06-698a7e0685aa/attachment.md","path":"references/DDD_PRINCIPLES.md","size":12699,"sha256":"3e32460c98d02cf97514cba33ef5f6b9da05d9e1fca19501071b11d1ff0efa59","contentType":"text/markdown; charset=utf-8"},{"id":"9ac8f437-d132-5b6a-bde5-9191db53dbe1","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/9ac8f437-d132-5b6a-bde5-9191db53dbe1/attachment.md","path":"references/MERMAID_GUIDE.md","size":8963,"sha256":"bb223e0a036819c8ac6a1f70474b1b3ff35c03cae93bab5df398e4c0da6b1ab0","contentType":"text/markdown; charset=utf-8"},{"id":"4abd3de2-2f63-50c7-a07a-3556c7198673","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/4abd3de2-2f63-50c7-a07a-3556c7198673/attachment.md","path":"references/ORGANIZE.md","size":12806,"sha256":"1df7ec93ad85a14273744218bf32281eeacfafbb84135d0dc5757990a2a0b30b","contentType":"text/markdown; charset=utf-8"},{"id":"dc28dc7b-005b-5fbf-9c95-106610ce37b6","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/dc28dc7b-005b-5fbf-9c95-106610ce37b6/attachment.md","path":"references/UPDATE.md","size":13312,"sha256":"0b09ef5eef6cc7e9abe9ec6d9891735401a6b5a0fdc3a0176e0e262c7bffe403","contentType":"text/markdown; charset=utf-8"}],"bundle_sha256":"3a9fe69d5150eca6a54123ef1bae6b5cf784cabc289f7caeb1ff186711d29207","attachment_count":7,"text_attachments":7,"attachment_storage":"skillopedia-attachments-v1","binary_attachments":0,"excluded_attachments":[]},"cluster_size":1,"skill_md_path":"skills/diagram/SKILL.md","import_metadata":{"date":"2026-06-05","author":"@skillopedia","version":"v1","category":"software-engineering","category_label":"Engineering"},"exact_dupes_collapsed_into_this":0},"version":"v1","category":"software-engineering","import_tag":"clean-skills-v1","description":"Use this skill whenever a \"diagram\" is mentioned. Maintain and synchronize Unified Impact Diagrams following Diagram Driven Development (DDD) methodology. Create, update, and manage diagrams that connect user value to technical implementation.","allowed-tools":"Bash, Glob, Read, Write, Edit"}},"renderedAt":1782988098719}

Important: agents should read /llm.txt, /llms.txt, or /.well-known/skills.json to discover the public Skillopedia API.