Summary of All Errors Fixed

This document lists all mermaid diagram syntax errors found in the Angular System Design 2026 Guide, their fixes, and comprehensive instructions for AI/LLM models to prevent these errors.

Error Categories and Fixes

1. Invalid Edge Label |\1| (56 occurrences)

Error Pattern:

Parse Error:

• Mermaid interprets \1 as an escape sequence or invalid syntax
• Appears to be a placeholder that wasn’t replaced

Fix:

Files Affected:

• angular-foundations-beyond-basics.md (2)
• resilience-graceful-degradation.md (10)
• project-microfrontend-portal.md (4)
• ci-cd-enterprise-angular.md (6)
• core-angular-architectural-patterns.md (12)
• project-admin-dashboard.md (4)
• observability-monitoring-angular.md (10)
• performance-budgeting-optimization.md (2)
• project-offline-field-app.md (1)
• microfrontends-concepts-integration.md (8)

2. Parentheses in Subgraph Names

Error Pattern:

Parse Error:

Expecting 'SEMI', 'NEWLINE', 'SPACE', 'EOF', got 'PS'

Fix:

Files Affected:

• core-angular-architectural-patterns.md
• observability-monitoring-angular.md
• project-admin-dashboard.md
• data-fetching-caching-offline.md
• project-offline-field-app.md

3. Ampersands (&) in Subgraph Names

Error Pattern:

Parse Error:

• Ampersand is interpreted as a special character

Fix:

Files Affected:

• observability-monitoring-angular.md
• data-fetching-caching-offline.md

4. Complex Text in Decision Nodes

Error Pattern:

Parse Error:

Expecting 'SQE', 'DOUBLECIRCLEEND', got 'PS'

Fix:

Explanation: Decision nodes {...} should have simple text. Use rectangular nodes [...] for complex labels.

Files Affected:

• ci-cd-enterprise-angular.md
• project-white-label-saas-ui.md

5. Colons in Node Labels

Error Pattern:

Parse Error:

• Colon can cause parsing issues in some contexts

Fix:

Files Affected:

• project-microfrontend-portal.md

6. Incorrect Dotted Arrow Syntax

Error Pattern:

Parse Error:

Lexical error. Unrecognized text.

Fix:

Explanation: Three dashes -- before dot is incorrect. Use single dash-dot-arrow -.->.

Files Affected:

• project-microfrontend-portal.md
• project-offline-field-app.md

7. Semicolons in Edge Labels

Error Pattern:

Parse Error:

Expecting 'SOLID_OPEN_ARROW', got 'NEWLINE'

Fix:

Files Affected:

• security-best-practices.md

8. Double Quotes in Node Labels

Error Pattern:

Parse Error:

Expecting 'SQE', 'DOUBLECIRCLEEND', got 'STR'

Fix:

Files Affected:

• resilience-graceful-degradation.md

9. Parentheses in Edge Labels

Error Pattern:

Parse Error:

Expecting 'SQE', 'DOUBLECIRCLEEND', got 'PS'

Fix:

Files Affected:

• whats-next-angular-architecture.md

Additional Potential Errors (Not Found But Likely)

10. Brackets in Node IDs

Potential Error:

Should Be:

11. Special Characters in Node IDs

Potential Error:

Should Be:

12. Slashes in Labels

Potential Error:

Should Be:

or

13. Hash/Pound Signs in Text

Potential Error:

Should Be:

14. Percentage Signs

Potential Error:

Should Be:

15. Equals Signs in Edge Labels

Potential Error:

Should Be:

16. Multiple Spaces or Tabs

Potential Error:

Should Be:

Comprehensive Instructions for AI/LLM Models

MERMAID DIAGRAM SYNTAX RULES FOR FLOWCHARTS

When generating Mermaid flowchart diagrams, follow these strict rules:

1. Node IDs and Labels

DO:

• Use alphanumeric characters and underscores for node IDs: NodeID, Node_1, MyComponent
• Wrap labels in square brackets: NodeID[Label Text]
• Use simple, descriptive text in labels
• Replace special characters with words or hyphens:
  • : → - or and
  • & → and
  • / → or or -
  • % → percent
  • # → No or Number

DON’T:

• Use special characters in node IDs: @, !, #, $, %, ^, *, (, ), [, ]
• Use quotes inside labels: [Show "text"] ❌
• Use parentheses in decision node text: {Text (details)} ❌
• Use colons in labels unnecessarily: [Label: Details] ❌

2. Subgraph Declarations

DO:

• Use the format: subgraph ID["Display Label"]
• Use underscores in IDs: subgraph My_Flow["My Flow"]
• Put complex text in the display label (quoted string)

Example:

DON’T:

• Use spaces in subgraph IDs: subgraph My Flow ❌
• Use parentheses: subgraph Flow (Details) ❌
• Use special characters: subgraph Flow & Logic ❌

3. Arrow Types and Edge Labels

DO:

• Solid arrow: -->
• Dotted arrow: -.-> (ONE dash, dot, arrow)
• Labeled edge: -->|Label Text|
• Keep edge labels simple and concise
• Replace special characters in edge labels

Example:

DON’T:

• Use three dashes for dotted: --.-> ❌
• Use complex labels with: ;, :, ", (, ), =
• Example BAD: -->|Set-Cookie: token=123; HttpOnly| ❌
• Example GOOD: -->|Set HttpOnly Cookie| ✓

4. Node Shapes

DO:

• Rectangle: [Text]
• Decision (simple text only): {Simple Question?}
• Rounded: (Text)
• Stadium: ([Text])

DON’T:

• Put complex text in decision nodes
• BAD: {Build App (ng build --prod)} ❌
• GOOD: [Build Application] or {Build Complete?} ✓

5. Direction and Layout

DO:

Available:

• TD or TB - Top to bottom
• BT - Bottom to top
• LR - Left to right
• RL - Right to left

6. Styling

DO:

DON’T:

• Use invalid CSS properties
• Use special characters in style definitions

7. Common Patterns to Avoid

Invalid Patterns:

Valid Replacements:

Quick Reference Checklist

Before finalizing any Mermaid diagram, verify:

• No |\1| or similar escape sequences in edges
• All subgraphs use ID["Label"] format
• No parentheses in subgraph IDs or decision node labels
• Dotted arrows use -.-> (not --.-> or -..-)
• No quotes inside node labels
• No colons, semicolons, or special chars in critical positions
• Node IDs are alphanumeric with underscores only
• Edge labels are simple and descriptive
• Decision nodes {...} have minimal text
• Complex descriptions use rectangular nodes [...]

Testing Mermaid Diagrams

Recommended Tools:

1. Mermaid Live Editor - Test diagrams before committing
2. VS Code Mermaid Preview extensions
3. Hugo’s built-in mermaid rendering

Test Process:

1. Write diagram
2. Preview in Mermaid Live Editor
3. Check for parse errors
4. Simplify labels if errors occur
5. Use proper escaping only when necessary

Summary of Best Practices

1. Keep It Simple: Simpler labels = fewer errors
2. Use IDs Wisely: Alphanumeric + underscores only
3. Quote Display Labels: Use ["Display Text"] for subgraphs
4. Replace Special Chars: Convert to words or hyphens
5. Test Before Commit: Always preview diagrams
6. One Dash for Dotted: -.-> not --.->
7. No Quotes in Labels: Remove or replace
8. Decision Nodes: Keep text minimal
9. Edge Labels: Descriptive but simple
10. Consistency: Follow the same patterns throughout

Examples of Correct Diagrams

Example 1: Simple Flowchart

Example 2: With Subgraphs

Example 3: Mix of Arrows

Document Version: 1.0
Date: February 15, 2026
Total Errors Fixed: 100+
Files Affected: 15 files in angular-system-design-2026-guide/