From skill-forge
Generate architecture diagrams, dependency maps, and system documentation directly from your codebase. Reads source files, traces dependencies, identifies boundaries, and outputs Mermaid/PlantUML/C4 diagrams. Use when asked to document architecture, visualize dependencies, generate system diagrams, create C4 models, map service boundaries, understand a codebase structure, or produce technical documentation from existing code.
How this skill is triggered — by the user, by Claude, or both
Slash command
/skill-forge:arch-from-codeThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Read the actual codebase. Generate accurate architecture diagrams. No guessing, no outdated docs — diagrams that reflect what the code ACTUALLY does right now.
Read the actual codebase. Generate accurate architecture diagrams. No guessing, no outdated docs — diagrams that reflect what the code ACTUALLY does right now.
# Step 1: Identify the codebase structure
find . -name "*.ts" -o -name "*.py" -o -name "*.go" | head -50
# Or: list top-level directories
ls -la src/ app/ lib/ services/ packages/
# Step 2: Run this skill's analysis process (below)
# Step 3: Output Mermaid diagram
# Package manager = tech stack signal
ls package.json pyproject.toml go.mod Cargo.toml pom.xml *.csproj 2>/dev/null
# Entry points
ls src/index.* src/main.* app/main.* cmd/main.* 2>/dev/null
# Service boundaries (microservices)
ls -d services/* apps/* packages/* 2>/dev/null
# Configuration reveals integrations
cat .env.example docker-compose.yml 2>/dev/null | grep -i "host\|url\|port\|database\|redis\|queue"
For TypeScript/JavaScript:
# External dependencies = integration points
cat package.json | jq '.dependencies'
# Internal imports = module relationships
grep -r "from ['\"]\.\./" src/ --include="*.ts" | sed 's/.*from ['\''\"]\(.*\)['\''\"]/\1/' | sort | uniq -c | sort -rn
For Python:
cat requirements.txt pyproject.toml | grep -v "^#"
grep -r "^from\|^import" src/ --include="*.py" | grep -v __pycache__ | sort | uniq -c | sort -rn
For Go:
cat go.mod | grep -v "^//"
grep -r "import" . --include="*.go" | grep -v vendor | sort | uniq -c | sort -rn
Read top-level directories and classify:
| Directory Pattern | Likely Layer | Diagram Element |
|---|---|---|
api/, routes/, controllers/ | Presentation | API Gateway box |
services/, usecases/, domain/ | Business Logic | Core services |
repositories/, db/, models/ | Data Access | Database cylinder |
lib/, utils/, shared/ | Infrastructure | Shared component |
workers/, jobs/, queues/ | Background Processing | Async workers |
events/, pubsub/, messaging/ | Event Bus | Message broker |
System Context (C4 Level 1):
graph TB
User["User / Browser"]
System["Your System"]
DB["Database"]
Cache["Cache (Redis)"]
Queue["Message Queue"]
External["External APIs"]
User -->|"HTTP/WebSocket"| System
System -->|"SQL/ORM"| DB
System -->|"Get/Set"| Cache
System -->|"Publish"| Queue
System -->|"REST/gRPC"| External
Queue -->|"Consume"| System
Container Diagram (C4 Level 2):
graph TB
subgraph Frontend
Web["Web App (React/Next.js)"]
Mobile["Mobile App"]
end
subgraph Backend
API["API Server"]
Auth["Auth Service"]
Worker["Background Workers"]
end
subgraph Data
DB["PostgreSQL"]
Redis["Redis Cache"]
S3["Object Storage"]
end
Web --> API
Mobile --> API
API --> Auth
API --> DB
API --> Redis
Worker --> DB
Worker --> S3
Dependency Flow:
graph LR
subgraph Presentation
Routes["routes/"]
Controllers["controllers/"]
end
subgraph Business
Services["services/"]
Domain["domain/"]
end
subgraph Infrastructure
Repos["repositories/"]
Clients["clients/"]
end
Routes --> Controllers
Controllers --> Services
Services --> Domain
Services --> Repos
Services --> Clients
Repos --> DB[(Database)]
Clients --> ExtAPI[External API]
Output a structured architecture doc:
# Architecture Overview
## System Context
[Mermaid diagram here]
## Key Decisions
- **Framework:** [detected] because [inferred from config]
- **Database:** [detected from connection strings]
- **Caching:** [detected from Redis/Memcached usage]
- **Deployment:** [detected from Dockerfile/k8s/serverless config]
## Data Flow
1. Request enters via [entry point]
2. Auth validated by [auth middleware/service]
3. Business logic in [service layer]
4. Data persisted to [database]
5. Response returned via [serialization layer]
## Integration Points
| System | Protocol | Purpose |
|--------|----------|---------|
| [external service] | REST/gRPC | [inferred purpose] |
## Scaling Considerations
- [Based on queue usage, caching patterns, etc.]
After generating diagrams, verify:
| Format | Use When |
|---|---|
| Mermaid | Default — renders in GitHub, Notion, most tools |
| PlantUML | Enterprise teams, existing PlantUML tooling |
| C4 (Structurizr) | Formal architecture reviews |
| ASCII | Terminal/CLI environments |
| Excalidraw JSON | When user wants editable hand-drawn style |
Provides UI/UX resources: 50+ styles, color palettes, font pairings, guidelines, charts for web/mobile across React, Next.js, Vue, Svelte, Tailwind, React Native, Flutter. Aids planning, building, reviewing interfaces.
Fetches up-to-date documentation from Context7 for libraries and frameworks like React, Next.js, Prisma. Use for setup questions, API references, and code examples.
npx claudepluginhub adit-jain-srm/skill-forge --plugin skill-forge