Add under-anything knowledge dashboard
This commit is contained in:
qiaoxinjiu
@@ -0,0 +1,268 @@
|
||||
# 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
|
||||
|
||||
```typescript
|
||||
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
|
||||
|
||||
```typescript
|
||||
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
|
||||
Reference in New Issue
Block a user