# 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)