Adds unit 2 functional design and code generation plan and gap 4 report

2026-06-21 23:28:45 +02:00
parent ab93a5c7d1
commit f9689d2091
9 changed files with 1567 additions and 1003 deletions
@@ -0,0 +1,129 @@
+# 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
+
+- [x] 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)