slp-modular-cms/aidlc-docs/gap-reports/gap-004-unit-2-diagrams-not-mermaid.md

Gap-004: Unit 2 Functional Design Diagrams Not in Mermaid Format

Issue Summary

Unit 2 functional design artifacts (frontend-components.md, domain-entities.md, business-logic-model.md) contain textual/ASCII diagrams instead of Mermaid diagrams. This violates aidlc-workflow content validation rules (common/content-validation.md) that explicitly require:

• All diagrams MUST be Mermaid syntax
• ASCII/textual diagram variants are FORBIDDEN
• Diagrams MUST use color to differentiate components

Root Cause

During Unit 2 Functional Design artifact generation, the AI model created textual component hierarchies and entity relationship trees instead of converting them to Mermaid syntax. This was an oversight in content validation enforcement at generation time.

Affected Files

1. aidlc-docs/features/cms-frontend/construction/unit-2/functional-design/frontend-components.md

   • Section: "## Component Hierarchy" (lines 7–29)
   • Current format: ASCII tree with ├──, └──, │ characters
   • Required: Mermaid graph TD with color classes

2. aidlc-docs/features/cms-frontend/construction/unit-2/functional-design/domain-entities.md

   • Section: "## Relationships & Dependencies" → "### Entity Relationships" (lines 170–182)
   • Current format: ASCII tree showing entity dependencies
   • Required: Mermaid graph LR or classDiagram with color classes

3. aidlc-docs/features/cms-frontend/construction/unit-2/functional-design/business-logic-model.md (Optional but recommended)

   • Missing visual flow diagrams for the 3 business flows
   • Required: Sequence diagrams for Setup Flow and Invitation Flow; Graph diagram for RBAC Flow

Conversion Standards

Mermaid Format Requirements

All converted diagrams MUST:

1. Use valid Mermaid syntax (tested/validated)
2. Include classDef or style directives with colors
3. Color components by type/role:
   • Root/System components: fill:#4CAF50 (green)
   • Guards/Auth components: fill:#FF9800 (orange)
   • Pages/UI components: fill:#2196F3 (blue)
   • API/Hooks components: fill:#9C27B0 (purple)
   • External/Backend: fill:#F44336 (red)
4. Include a one-line text alternative immediately after each Mermaid code block
5. Escape special characters: " → \", ' → \'
6. Use alphanumeric + underscore only for node IDs (no hyphens in IDs)

Validation Checklist

• Syntax is valid Mermaid (no parse errors)
• Color classes are defined via classDef or style
• All nodes/participants have color assignments
• Text alternative is present and descriptive
• Diagram conveys the same information as original ASCII version
• Diagram fits context (readable, not overly complex)

Solution

File 1: frontend-components.md

Original information to preserve:

• __root.tsx is the root layout
• InitGuard (wrapper/hook) is at root level
• _authenticated.tsx is a protected layout wrapping protected routes
• ProtectedRoute and RoleGuard protect routes
• Unprotected routes: /setup, /login, /invite/complete
• Protected routes: /dashboard, /profile, /users, /settings, /cms

Conversion approach: Mermaid graph TD with layers

---

File 2: domain-entities.md

Original information to preserve:

• User entity relationships (created by Setup or Invitation, stored in AuthContext)
• SetupStatus controls InitGuard logic
• InvitationToken used to create User
• PasswordCredential shared across forms
• RoleGuard reads User.role for access control

Conversion approach: Mermaid graph LR showing entity dependencies

---

File 3: business-logic-model.md (Optional)

Add visual flow diagrams for:

1. Setup Flow (sequence: user → SetupPage → POST /Setup → login redirect)
2. Invitation Flow (sequence: user → InviteCompletePage → token validation → POST /Invitation/complete → login redirect)
3. RBAC Decision Flow (graph: role check → allow vs. deny)

Conversion approach: Mermaid sequenceDiagram + graph with proper coloring

---

Success Criteria

• Gap identified and documented
• All ASCII diagrams converted to Mermaid syntax
• All Mermaid diagrams render correctly (no parse errors)
• All diagrams include color coding
• All diagrams include text alternatives
• No special character escaping errors
• Information completeness matches original ASCII versions
• Files validated and ready for Unit 2 approval

---

Impact

Severity: Medium (content validation violation, blocks Unit 2 completion)
Scope: Unit 2 Functional Design artifacts only
Timeline: Must be fixed before Unit 2 Functional Design approval
Dependencies: None (can be fixed independently)

---

References

• Workflow rule: C:\Users\Bryan\.claude\skills\aidlc-workflow\.aidlc-rule-details\common\content-validation.md
• Mermaid standards: C:\Users\Bryan\.claude\skills\aidlc-workflow\.aidlc-rule-details\common\mermaid-diagram-standards.md
• Unit 1 color examples: Existing Mermaid diagrams in Unit 1 artifacts (e.g., unit-of-work.md)

---

Opened: 2026-06-20
Status: In Progress
Assigned to: AI Assistant (diagram conversion task)
Resolution: Immediate (diagrams converted and validated)