nick-doc/PRD - Mermaid Diagram Fixes.md

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)