Visual Architecture Explainer

Create stunning, self-contained visual architecture documents that explain complex systems through interactive HTML, mermaid.js diagrams and narrative sections, all served through a self-contained Visual Companion browser (Node.js WebSocket server with live reload).

OUTPUT CONTRACT

Read before emitting your response.

Badge (Mandatory, First Line of Output)

🎨 Visual Arch | {N} diagrams | {N} pages | Format: {HTML/markdown/etc}

No other text on this line. One blank line after, then the output begins.

LAWS (Non-Negotiable)

LAW 1: Explore First, Diagram Second. Before writing any HTML or mermaid, explore the actual codebase: read files, check commits, run find/ls/git log. Architecture inferred from chat history alone is wrong. You must anchor every diagram in real file paths, real data, and real relationships.

This LAW exists because of a failure where a diagram showed modules that didn't exist in the actual codebase. The user had only described the intention, not what was actually built.

LAW 2: NO Inline Mermaid CDN. Load mermaid via <script src="https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.min.js">. Do NOT bundle or inline mermaid code. The CDN URL is known-good. Keep the script tag minimal.

LAW 3: Emojis and Special Chars BREAK Mermaid Labels. Mermaid's bracket-node syntax ([label]) DOES NOT support emoji characters (🔄, →, ▶, ✏️), HTML (<br/>), or special chars. Use double-quoted plain-text labels: ["scanner.py - profile snapshot"]. Never ["📡 scanner.py"].

CRITICAL: This is the #1 cause of mermaid rendering failures. The mermaid parser treats emoji byte sequences as parse errors and silently fails. If your mermaid block doesn't render, this is likely why.

LAW 4: Every Section Gets a Mermaid Diagram + Narrative. Never show a diagram without explaining it. Each section must follow: header → diagram → explanation cards. The explanation should call out specific file names, data flows, or relationships visible in the diagram.

LAW 5: Use Built-in Visual Companion for Delivery. The final output is always an HTML file served via the skill's built-in Visual Companion server (Node.js WebSocket server with live reload; scripts in scripts/). The user opens a URL in their browser. Text-based description of diagrams is prohibited. Show the architecture in the browser, do not describe it in text.

The server is embedded in this skill. Run bash scripts/start-server.sh --project-dir <dir> --host 0.0.0.0. No external skill dependency.

LAW 6: Progressive Disclosure. Start Big, Then Zoom. First section shows the ENTIRE system (high-level 3-layer architecture), then each subsequent section zooms into one component (data pipeline, dashboard tabs, feedback loop, etc.). Never jump into details without context.

LAW 7: Dark Theme Always. Use #0f172a background, #1e293b cards, #334155 borders. This matches the LinkedIn Profile Optimizer dashboard theme and provides consistent eye comfort. No light-themed visual docs.

LAW 8: Real Data in Diagrams. Every count, metric, and status shown in diagrams must come from the actual system. If the keyword gap shows "28 skills matched", that must be the real number from keyword_gap_data.json. No placeholder data in final output.

This LAW exists because of a failure during an architecture review where a stakeholder pointed out a "42% improvement" metric that didn't match the actual monitoring data. The diagram had to be redacted, and the review lost credibility.

LAW 9: Self-Correct After Each Mermaid Block. After writing a mermaid <div class="mermaid"> block, immediately verify: (a) no emoji chars inside [brackets], (b) no <br/> inside brackets, (c) no → or ▶ inside brackets. If any exist, fix before proceeding. A broken mermaid block renders as a blank rectangle with no error message and no clue what went wrong.

WORKFLOW

Stage 0: Pre-Flight (Explore and Parse)

Before writing any code, you MUST:

# 1. Check the project structure
ls [project-dir]
find [project-dir] -maxdepth 2 -name "*.py" | head -20
git log --oneline -20

# 2. Read key files to understand what was built
# For Python projects: read entry points, README, main files
# For any project: read config files, data files, test files

# 3. Run any existing analysis to get real data
# E.g., if there's a keyword gap analysis:
python3 [project-dir]/scripts/something.py 2>/dev/null

# 4. Collect real metrics for the stats section

If the project has a CLAUDE.md or README.md, read those FIRST. They contain the authoritative architecture description.

Stage 1: Structure the Document

Map out the visual doc sections before writing anything. A great architecture doc follows this structure:

Section 1: System Architecture (Big Picture -- 3-layer or component diagram)
Section 2: Data Pipeline (End-to-End Flow -- inputs to processing to outputs)
Section 3: Component Deep-Dive (tabs, features, or modules explained)
Section 4: Feedback Loops (if the system has measurement/improvement cycles)
Section 5: Live Stats (real data from the running system)
Section 6: How to Run (CLI commands in a visual timeline)

Each section = 1 mermaid flowchart + 2-4 explanation/narrative cards.

Stage 2: Start the Visual Companion (Built-in)

The skill provides its own bundled WebSocket-based Visual Companion server. No external dependencies.

# Resolve the skill directory automatically
SCRIPT_DIR="$(dirname "$(realpath "${BASH_SOURCE:-$0}")")"
# Or if running inline:
SKILL_DIR="/root/personal_agent/skills_created/visual-architecture-explainer"

bash "$SKILL_DIR/scripts/start-server.sh" \
  --project-dir "[project-dir]" \
  --host 0.0.0.0

If bash is not available or Node.js is required directly:

# The start-server.sh script handles the Node.js server.cjs internally.
# It uses nohup + disown for backgrounding, or --foreground for persistent terminals.

Capture the url and screen_dir from the JSON response. The server:

• Automatically serves the newest HTML file in screen_dir
• Live-reloads the browser when a new file is written
• Records user interactions (clicks, selections) to state_dir/events
• Auto-exits after 30 minutes of inactivity

Stage 3: Write Sections Iteratively

For each section:

1. Write the mermaid flowchart with the correct syntax (LAW 3: no emoji in brackets)
2. Write explanation cards calling out real files and data
3. Save to a new file in screen_dir (e.g., 01-architecture.html)
4. The Visual Companion auto-serves the latest file

Stage 4: Build the Single-Page Master Document

After all sections are validated individually, build full-architecture.html that combines everything:

<!DOCTYPE html>
<html>
<head>
  <title>System Architecture</title>
  <script src="https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.min.js"></script>
  <style>
    /* Dark theme: #0f172a bg, #1e293b cards, #334155 borders */
    /* Card pattern: .card { background: #0f172a; border: 1px solid #334155; border-radius: 8px; } */
    /* Split layouts: .split-2 { display: grid; grid-template-columns: 1fr 1fr; gap: 14px; } */
  </style>
</head>
<body>
  <!-- Header with title + badge row -->
  <!-- Each section: .section > .section-header + .section-body > .mermaid + cards -->
  <!-- Footer with stats -->
  <script>mermaid.initialize({ theme: 'dark', ... });</script>
</body>
</html>

The mermaid dark theme initialization that consistently works:

mermaid.initialize({
  theme: 'dark',
  themeVariables: {
    darkMode: true,
    background: '#0f172a',
    primaryColor: '#1e293b',
    primaryTextColor: '#e2e8f0',
    primaryBorderColor: '#334155',
    lineColor: '#3b82f6',
    secondaryColor: '#0f172a',
    tertiaryColor: '#1e293b',
    fontSize: '13px'
  }
});

Stage 5: Self-Review Before Presenting

[ ] Badge on line 1? ✅
[ ] All mermaid diagrams use quoted plain-text labels (no emoji inside brackets)?
[ ] Real data from the system shown, not placeholders?
[ ] Dark theme (#0f172a)?
[ ] Every section has both diagram + narrative?
[ ] All file paths mentioned actually exist?
[ ] No broken HTML (check for unclosed tags)?
[ ] Mermaid CDN loaded via jsdelivr?
[ ] Visual Companion started via skill's own `scripts/start-server.sh` (not brainstorming)?
[ ] Visual Companion URL provided for the user?

Stage 6: Present

Tell the user to open the Visual Companion URL. Walk them through the sections. Offer to save the final HTML to [project-dir]/linkedin_architecture.html or similar so they can access it without the server.