map

Architecture Map

Generate a high-level architectural map of the codebase: layers, modules, boundaries, data flow, and dependency directions. The output should give someone who's never seen this codebase a mental model in 2 minutes.

Workflow

1. Survey the Project

Gather structural data:

• Directory listing: Top-level and one level deep (ls -la, ls src/)
• Package config: package.json, pyproject.toml, Cargo.toml, go.mod — what's the stack?
• Framework config: next.config.js, vite.config.ts, tsconfig.json, etc.
• Entry points: Main files, route directories, handler directories
• lenskit_status: If available, call lenskit_status with detailed: true first. It provides file count, avg risk score, top risk files, circular dependency count, hub count, and test coverage ratio. This gives you a quantitative foundation before reading any code.

2. Identify Layers

Read representative files from each major directory to understand the layer:

Use the layer classification from skills/trace/references/layer-patterns.md to identify which directory maps to which architectural layer. Common patterns:

• Entry/Routing: app/, pages/, routes/, api/, handlers/, controllers/
• Business logic: services/, use-cases/, domain/
• Data access: db/, repositories/, models/
• Utilities: lib/, utils/, helpers/
• Presentation: components/, ui/, views/
• Cross-cutting: middleware/, plugins/, config/

For framework-specific patterns (Django, FastAPI, Spring Boot, etc.), see the reference file.

3. Map Dependencies

With lenskit-mcp (preferred): Call lenskit_graph to get the full dependency graph with layer classifications, circular dependencies, hub files, and layer violations pre-computed. Use this data directly for the module map and observations sections. For the highest-risk or highest-centrality files, call lenskit_analyze to add risk-score and coupling detail to the observations.

Note on tsconfig path aliases: If the project uses tsconfig path aliases (e.g., @/utils/helpers mapping to src/utils/helpers), lenskit resolves these automatically. The graph data will show the true file-to-file dependencies even for aliased imports. If you see aliased imports in the code that don't appear in the graph, check whether the project's tsconfig.json has paths configured.

Without lenskit-mcp: For each major module/directory, identify what it imports from and what imports it:

# What does src/lib/auth import?
grep -h "from" src/lib/auth/*.ts | sort -u

# What imports from src/lib/auth?
grep -rl "from.*lib/auth" src/ | grep -v "lib/auth"

Build a dependency direction map: which layers depend on which?

4. Identify Boundaries

Look for:

• Trust boundaries: Where external input enters (API routes, webhooks, file uploads)
• Package boundaries: In monorepos, where packages interface with each other
• Layer boundaries: Where one architectural layer calls another
• External boundaries: Where code talks to databases, APIs, file systems

5. Present the Map

Report format:

## Architecture Map — {project name}

### Stack
{Framework, language, database, key dependencies — one line each}

### Layer Diagram

┌─────────────────────────────────────────┐
│  Entry (app/api/, app/(routes)/)        │ ← External requests
├─────────────────────────────────────────┤
│  Middleware (middleware.ts, lib/auth/)    │ ← Auth, rate limiting
├─────────────────────────────────────────┤
│  Business Logic (lib/services/)          │ ← Core domain
├─────────────────────────────────────────┤
│  Data Access (lib/db/)                   │ ← Database operations
├─────────────────────────────────────────┤
│  External Services (lib/clients/)        │ ← Third-party APIs
└─────────────────────────────────────────┘

### Module Map

| Module | Purpose | Depends on | Depended by |
|--------|---------|------------|-------------|
| lib/auth | Authentication | lib/db, env | api/*, middleware |
| lib/db | Database access | prisma, env | lib/services, api/* |
| lib/services | Business logic | lib/db, lib/clients | api/* |
| ... |

### Data Flow
{Primary data flow path from entry to storage — reference /trace for detailed flows}

### Boundaries
- **Trust boundary**: All API routes require auth via middleware
- **Package boundary**: (if monorepo) packages communicate via published APIs
- **External boundary**: Database via Prisma, payments via Stripe SDK

### Key Patterns
{2-3 architectural patterns the project follows: repository pattern, service layer,
middleware chain, event-driven, etc.}

### Observations
{Potential issues: circular dependencies, layer violations, god modules, etc.}

Related Skills

• /hotspots — Find the riskiest areas in the architecture
• /trace — Follow a specific feature flow through the layers
• /explain — Deep-dive into any module you found in the map

Monorepo Guidance

For monorepos (Turborepo, Nx, Lerna, pnpm workspaces):

• Map each package separately first, then show inter-package dependencies
• Identify the dependency graph between packages (which packages depend on which)
• Highlight shared/core packages that all others depend on (these are the highest-impact modules for architecture decisions)
• Note package boundary violations: direct imports from one package's src/ into another (should use published package exports instead)
• If lenskit_graph is available, run it at the monorepo root to get cross-package edges

Guidelines

• The map should be scannable in under 2 minutes. Lead with the diagram, detail below.
• Use ASCII box diagrams for layers. Keep them simple — clarity over artistic merit.
• Focus on the ARCHITECTURE, not every file. Group by module/directory, not individual files.
• Note architectural violations: files that import across layers in unexpected directions (e.g., a utility importing from a route handler).
• If the project has no clear architecture (flat structure, everything in one directory), say so. That's a finding in itself.