From excalidraw
Automatically analyzes codebases to generate zero-config architecture diagrams by detecting project type, tech stack, and structure. For repo overviews without custom specs.
npx claudepluginhub edwingao28/excalidraw-toolkit --plugin excalidrawThis skill uses the workspace's default tool permissions.
Analyze ANY codebase and generate a complete architecture diagram automatically.
Scans codebases to auto-generate Mermaid diagrams like ER for DB schemas/models, sequence for API routes, architecture for services, and state diagrams from file structure.
Scans a codebase path to auto-generate 2-4 relevant D2 diagrams like ER for DB schemas, sequences for API routes, architecture for services, and class diagrams.
Generates Mermaid flowcharts visualizing high-level codebase component relationships. Use for onboarding, PR reviews, and understanding system structure.
Share bugs, ideas, or general feedback.
Analyze ANY codebase and generate a complete architecture diagram automatically. No description needed — you read the code and figure out what to draw.
Before starting analysis, verify the Excalidraw MCP server is available:
mcp__excalidraw__read_diagram_guide()
If this fails, tell the user:
"The Excalidraw MCP server isn't running. Start the canvas server first:
docker run -d -p 3000:3000 ghcr.io/yctimlin/mcp_excalidraw-canvas:latestThen open http://localhost:3000 and try again."
To prevent context window blowout on large codebases, follow these hard limits:
| Operation | Limit |
|---|---|
| Grep results per pattern | 20 matches (use head_limit) |
| Files read per component | 5 files |
| Tool calls in Phase 2 | 15 |
| Tool calls in Phase 3 | 10 |
If limits are exceeded, proceed with partial results and note gaps to the user.
Run these file checks to identify the project type and tech stack:
package.json, pyproject.toml, go.mod, Cargo.toml, pom.xml, Gemfile, composer.json, mix.exs, Makefile, Dockerfile, docker-compose.yml, *.tfls the root and first-level subdirectories to identify the layout patternworkspaces in package.json, lerna.json, pnpm-workspace.yaml, multiple go.mod files, packages/ or apps/ directoriesDockerfile files, docker-compose.yml with 3+ servicesnext.config.*, src/app/, src/pages/routes/, controllers/, middleware/@nestjs/core in package.jsonmanage.py, wsgi.py, app.py, main.py with uvicornsrc/main/java/, application.propertiescmd/, internal/, pkg/src/main.rs, src/lib.rsGemfile + config/routes.rbartisan, app/Http/mix.exs + lib/*_web/Output: A mental model of the project type, primary language, and framework.
Monorepo handling: If monorepo detected, scope analysis to the top-level package structure first. Show one box per package/app. Offer to drill into specific packages on request.
Based on project type, identify architectural components. Max 15 tool calls.
*.tsx, *.jsx, *.vue, *.svelte in src/, app/, pages/ (head_limit: 20)router\.(get|post|put|delete), @(Get|Post|Put|Delete), @app\.route, HandleFunc (head_limit: 20)prisma/schema.prisma, models.py, *.entity.ts, migrations/, @Entity, db.Model (head_limit: 20)axios, fetch(, requests\., http\.NewRequest (head_limit: 20)amqp, kafka, bull, celery, SQS, pubsub (head_limit: 10)redis, memcached, cache in imports (head_limit: 10)passport, jwt, oauth, @Auth, middleware.*auth (head_limit: 10)docker-compose.yml service definitions*.tf for resource " blocks (head_limit: 20)**/k8s/*.yaml or **/manifests/*.yaml (head_limit: 20)main, bin, exports in package configOutput: A list of 4-12 components with names, types, and key file locations.
Determine how components connect. Max 10 tool calls. Focus on entry points and their immediate dependencies -- don't trace every import.
Read entry point files -- For each major component, read the main/index file (max 5 files total). Look for:
Map connection types -- Categorize each connection:
REST/HTTP -- fetch/axios/requests callsSQL/ORM -- database queriesgRPC/RPC -- inter-service callsEvent/Queue -- pub/sub, message queuesImport -- direct module import (same codebase)Build edge list -- Directed edges: ComponentA --[protocol]--> ComponentB
If you can't determine connections reliably: Show components without arrows and note "connections could not be auto-detected from entry point analysis. Try: 'add connections between X and Y'."
Output: A list of directed edges with labels.
Before drawing, present a summary and ask for confirmation:
"I found N components and M connections in this codebase:
Components: [list with types] Connections: [list of edges]
Does this look right? Should I add, remove, or rename anything before generating the diagram?"
Wait for confirmation before proceeding. Incorporate any changes the user suggests.
Choose layout based on the architecture pattern detected:
| Pattern | Layout | Trigger |
|---|---|---|
| Request/response flow (most web apps) | Vertical flow (top→bottom) | Frontend + API + DB layers detected |
| Data pipeline / ETL | Horizontal pipeline (left→right) | Linear chain of transforms detected |
| Event-driven / microservices | Hub and spoke | Message broker/event bus detected |
| Monolith with modules | Vertical flow with zones | Single service, multiple internal modules |
Tiebreaking: Prefer the pattern with more detected components. Default to vertical flow.
Hybrid: If both request/response and event-driven patterns exist, use vertical flow with the event bus in the middle layer (not hub-and-spoke).
Follow the excalidraw skill's workflow:
mcp__excalidraw__clear_canvas() -- start freshmcp__excalidraw__get_canvas_screenshot() -- verify emptymcp__excalidraw__batch_create_elements(elements=[...]) -- all elements in ONE callmcp__excalidraw__set_viewport({ scrollToContent: true }) -- zoom to fitmcp__excalidraw__get_canvas_screenshot() -- verify resultupdate_element or delete_element + create_element. Max 2 rounds.Color by component role:
| Role | Background | Stroke |
|---|---|---|
| Frontend | #a5d8ff | #1971c2 |
| Backend/API | #d0bfff | #7048e8 |
| Database | #b2f2bb | #2f9e44 |
| External service | #ffc9c9 | #e03131 |
| Queue/Event | #fff3bf | #fab005 |
| Cache | #ffe8cc | #fd7e14 |
Label format: Each box should contain:
ComponentName
tech-stack
(key detail)
Example:
API Server
Express.js
/api/* routes
When more than 12 components are discovered:
services/auth/ → "Auth Service")| Situation | How to Handle |
|---|---|
| Empty or trivial repo (<5 files) | Generate a simple module diagram showing file relationships |
| Monorepo with many packages | Show package-level view first, offer drill-down per package |
| No clear architecture (scripts, notebooks) | Show file dependency graph instead |
| Can't detect connections | Show components without arrows, note it to user |
| User specifies a subdirectory | Scope analysis to that directory only |
| MCP server not running | Print setup instructions (see Prerequisite Check) |
| Context budget exceeded | Proceed with partial results, tell user what was skipped |
User verification prompt:
I found 6 components and 5 connections in this codebase:
Components:
- Next.js Frontend (pages/, components/) — Frontend
- API Routes (pages/api/) — Backend/API
- Prisma ORM (prisma/schema.prisma) — Database
- PostgreSQL (from DATABASE_URL in .env.example) — Database
- NextAuth (from imports in [...nextauth].ts) — Auth
- Stripe API (from stripe SDK imports) — External API
Connections:
- Frontend → API Routes (REST API)
- API Routes → Prisma ORM (Prisma queries)
- Prisma ORM → PostgreSQL (SQL)
- API Routes → NextAuth (auth middleware)
- API Routes → Stripe API (payment calls)
Does this look right?
Diagram layout: Vertical flow, 3 layers
┌─────────────────────────────────────────────┐
│ Frontend Layer │
│ ┌──────────────┐ ┌──────────────┐ │
│ │ Next.js App │ │ React │ │
│ │ pages/ │ │ components/ │ │
│ └──────┬───────┘ └──────────────┘ │
└─────────┼───────────────────────────────────┘
│ API calls
┌─────────┼───────────────────────────────────┐
│ API Layer │
│ ┌──────▼───────┐ ┌──────────────┐ │
│ │ API Routes │ │ NextAuth │ │
│ │ pages/api/ │──│ OAuth flow │ │
│ └──────┬───────┘ └──────────────┘ │
└─────────┼───────────────────────────────────┘
│ Prisma queries
┌─────────┼───────────────────────────────────┐
│ Data Layer │
│ ┌──────▼───────┐ ┌──────────────┐ │
│ │ PostgreSQL │ │ Stripe API │ │
│ │ via Prisma │ │ payments │ │
│ └──────────────┘ └──────────────┘ │
└─────────────────────────────────────────────┘