# kunalamin/visual-explainer architecture

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

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

## Overview

1. **Repository type**
   - This is not a traditional app; it is an **agent skill/plugin package**.
   - The repo ships prompt files, manifests, reference docs, HTML templates, and a small deploy script that together teach an AI agent how to generate visual explanations.

2. **Top-level packaging boundary**
   - `.claude-plugin/` contains the **marketplace-facing plugin metadata**.
   - `plugin.json` identifies the plugin, and `marketplace.json` registers it in the catalog.
   - This boundary is about distribution and discovery, not runtime behavior.

3. **Primary skill boundary**
   - `plugins/visual-explainer/` is the actual skill payload.
   - Its own `.claude-plugin/plugin.json` acts as the **skill manifest** for the plugin runtime.
   - Everything else in this folder is content the agent consumes to decide what to generate.

4. **Command entry points**
   - `commands/` contains the slash-command prompts, such as `generate-web-diagram`, `diff-review`, `plan-review`, `project-recap`, and `share`.
   - These are the main **user-facing orchestration endpoints**.
   - Each command steers the agent toward a particular output shape: diagram, review, recap, slide deck, or shareable page.

5. **Behavioral guidance layer**
   - `SKILL.md` defines the **core workflow and design principles** for the agent.
   - This file is the central behavioral contract: it explains how the skill should choose layouts, manage complexity, and present information visually.

6. **Reference knowledge layer**
   - `references/` contains reusable design and implementation guidance the agent reads before generating output.
   - The docs are organized by concern:
     - `css-patterns.md` for layout/theming/animation choices
     - `libraries.md` for supported visualization libraries like Mermaid or Chart.js
     - `responsive-nav.md` for long-form navigation patterns
     - `slide-patterns.md` for slide-deck structure and presentation patterns
   - This layer acts like a lightweight knowledge base for consistent output quality.

7. **Template rendering layer**
   - `templates/` contains self-contained HTML examples for the output formats:
     - `architecture.html`
     - `data-table.html`
     - `mermaid-flowchart.html`
     - `slide-deck.html`
   - These templates are the **presentation substrate** the agent adapts when generating final pages.
   - The repo’s architecture is intentionally browser-native: output is HTML, not a compiled app.

8. **Sharing/deployment path**
   - `scripts/share.sh` is the only executable helper in the repo.
   - It packages or deploys generated HTML to **Vercel** and returns a shareable URL.
   - This is the external publishing boundary for turning local output into a link.

9. **Execution flow**
   - A user invokes a command or directly asks the agent for a visualization/review.
   - The agent reads `SKILL.md`, the relevant command file, and supporting reference docs.
   - It then selects an HTML template or Mermaid-based approach, writes the result to `~/.agent/diagrams/...`, and opens it in a browser.
   - If sharing is requested, the script pushes the HTML to Vercel.

10. **Output model**
   - The system favors **static, self-contained HTML pages** with optional embedded Mermaid/visual libraries.
   - That means the main runtime dependencies are the **browser** and the **agent environment**, not a backend service or build pipeline.
   - The repo is therefore best diagrammed as a content-driven generator with a browser-rendered output stage.

11. **Supported host environments**
   - The README shows the same skill can be installed into Claude Code, Pi, and OpenAI Codex environments.
   - That matters architecturally because the repo is designed to be **portable across agent runtimes**, with command prompts and skill files copied into each host’s expected directories.

12. **Key architecture takeaway**
   - The repository is a **plugin distribution package** composed of:
     - metadata/manifests for discovery,
     - command prompts for entry points,
     - reference docs for generation policy,
     - HTML templates for rendering,
     - a share script for publication.
   - There is no monolithic application core; the “engine” is the agent runtime interpreting these files.

Main entry points: [`plugins/visual-explainer/SKILL.md`](https://github.com/kunalamin/visual-explainer/blob/main/plugins/visual-explainer/SKILL.md) (Skill guide), [`plugins/visual-explainer/commands/generate-web-diagram.md`](https://github.com/kunalamin/visual-explainer/blob/main/plugins/visual-explainer/commands/generate-web-diagram.md) (Generate diagram), [`plugins/visual-explainer/commands/generate-slides.md`](https://github.com/kunalamin/visual-explainer/blob/main/plugins/visual-explainer/commands/generate-slides.md) (Generate slides), [`plugins/visual-explainer/commands/generate-visual-plan.md`](https://github.com/kunalamin/visual-explainer/blob/main/plugins/visual-explainer/commands/generate-visual-plan.md) (Visual plan)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_distribution["Distribution"]
  node_node_marketplace["Marketplace<br/>plugin catalog entry<br/>[marketplace.json]"]
  node_node_root_plugin["Root manifest<br/>plugin metadata<br/>[plugin.json]"]
end

subgraph group_group_skill["Visual Explainer"]
  node_node_skill_manifest["Skill manifest<br/>skill metadata<br/>[plugin.json]"]
  node_node_skill_workflow["Skill guide<br/>behavior contract<br/>[SKILL.md]"]
end

subgraph group_group_content["Content layer"]
  node_node_cmd_generate["Generate diagram<br/>slash command"]
  node_node_cmd_slides["Generate slides<br/>slash command<br/>[generate-slides.md]"]
  node_node_cmd_plan["Visual plan<br/>slash command"]
  node_node_cmd_diff["Diff review<br/>slash command<br/>[diff-review.md]"]
  node_node_cmd_planreview["Plan review<br/>slash command<br/>[plan-review.md]"]
  node_node_cmd_recap["Project recap<br/>slash command<br/>[project-recap.md]"]
  node_node_cmd_share["Share<br/>publish command<br/>[share.md]"]
  node_node_cmd_fact["Fact check<br/>slash command<br/>[fact-check.md]"]
  node_node_ref_libs["Libraries<br/>reference docs<br/>[libraries.md]"]
  node_node_ref_css["CSS patterns<br/>reference docs<br/>[css-patterns.md]"]
  node_node_ref_nav["Responsive nav<br/>reference docs<br/>[responsive-nav.md]"]
  node_node_ref_slides["Slide patterns<br/>reference docs<br/>[slide-patterns.md]"]
  node_node_tpl_arch["Architecture HTML<br/>template<br/>[architecture.html]"]
  node_node_tpl_table["Data table<br/>template<br/>[data-table.html]"]
  node_node_tpl_mermaid["Mermaid flowchart<br/>template"]
  node_node_tpl_slides["Slide deck<br/>template<br/>[slide-deck.html]"]
  node_node_share_script["Share script<br/>deploy helper<br/>[share.sh]"]
end

node_node_marketplace -->|"registers"| node_node_root_plugin
node_node_root_plugin -->|"installs"| node_node_skill_manifest
node_node_skill_manifest -->|"defines"| node_node_skill_workflow
node_node_skill_workflow -->|"orients"| node_node_cmd_generate
node_node_skill_workflow -->|"orients"| node_node_cmd_slides
node_node_skill_workflow -->|"orients"| node_node_cmd_plan
node_node_skill_workflow -->|"orients"| node_node_cmd_diff
node_node_skill_workflow -->|"orients"| node_node_cmd_planreview
node_node_skill_workflow -->|"orients"| node_node_cmd_recap
node_node_skill_workflow -->|"orients"| node_node_cmd_fact
node_node_cmd_generate -->|"consults"| node_node_ref_libs
node_node_cmd_generate -->|"consults"| node_node_ref_css
node_node_cmd_slides -->|"consults"| node_node_ref_slides
node_node_cmd_plan -->|"consults"| node_node_ref_nav
node_node_cmd_generate -->|"renders"| node_node_tpl_arch
node_node_cmd_generate -->|"renders"| node_node_tpl_mermaid
node_node_cmd_slides -->|"renders"| node_node_tpl_slides
node_node_cmd_plan -->|"renders"| node_node_tpl_table
node_node_cmd_recap -->|"renders"| node_node_tpl_arch
node_node_cmd_share -->|"executes"| node_node_share_script
node_node_share_script -.->|"publishes"| node_node_tpl_arch

click node_node_marketplace "https://github.com/kunalamin/visual-explainer/blob/main/.claude-plugin/marketplace.json"
click node_node_root_plugin "https://github.com/kunalamin/visual-explainer/blob/main/.claude-plugin/plugin.json"
click node_node_skill_manifest "https://github.com/kunalamin/visual-explainer/blob/main/plugins/visual-explainer/.claude-plugin/plugin.json"
click node_node_skill_workflow "https://github.com/kunalamin/visual-explainer/blob/main/plugins/visual-explainer/SKILL.md"
click node_node_cmd_generate "https://github.com/kunalamin/visual-explainer/blob/main/plugins/visual-explainer/commands/generate-web-diagram.md"
click node_node_cmd_slides "https://github.com/kunalamin/visual-explainer/blob/main/plugins/visual-explainer/commands/generate-slides.md"
click node_node_cmd_plan "https://github.com/kunalamin/visual-explainer/blob/main/plugins/visual-explainer/commands/generate-visual-plan.md"
click node_node_cmd_diff "https://github.com/kunalamin/visual-explainer/blob/main/plugins/visual-explainer/commands/diff-review.md"
click node_node_cmd_planreview "https://github.com/kunalamin/visual-explainer/blob/main/plugins/visual-explainer/commands/plan-review.md"
click node_node_cmd_recap "https://github.com/kunalamin/visual-explainer/blob/main/plugins/visual-explainer/commands/project-recap.md"
click node_node_cmd_share "https://github.com/kunalamin/visual-explainer/blob/main/plugins/visual-explainer/commands/share.md"
click node_node_cmd_fact "https://github.com/kunalamin/visual-explainer/blob/main/plugins/visual-explainer/commands/fact-check.md"
click node_node_ref_libs "https://github.com/kunalamin/visual-explainer/blob/main/plugins/visual-explainer/references/libraries.md"
click node_node_ref_css "https://github.com/kunalamin/visual-explainer/blob/main/plugins/visual-explainer/references/css-patterns.md"
click node_node_ref_nav "https://github.com/kunalamin/visual-explainer/blob/main/plugins/visual-explainer/references/responsive-nav.md"
click node_node_ref_slides "https://github.com/kunalamin/visual-explainer/blob/main/plugins/visual-explainer/references/slide-patterns.md"
click node_node_tpl_arch "https://github.com/kunalamin/visual-explainer/blob/main/plugins/visual-explainer/templates/architecture.html"
click node_node_tpl_table "https://github.com/kunalamin/visual-explainer/blob/main/plugins/visual-explainer/templates/data-table.html"
click node_node_tpl_mermaid "https://github.com/kunalamin/visual-explainer/blob/main/plugins/visual-explainer/templates/mermaid-flowchart.html"
click node_node_tpl_slides "https://github.com/kunalamin/visual-explainer/blob/main/plugins/visual-explainer/templates/slide-deck.html"
click node_node_share_script "https://github.com/kunalamin/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 node_node_marketplace,node_node_root_plugin toneBlue
class node_node_skill_manifest,node_node_skill_workflow toneAmber
class node_node_cmd_generate,node_node_cmd_slides,node_node_cmd_plan,node_node_cmd_diff,node_node_cmd_planreview,node_node_cmd_recap,node_node_cmd_share,node_node_cmd_fact,node_node_ref_libs,node_node_ref_css,node_node_ref_nav,node_node_ref_slides,node_node_tpl_arch,node_node_tpl_table,node_node_tpl_mermaid,node_node_tpl_slides,node_node_share_script toneMint
```

## Components

### Distribution

Marketplace-facing plugin metadata and package boundary.

- [Marketplace](https://github.com/kunalamin/visual-explainer/blob/main/.claude-plugin/marketplace.json): plugin catalog entry · Registers the plugin for discovery and installation. · `.claude-plugin/marketplace.json`
- [Root manifest](https://github.com/kunalamin/visual-explainer/blob/main/.claude-plugin/plugin.json): plugin metadata · Top-level plugin identity and distribution metadata. · `.claude-plugin/plugin.json`

### Visual Explainer

Primary skill payload consumed by the agent runtime.

- [Skill manifest](https://github.com/kunalamin/visual-explainer/blob/main/plugins/visual-explainer/.claude-plugin/plugin.json): skill metadata · Plugin manifest for the visual explainer skill runtime. · `plugins/visual-explainer/.claude-plugin/plugin.json`
- [Skill guide](https://github.com/kunalamin/visual-explainer/blob/main/plugins/visual-explainer/SKILL.md): behavior contract · Core workflow, principles, and generation rules for the agent. · `plugins/visual-explainer/SKILL.md`

### Content layer

Commands, guidance, references, templates, and publishing helper.

- [Generate diagram](https://github.com/kunalamin/visual-explainer/blob/main/plugins/visual-explainer/commands/generate-web-diagram.md): slash command · Primary command for producing web diagrams. · `plugins/visual-explainer/commands/generate-web-diagram.md`
- [Generate slides](https://github.com/kunalamin/visual-explainer/blob/main/plugins/visual-explainer/commands/generate-slides.md): slash command · Command for slide-deck output. · `plugins/visual-explainer/commands/generate-slides.md`
- [Visual plan](https://github.com/kunalamin/visual-explainer/blob/main/plugins/visual-explainer/commands/generate-visual-plan.md): slash command · Command for planning visual structure and output shape. · `plugins/visual-explainer/commands/generate-visual-plan.md`
- [Diff review](https://github.com/kunalamin/visual-explainer/blob/main/plugins/visual-explainer/commands/diff-review.md): slash command · Command for reviewing changes and differences visually. · `plugins/visual-explainer/commands/diff-review.md`
- [Plan review](https://github.com/kunalamin/visual-explainer/blob/main/plugins/visual-explainer/commands/plan-review.md): slash command · Command for reviewing plans and proposals. · `plugins/visual-explainer/commands/plan-review.md`
- [Project recap](https://github.com/kunalamin/visual-explainer/blob/main/plugins/visual-explainer/commands/project-recap.md): slash command · Command for summarizing a project into a visual recap. · `plugins/visual-explainer/commands/project-recap.md`
- [Share](https://github.com/kunalamin/visual-explainer/blob/main/plugins/visual-explainer/commands/share.md): publish command · Command that triggers packaging or publication of generated output. · `plugins/visual-explainer/commands/share.md`
- [Fact check](https://github.com/kunalamin/visual-explainer/blob/main/plugins/visual-explainer/commands/fact-check.md): slash command · Command for validating claims and factual content. · `plugins/visual-explainer/commands/fact-check.md`
- [Libraries](https://github.com/kunalamin/visual-explainer/blob/main/plugins/visual-explainer/references/libraries.md): reference docs · Supported visualization libraries and when to use them. · `plugins/visual-explainer/references/libraries.md`
- [CSS patterns](https://github.com/kunalamin/visual-explainer/blob/main/plugins/visual-explainer/references/css-patterns.md): reference docs · Layout, theming, and animation guidance. · `plugins/visual-explainer/references/css-patterns.md`
- [Responsive nav](https://github.com/kunalamin/visual-explainer/blob/main/plugins/visual-explainer/references/responsive-nav.md): reference docs · Patterns for long-form navigation and page structure. · `plugins/visual-explainer/references/responsive-nav.md`
- [Slide patterns](https://github.com/kunalamin/visual-explainer/blob/main/plugins/visual-explainer/references/slide-patterns.md): reference docs · Presentation structure guidance for slide decks. · `plugins/visual-explainer/references/slide-patterns.md`
- [Architecture HTML](https://github.com/kunalamin/visual-explainer/blob/main/plugins/visual-explainer/templates/architecture.html): template · Browser-native template for architecture visualizations. · `plugins/visual-explainer/templates/architecture.html`
- [Data table](https://github.com/kunalamin/visual-explainer/blob/main/plugins/visual-explainer/templates/data-table.html): template · Template for tabular or structured outputs. · `plugins/visual-explainer/templates/data-table.html`
- [Mermaid flowchart](https://github.com/kunalamin/visual-explainer/blob/main/plugins/visual-explainer/templates/mermaid-flowchart.html): template · Template for Mermaid-based diagrams. · `plugins/visual-explainer/templates/mermaid-flowchart.html`
- [Slide deck](https://github.com/kunalamin/visual-explainer/blob/main/plugins/visual-explainer/templates/slide-deck.html): template · Template for slide-based presentations. · `plugins/visual-explainer/templates/slide-deck.html`
- [Share script](https://github.com/kunalamin/visual-explainer/blob/main/plugins/visual-explainer/scripts/share.sh): deploy helper · Packages or deploys generated HTML to Vercel and returns a shareable link. · `plugins/visual-explainer/scripts/share.sh`

## Connections

- Marketplace → Root manifest: registers · Catalog entry points to the plugin package metadata.
- Root manifest → Skill manifest: installs · Distribution boundary delivers the skill payload.
- Skill manifest → Skill guide: defines · Skill metadata anchors the behavioral contract.
- Skill guide → Generate diagram: orients · Core guidance shapes the main diagram-generation command.
- Skill guide → Generate slides: orients · Core guidance shapes slide generation.
- Skill guide → Visual plan: orients · Core guidance shapes visual planning.
- Skill guide → Diff review: orients · Core guidance shapes review workflows.
- Skill guide → Plan review: orients · Core guidance shapes plan review.
- Skill guide → Project recap: orients · Core guidance shapes recap output.
- Skill guide → Fact check: orients · Core guidance shapes factual validation.
- Generate diagram → Libraries: consults · Commands rely on supported library guidance.
- Generate diagram → CSS patterns: consults · Commands use presentation and styling guidance.
- Generate slides → Slide patterns: consults · Slide generation uses slide-specific patterns.
- Visual plan → Responsive nav: consults · Planning uses navigation and structure patterns.
- Generate diagram → Architecture HTML: renders · Primary diagram command adapts the architecture template.
- Generate diagram → Mermaid flowchart: renders · Can also produce Mermaid-based diagrams.
- Generate slides → Slide deck: renders · Slide command uses the slide deck template.
- Visual plan → Data table: renders · Planning output can use structured table presentation.
- Project recap → Architecture HTML: renders · Recap output can be browser-native HTML.
- Share → Share script: executes · Share command invokes the deployment helper.
- Share script → Architecture HTML: publishes · Deployment path packages generated HTML for sharing.