119 lines
6.9 KiB
Markdown
119 lines
6.9 KiB
Markdown
# PRD: Mermaid Diagram Rendering Stabilization
|
|
|
|
## Summary
|
|
- Scope: Documentation Mermaid diagrams in this vault.
|
|
- Discovery date: 2026-05-24.
|
|
- Total Mermaid blocks checked: `57`.
|
|
- Total failing blocks: `11`.
|
|
- Tooling used: `@mermaid-js/mermaid-cli` parse validation for each extracted block.
|
|
|
|
## Goal
|
|
Create a pass-ready task queue of Mermaid syntax/render issues so each diagram can be corrected one-by-one without guessing.
|
|
|
|
## Acceptance Criteria
|
|
- Every Mermaid block parses successfully with the same mmdc-based syntax validation.
|
|
- Diagrams render in Obsidian/markdown previews without parser errors.
|
|
- Each corrected block retains the same intent and participant names where possible.
|
|
|
|
## Task 1 - Security Architecture: Email + password sequence
|
|
- **File:** `01 - Architecture/Security Architecture.md`
|
|
- **Diagram range:** `38-57` (Authentication layers / 2.1)
|
|
- **Error:** Parse error line 12: `...nAttempts; lock at N BE-->>FE: 4`
|
|
- **Likely issue:** Sequence parser is choking around a message containing inline punctuation and line continuation (`;` and `...`), likely interpreted as malformed sequence text.
|
|
- **Fix:** Keep the message text parser-safe (single simple `:` message per line; avoid special separators like unescaped semicolons) and rerun parser.
|
|
|
|
## Task 2 - Authentication Flow: Login sequence
|
|
- **File:** `04 - Flows/Authentication Flow.md`
|
|
- **Diagram range:** `57-90` (`## Sequence diagram`)
|
|
- **Error:** Parse error line 48: `...Tokens.push(refresh) BE->>BE: ge`
|
|
- **Likely issue:** Line includes inline method-like token with parentheses-like/space patterns and tokenization ambiguity.
|
|
- **Fix:** Replace the problematic statement with plain text in message, e.g. `BE->>DB: User.refreshTokens.push(refreshToken)` as one line.
|
|
|
|
## Task 3 - Authentication Flow: Refresh token flow
|
|
- **File:** `04 - Flows/Authentication Flow.md`
|
|
- **Diagram range:** `127-143` (`## Refresh flow`)
|
|
- **Error:** Parse error line 11: `... is in user.refreshTokens BE->>BE: Genera`
|
|
- **Likely issue:** Special math-style characters and expression-like message text interrupting parser tokenization.
|
|
- **Fix:** Replace special symbols in message text with plain ASCII and split to simple message line(s).
|
|
|
|
## Task 4 - Chat Flow: typing/chat notification sequence
|
|
- **File:** `04 - Flows/Chat Flow.md`
|
|
- **Diagram range:** `91-125` (`## Sequence diagram`)
|
|
- **Error:** Parse error line 20: `...ata.lastActivity=now BE->>IO: emit c`
|
|
- **Likely issue:** Assignment-style text (`...=now`) in message and possible bare punctuation in one-line payload.
|
|
- **Fix:** Simplify message bodies around state updates to readable text only.
|
|
|
|
## Task 5 - Delivery Confirmation Flow: code verification sequence
|
|
- **File:** `04 - Flows/Delivery Confirmation Flow.md`
|
|
- **Diagram range:** `45-71` (`## Sequence diagram`)
|
|
- **Error:** Parse error line 22: `...; status="delivered" BE->>IO: emit r`
|
|
- **Likely issue:** Double status expression in message (`deliveryCodeUsed=true; status="delivered"`).
|
|
- **Fix:** Split into two explicit sequence lines or rephrase with punctuation-safe text.
|
|
|
|
## Task 6 - Dispute Flow: admin resolve sequence
|
|
- **File:** `04 - Flows/Dispute Flow.md`
|
|
- **Diagram range:** `90-134` (`## Sequence diagram`)
|
|
- **Error:** Parse error line 18: `... is dispute } FE-->>B,S: chat opens (real`
|
|
- **Likely issue:** Invalid multi-recipient send syntax `B,S` on one arrow line.
|
|
- **Fix:** Either split into two lines (`FE-->>B:` and `FE-->>S:`) or route via a shared frontend/chat intermediary.
|
|
|
|
## Task 7 - Google OAuth Flow: completion sequence
|
|
- **File:** `04 - Flows/Google OAuth Flow.md`
|
|
- **Diagram range:** `56-96` (`## Sequence diagram`)
|
|
- **Error:** Parse error line 34: `...fill avatar if blank end BE->>BE`
|
|
- **Likely issue:** `end`/branch block combined with following arrow in parser context likely due missing separation in message-heavy block.
|
|
- **Fix:** Ensure `opt ... end` block boundaries and arrows are on clean, standalone lines.
|
|
|
|
## Task 8 - Purchase Request Flow: publish sequence
|
|
- **File:** `04 - Flows/Purchase Request Flow.md`
|
|
- **Diagram range:** `94-129` (`## Sequence diagram`)
|
|
- **Error:** Parse error line 27: `...ds; compute isPublic BE->>DB: Purcha`
|
|
- **Likely issue:** Message text includes expressions (`compute isPublic`) and punctuation (`;`) that are breaking the sequence parser.
|
|
- **Fix:** Rephrase backend processing lines into simple text without `;`/embedded expressions.
|
|
|
|
## Task 9 - Referral Flow: conversion and payout sequence
|
|
- **File:** `04 - Flows/Referral Flow.md`
|
|
- **Diagram range:** `70-99` (`## Sequence diagram`)
|
|
- **Error:** Parse error line 26: `...Transaction.create; update`
|
|
- **Likely issue:** Message text around chained commands (`updateUserLevel`) appears parser-conflicting.
|
|
- **Fix:** Break chained method-like messages into one action-per-line statements.
|
|
|
|
## Task 10 - Registration Flow: email verification sequence
|
|
- **File:** `04 - Flows/Registration Flow.md`
|
|
- **Diagram range:** `87-127` (`## Sequence diagram`)
|
|
- **Error:** Parse error line 36: `...tokens.push(refresh) BE->>BE: 200`
|
|
- **Likely issue:** Message line includes token-manipulation call style in plain text causing parser confusion.
|
|
- **Fix:** Reword to plain textual action; keep method calls minimal.
|
|
|
|
## Task 11 - Seller Offer Flow: submit offer sequence
|
|
- **File:** `04 - Flows/Seller Offer Flow.md`
|
|
- **Diagram range:** `97-134` (`## Sequence diagram`)
|
|
- **Error:** Parse error line 16: `...ETA, notes; submit FE_S->>BE: POST`
|
|
- **Likely issue:** Message with `; submit` and inline comma-separated action text.
|
|
- **Fix:** Split into cleaner action lines before POST step.
|
|
|
|
## Execution Order
|
|
1. Address Task 6 first (obvious syntax violation) to quickly cut down parse noise.
|
|
2. Tackle Tasks 2, 3, 5, 8, 9, 10, 11 (message-format cleanup).
|
|
3. Validate with a full parser sweep after each batch.
|
|
4. Final sweep: re-run mmdc parse validation across all `57` Mermaid blocks and close this PRD once no errors remain.
|
|
|
|
## Current Run Status
|
|
- Execution date: 2026-05-24
|
|
- Parallel passes launched: 3
|
|
- Result: All targeted task files pass `@mermaid-js/mermaid-cli` parsing.
|
|
- Full vault sweep (all markdown Mermaid blocks): **pass**.
|
|
|
|
### Task Completion
|
|
- Task 1: Complete (Security Architecture sequence lines simplified)
|
|
- Task 2: Complete (Authentication login refresh token line split/rephrased)
|
|
- Task 3: Complete (Authentication refresh-flow syntax normalized)
|
|
- Task 4: Complete (Chat flow update-message line rewritten)
|
|
- Task 5: Complete (Delivery confirmation message split into safe lines)
|
|
- Task 6: Complete (Dispute flow multi-recipient send split into separate arrows)
|
|
- Task 7: Complete (Google OAuth flow statement ordering fixed)
|
|
- Task 8: Complete (Purchase Request preference/public logic split into separate action lines)
|
|
- Task 9: Complete (Referral flow user-points action split)
|
|
- Task 10: Complete (Registration token update line split)
|
|
- Task 11: Complete (Seller Offer flow rewritten into parser-safe sequence diagram)
|