# Visual Architecture Explainer

> Use when the user wants a visual, beautifully explained architecture document for any system they've built, combining mermaid.js diagrams, visual companion mockups, dark-themed HTML, and narrative walkthroughs. Best for when they say 'I can't understand what I built, explain it visually', 'create a visual architecture doc', or 'make me a diagram of my system'.

- Skill: `ajeesh25353646/visual-architecture-explainer` (Agent Skill, multi-file: 7 files)
- Install (CLI): `npx skillmds@latest add ajeesh25353646/visual-architecture-explainer`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ajeesh25353646/visual-architecture-explainer/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: Ajeesh25353646 (https://skillmd.com/u/ajeesh25353646)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/ajeesh25353646/visual-architecture-explainer

---


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

<SUBAGENT-STOP>
If you were dispatched as a subagent, you are NOT running this skill. You are executing a specific task within it. Follow your task prompt.
</SUBAGENT-STOP>

---

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

```bash
# 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.

```bash
# 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:
```bash
# 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:

```html
<!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:
```javascript
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.