Fulfilled-Knowledge/Understand-Anything-main/docs/superpowers/specs/2026-03-14-understand-anything-design.md

Understand Anything — Design & Implementation Plan

Context

AI coding tools have made writing code easy, but understanding code remains hard. Junior developers, non-programmers (PMs, designers), and even experienced devs working in unfamiliar languages struggle to comprehend codebases they didn't write — or that AI wrote for them. The only entity that "understands" the code is the AI itself.

Understand Anything bridges this gap: an open-source tool that combines LLM intelligence with static analysis to produce an interactive, multi-persona dashboard for understanding any codebase. It runs as a Claude Code skill (leveraging the active session) and serves a rich web dashboard.

---

Architecture: Monorepo with Shared Core

understand-anything/
├── packages/
│   ├── core/              # Shared analysis engine
│   │   ├── analyzer/      # LLM + tree-sitter analysis
│   │   ├── graph/         # Knowledge graph builder & schema
│   │   ├── plugins/       # Plugin system for language analyzers
│   │   └── persistence/   # JSON read/write, staleness detection
│   ├── skill/             # Claude Code skill (5 commands)
│   └── dashboard/         # React + TypeScript multi-panel workspace
├── plugins/               # Built-in language analyzer plugins
│   └── tree-sitter/       # Tree-sitter based multi-language analyzer
├── docs/
│   └── plans/
├── package.json           # Monorepo root (pnpm workspaces)
├── tsconfig.json
└── .gitignore

Key decisions:

• Monorepo (pnpm workspaces) — skill and dashboard share the core analysis engine
• JSON interchange — knowledge graph is a JSON file, readable by both skill and dashboard
• Committable + auto-sync — graph persists in .understand-anything/, can be committed to git, auto-detects staleness via git diff

---

Knowledge Graph Schema

interface KnowledgeGraph {
  version: string;
  project: ProjectMeta;
  nodes: GraphNode[];
  edges: GraphEdge[];
  layers: Layer[];
  tour: TourStep[];
}

interface ProjectMeta {
  name: string;
  languages: string[];
  frameworks: string[];
  description: string;           // LLM-generated project summary
  analyzedAt: string;            // ISO timestamp
  gitCommitHash: string;         // For staleness detection
}

interface GraphNode {
  id: string;
  type: "file" | "function" | "class" | "module" | "concept";
  name: string;
  filePath?: string;
  lineRange?: [number, number];
  summary: string;               // Plain-English description
  tags: string[];                // Searchable tags
  complexity: "simple" | "moderate" | "complex";
  languageNotes?: string;        // Language-specific explanations
}

interface GraphEdge {
  source: string;
  target: string;
  type: EdgeType;
  direction: "forward" | "backward" | "bidirectional";
  description?: string;
  weight: number;                // 0-1 importance
}

type EdgeType =
  // Structural
  | "imports" | "exports" | "contains" | "inherits" | "implements"
  // Behavioral
  | "calls" | "subscribes" | "publishes" | "middleware"
  // Data flow
  | "reads_from" | "writes_to" | "transforms" | "validates"
  // Dependencies
  | "depends_on" | "tested_by" | "configures"
  // Semantic
  | "related" | "similar_to";

interface Layer {
  id: string;
  name: string;                  // e.g., "API Layer", "Data Layer"
  description: string;
  nodeIds: string[];
}

interface TourStep {
  order: number;
  title: string;
  description: string;           // Markdown explanation
  nodeIds: string[];             // Nodes to highlight
  languageLesson?: string;       // Optional language concept explanation
}

---

Dashboard: Multi-Panel Workspace (React + TypeScript)

┌─────────────────────────────────────────────────────────┐
│  🔍 Natural Language Search: "communication layer"      │
├──────────────────────┬──────────────────────────────────┤
│                      │                                  │
│   GRAPH VIEW         │   CODE VIEWER                    │
│   (React Flow)       │   (Monaco Editor, read-only)     │
│                      │                                  │
│   Interactive node   │   Source code + syntax highlight  │
│   graph. Click to    │   LLM annotations inline.        │
│   select. Search     │                                  │
│   highlights.        │                                  │
├──────────────────────┼──────────────────────────────────┤
│                      │                                  │
│   CHAT PANEL         │   LEARN PANEL                    │
│                      │                                  │
│   Context-aware Q&A  │   Tour mode + Contextual mode    │
│   about selected     │   Language lessons in context     │
│   nodes / project.   │   of YOUR code.                  │
│                      │                                  │
└──────────────────────┴──────────────────────────────────┘

Tech stack:

• React 18 + TypeScript + Vite
• React Flow — graph visualization (built for node graphs, better than raw D3 for this)
• Monaco Editor — code viewer with syntax highlighting (same as VS Code)
• TailwindCSS — styling
• Zustand — state management (lightweight, no boilerplate)

Persona modes:

• Non-technical: High-level concept nodes, code viewer hidden, learn panel expanded
• Junior dev: All panels, learn panel prominent, complexity indicators
• Experienced dev: Code viewer prominent, chat panel for deep dives

Natural language search:

• Searches against node tags, summary, and name fields
• Uses embedding similarity if available, falls back to keyword matching
• Highlights matching nodes in the graph, filters the list

---

Claude Code Skill Commands

Command	Description
/understand	Full analysis (or incremental update if graph exists) + open dashboard
/understand-chat "<query>"	In-terminal Q&A using the knowledge graph
/understand-diff	Analyze current PR/diff — explain changes, affected areas, risks
/understand-explain <path>	Deep-dive explanation of a specific file or function
/understand-onboard	Generate structured onboarding guide for new team members

LLM strategy:

• Inside Claude Code → uses the active Claude session (zero extra cost)
• Standalone dashboard → users provide Claude API key for chat features
• Graph browsing, search, and learn mode work offline (pre-generated data)

---

Persistence & Staleness Detection

.understand-anything/
├── knowledge-graph.json       # The full graph (committable)
├── meta.json                  # Analysis metadata
│   {
│     "lastAnalyzedAt": "2026-03-14T...",
│     "gitCommitHash": "abc123",
│     "version": "1.0.0",
│     "analyzedFiles": 47
│   }
├── cache/                     # Per-file analysis cache
│   ├── src__index.ts.json
│   └── src__auth__login.ts.json
└── tours/
    └── default-tour.json

Auto-sync flow:

1. Skill starts → reads meta.json → gets last analyzed commit hash
2. Runs git diff <last-hash>..HEAD --name-only → gets changed files
3. If no changes → serves existing graph
4. If changes → re-analyzes only changed files → merges into existing graph → updates meta

---

Plugin System

interface AnalyzerPlugin {
  name: string;
  languages: string[];
  analyzeFile(filePath: string, content: string): StructuralAnalysis;
  resolveImports(filePath: string, content: string): ImportResolution[];
  extractCallGraph?(filePath: string, content: string): CallGraphEntry[];
}

Day 1: tree-sitter plugin — uses node-tree-sitter with language grammars for:

• TypeScript/JavaScript, Python, Go, Java, Rust, C/C++
• Extracts: function/class boundaries, import/export statements, call sites
• Combined with LLM analysis for semantic understanding

Future: community plugins for language-specific deep analysis.

---

Implementation Phases

Phase 1: Foundation (MVP)

1. Project scaffolding — monorepo, TypeScript config, build setup
2. Core: Knowledge graph schema + JSON persistence
3. Core: LLM analysis engine (file-by-file analysis using prompts)
4. Core: tree-sitter integration for structural analysis
5. Skill: /understand command — analyze + persist graph
6. Dashboard: Basic React app that reads and renders the graph
7. Dashboard: Graph view with React Flow
8. Dashboard: Code viewer with Monaco Editor

Phase 2: Intelligence

9. Natural language search across graph nodes
10. Skill: /understand-chat — terminal Q&A
11. Dashboard: Chat panel with context-aware Q&A
12. Staleness detection + incremental updates
13. Layer auto-detection (group nodes into logical layers)

Phase 3: Learn Mode

14. Tour generation — guided project walkthrough
15. Contextual explanations — click-to-explain
16. Language-specific lessons in context of the user's code
17. Persona modes (non-technical / junior / experienced)

Phase 4: Advanced

18. Skill: /understand-diff — PR/diff analysis
19. Skill: /understand-explain — deep-dive on specific files
20. Skill: /understand-onboard — onboarding guide generation
21. Community plugin system
22. Embedding-based semantic search (optional enhancement)

---

Verification

How to test end-to-end:

1. Skill analysis: Run /understand on a sample project → verify .understand-anything/knowledge-graph.json is generated with correct schema
2. Incremental update: Modify a file → run /understand again → verify only the changed file is re-analyzed
3. Dashboard: Open http://localhost:5173 → verify graph renders, nodes are clickable, search works
4. Chat: Ask a question in the chat panel → verify it returns a relevant answer using the knowledge graph
5. Learn mode: Start the tour → verify it walks through the project step by step
6. Tree-sitter: Analyze a TypeScript file → verify function boundaries and import relationships match the actual code

Test projects to validate against:

• A small TypeScript project (the tool itself)
• A Python Flask/Django API
• A Go microservice
• A mixed-language monorepo