# nicobailon/visual-explainer architecture

> Architecture diagram of the GitHub repository nicobailon/visual-explainer, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nicobailon/visual-explainer
- Repository: https://github.com/nicobailon/visual-explainer

## Overview

This repository is a Claude Code / agent plugin that produces visually rendered explanations from text prompts and terminal output. It is not an application server or frontend app; it is a packaging and prompt-authoring repo for an agent skill named `visual-explainer`.

#### Architectural shape

At a high level, the repo has three layers:

1. **Plugin distribution layer**
   - Root-level plugin metadata in `.claude-plugin/`
   - Marketplace and install plumbing for Claude Code / Pi / Codex
   - A root `package.json` and `install-pi.sh` for packaging and installation workflows

2. **Skill implementation layer**
   - Everything under `plugins/visual-explainer/`
   - This is the actual agent skill: instructions, commands, references, templates, and sharing script

3. **Output delivery layer**
   - The skill generates self-contained HTML files
   - Those files are meant to be opened locally in a browser or deployed to Vercel for sharing

#### Main subsystems

##### 1) Plugin metadata and packaging
Files:
- `.claude-plugin/plugin.json`
- `.claude-plugin/marketplace.json`
- `plugins/visual-explainer/.claude-plugin/plugin.json`

This layer defines the plugin identity and how it is exposed to a marketplace or agent runtime. The root `.claude-plugin` directory appears to describe the repo as a plugin catalog entry, while the plugin-specific manifest under `plugins/visual-explainer/.claude-plugin` defines the actual skill package.

This is the boundary between the repository and the consuming agent platform.

##### 2) Skill behavior and orchestration
File:
- `plugins/visual-explainer/SKILL.md`

This is the core operating manual for the agent skill. It likely explains:
- when to choose HTML, Mermaid, tables, or slide decks
- how to interpret prompts
- how to structure outputs for readability
- design principles for generated pages

This file is the central control plane for the agent’s behavior. The commands and templates are supporting assets; the skill document is what tells the model how to use them.

##### 3) Slash command entry points
Directory:
- `plugins/visual-explainer/commands/`

Commands:
- `diff-review.md`
- `fact-check.md`
- `generate-slides.md`
- `generate-visual-plan.md`
- `generate-web-diagram.md`
- `plan-review.md`
- `project-recap.md`
- `share.md`

These are task-specific prompts or workflows. They are the user-facing functional entry points. Each command represents a distinct use case:
- architecture or system diagram generation
- visual plan generation
- slide deck generation
- code diff review
- plan/code comparison
- project recap/context snapshot
- document fact-checking
- sharing a generated artifact

Architecturally, these commands are the routing layer: they decide which kind of output should be generated and what format it should take.

##### 4) Reference knowledge base for generation
Directory:
- `plugins/visual-explainer/references/`

Files:
- `css-patterns.md`
- `libraries.md`
- `responsive-nav.md`
- `slide-patterns.md`

These are supporting design and implementation references the agent reads while generating content. They act like a constrained knowledge base:
- CSS/layout patterns for polished pages
- supported libraries such as Mermaid or Chart.js
- navigation patterns for long documents
- slide composition patterns for deck mode

This layer is important because the skill is not just “write HTML”; it is “write HTML that follows preferred visual and interaction patterns.”

##### 5) Presentation templates
Directory:
- `plugins/visual-explainer/templates/`

Files:
- `architecture.html`
- `data-table.html`
- `mermaid-flowchart.html`
- `slide-deck.html`

These are canonical output templates. They define the visual system for generated artifacts:
- architecture pages for system overviews
- table layouts for structured comparisons
- Mermaid-based diagrams for flowcharts
- slide deck layout for presentation-style output

These templates are the primary rendering boundary. The agent maps a task to one of these output shapes and fills in content.

##### 6) Sharing/deployment script
File:
- `plugins/visual-explainer/scripts/share.sh`

This script provides the distribution path for a finished artifact. The README says the share workflow deploys the HTML page to Vercel and returns a live URL. That makes sharing a separate concern from generation.

This is a distinct operational boundary:
- generation happens locally
- sharing publishes the generated static HTML externally

#### Data flow

The repository’s end-to-end flow is:

1. **User invokes a command or asks the agent for a visual explanation**
   - Examples: diagram a flow, review a diff, compare plan vs code

2. **Agent consults skill instructions and references**
   - `SKILL.md`
   - command prompt file
   - supporting references

3. **Agent selects an output form**
   - Mermaid diagram
   - HTML architecture page
   - data table
   - slide deck

4. **Agent renders a self-contained HTML artifact**
   - output is saved locally under `~/.agent/diagrams/filename.html` according to the README
   - no build step is required

5. **Browser opens the artifact**
   - the local HTML becomes the primary presentation surface

6. **Optional sharing path**
   - `share.sh` deploys the generated page to Vercel
   - a public URL is returned for collaboration

#### Important boundaries

##### Prompting vs rendering
The repo does not contain an application runtime that renders pages dynamically. Instead, it separates:
- **instructions and templates** for the agent
- **static HTML output** for the browser

That means the “engine” is mostly the model + templates, not JavaScript application logic.

##### Local artifact vs public share
Generated pages are first-class local files. Public sharing is optional and externalized through Vercel. That keeps the core flow offline/local while enabling collaboration as a separate step.

##### Generic generation vs specialized workflows
The command files split general visual generation into specific workflows:
- diagrams
- plans
- reviews
- recaps
- slides
- fact checking

This reduces ambiguity for the agent and makes each output type more predictable.

##### Markdown instructions vs HTML templates
The repo uses Markdown for agent instructions and HTML for rendered presentation. Markdown drives the model; HTML is the deliverable.

#### Technologies and runtime implications

The architecture is lightweight and static:
- **Markdown** for skill and command definitions
- **HTML/CSS** for output templates
- **Mermaid** for diagrams
- likely **Chart.js** for charts, as hinted in the README references
- **browser** as the rendering runtime
- **Vercel** as the optional hosting target
- shell scripting for installation/sharing

There is no evidence of a backend service, database, or long-running process in this repo.

#### How to draw this repository as an architecture diagram

The most accurate diagram would show:

- A top-level **agent platform / Claude Code** box
- A **plugin package** boundary containing:
  - plugin metadata
  - skill instructions
  - command prompts
  - reference docs
  - templates
  - share script
- A **local output** box for generated HTML files
- A **browser** box that renders the HTML
- An optional **Vercel** box for public sharing

The key flows are:
- user prompt → command/skill instructions → template selection → HTML artifact
- HTML artifact → browser
- HTML artifact → share script → Vercel → public URL

#### Repository intent

The repo is fundamentally a **visual-output framework for agents**. It packages the knowledge and presentation patterns needed to transform plain-text reasoning into polished, browser-rendered artifacts. The main architectural concern is not business logic, but controlling presentation quality, choosing the right output format, and making the result easy to view or share.

Main entry points: [`plugins/visual-explainer/SKILL.md`](https://github.com/nicobailon/visual-explainer/blob/HEAD/plugins/visual-explainer/SKILL.md) (Skill guide), [`plugins/visual-explainer/commands`](https://github.com/nicobailon/visual-explainer/tree/HEAD/plugins/visual-explainer/commands) (Commands), [`plugins/visual-explainer/templates`](https://github.com/nicobailon/visual-explainer/tree/HEAD/plugins/visual-explainer/templates) (Templates), [`plugins/visual-explainer/scripts/share.sh`](https://github.com/nicobailon/visual-explainer/blob/HEAD/plugins/visual-explainer/scripts/share.sh) (Share script)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph "Plugin distribution"
  root_plugin_json["Plugin manifest<br/>plugin metadata<br/>[plugin.json]"]
  marketplace_json["Marketplace<br/>plugin catalog<br/>[marketplace.json]"]
  package_json["Package config<br/>package metadata<br/>[package.json]"]
  install_script["Install script<br/>shell installer<br/>[install-pi.sh]"]
end

subgraph "Visual explainer skill"
  skill_manifest["Skill manifest<br/>plugin metadata<br/>[plugin.json]"]
  skill_md["Skill guide<br/>agent instructions<br/>[SKILL.md]"]
  commands["Commands<br/>prompt entrypoints"]
  references["References<br/>knowledge base"]
  templates["Templates"]
  share_sh["Share script<br/>publish script<br/>[share.sh]"]
end

subgraph "Output delivery"
  local_html["HTML artifact<br/>generated output"]
  browser(("Browser<br/>viewer"))
  vercel["Vercel<br/>hosting target"]
end

claude_platform(("Claude Code<br/>agent runtime"))

claude_platform -->|"loads"| root_plugin_json
claude_platform -->|"loads"| skill_manifest
root_plugin_json -->|"catalogs"| marketplace_json
package_json -->|"packages"| install_script
skill_manifest -->|"governs"| skill_md
skill_md -->|"routes"| commands
skill_md -->|"consults"| references
commands -->|"selects"| templates
references -->|"informs"| templates
templates -->|"renders"| local_html
local_html -->|"opens"| browser
commands -->|"invokes"| share_sh
share_sh -->|"deploys"| vercel
local_html -->|"publishes"| share_sh
claude_platform -.->|"installs"| install_script

click root_plugin_json "https://github.com/nicobailon/visual-explainer/blob/main/.claude-plugin/plugin.json"
click marketplace_json "https://github.com/nicobailon/visual-explainer/blob/main/.claude-plugin/marketplace.json"
click package_json "https://github.com/nicobailon/visual-explainer/blob/main/package.json"
click install_script "https://github.com/nicobailon/visual-explainer/blob/main/install-pi.sh"
click skill_manifest "https://github.com/nicobailon/visual-explainer/blob/main/plugins/visual-explainer/.claude-plugin/plugin.json"
click skill_md "https://github.com/nicobailon/visual-explainer/blob/main/plugins/visual-explainer/SKILL.md"
click commands "https://github.com/nicobailon/visual-explainer/tree/main/plugins/visual-explainer/commands"
click references "https://github.com/nicobailon/visual-explainer/tree/main/plugins/visual-explainer/references"
click templates "https://github.com/nicobailon/visual-explainer/tree/main/plugins/visual-explainer/templates"
click share_sh "https://github.com/nicobailon/visual-explainer/blob/main/plugins/visual-explainer/scripts/share.sh"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class root_plugin_json,marketplace_json,package_json,install_script toneBlue
class skill_manifest,skill_md,commands,references,templates,share_sh toneAmber
class local_html,browser,vercel toneMint
class claude_platform toneNeutral
```

## Components

### Plugin distribution

Repository-level packaging and marketplace entrypoints.

- [Plugin manifest](https://github.com/nicobailon/visual-explainer/blob/HEAD/.claude-plugin/plugin.json): plugin metadata · Repository-level plugin metadata for marketplace/runtime exposure. · `.claude-plugin/plugin.json`
- [Marketplace](https://github.com/nicobailon/visual-explainer/blob/HEAD/.claude-plugin/marketplace.json): plugin catalog · Marketplace plumbing for install and discovery. · `.claude-plugin/marketplace.json`
- [Package config](https://github.com/nicobailon/visual-explainer/blob/HEAD/package.json): package metadata · Root packaging and dependency metadata. · `package.json`
- [Install script](https://github.com/nicobailon/visual-explainer/blob/HEAD/install-pi.sh): shell installer · Root installation workflow for Pi or related packaging. · `install-pi.sh`

### Visual explainer skill

The packaged agent skill, prompts, references, and templates.

- [Skill manifest](https://github.com/nicobailon/visual-explainer/blob/HEAD/plugins/visual-explainer/.claude-plugin/plugin.json): plugin metadata · Skill-specific plugin metadata under the visual-explainer package. · `plugins/visual-explainer/.claude-plugin/plugin.json`
- [Skill guide](https://github.com/nicobailon/visual-explainer/blob/HEAD/plugins/visual-explainer/SKILL.md): agent instructions · Core operating manual that governs how the skill chooses and structures outputs. · `plugins/visual-explainer/SKILL.md`
- [Commands](https://github.com/nicobailon/visual-explainer/tree/HEAD/plugins/visual-explainer/commands): prompt entrypoints · Task-specific slash-command workflows for visual generation, review, recap, and sharing. · `plugins/visual-explainer/commands`
- [References](https://github.com/nicobailon/visual-explainer/tree/HEAD/plugins/visual-explainer/references): knowledge base · Supporting guidance for CSS patterns, libraries, navigation, and slide composition. · `plugins/visual-explainer/references`
- [Templates](https://github.com/nicobailon/visual-explainer/tree/HEAD/plugins/visual-explainer/templates): render templates · Canonical HTML templates for diagrams, tables, architecture pages, and slide decks. · `plugins/visual-explainer/templates`
- [Share script](https://github.com/nicobailon/visual-explainer/blob/HEAD/plugins/visual-explainer/scripts/share.sh): publish script · Deploys a generated artifact for sharing. · `plugins/visual-explainer/scripts/share.sh`

### Output delivery

Local HTML artifacts and optional publishing path.

- **HTML artifact**: generated output · Self-contained local HTML file produced by the skill.
- **Browser**: viewer · Local browser that renders the generated HTML artifact.
- **Vercel**: hosting target · Optional public hosting target for shared HTML artifacts.

### Other components

- **Claude Code**: agent runtime · Consuming agent platform that loads the plugin and executes commands.

## Connections

- Claude Code → Plugin manifest: loads · Platform discovers the repository plugin entry.
- Claude Code → Skill manifest: loads · Platform loads the skill package metadata.
- Plugin manifest → Marketplace: catalogs · Root plugin metadata is paired with marketplace configuration.
- Package config → Install script: packages · Package metadata supports installation and distribution workflows.
- Skill manifest → Skill guide: governs · Skill metadata leads into the primary operating instructions.
- Skill guide → Commands: routes · Skill guide directs task-specific command workflows.
- Skill guide → References: consults · Skill guide uses supporting references for output quality and patterns.
- Commands → Templates: selects · Command prompts map tasks to output templates.
- References → Templates: informs · Reference docs shape the visual patterns used by templates.
- Templates → HTML artifact: renders · Templates are filled to produce a self-contained HTML artifact.
- HTML artifact → Browser: opens · Generated HTML is viewed locally in a browser.
- Commands → Share script: invokes · Share workflow triggers the publishing script.
- Share script → Vercel: deploys · Sharing publishes the artifact to Vercel.
- HTML artifact → Share script: publishes · The generated artifact is handed to the sharing workflow.
- Claude Code → Install script: installs · The consuming environment may use the install workflow.
