swissarmyhammer/map

Map Codebase

Generate a rich, visual overview of the codebase and write it to ARCHITECTURE.md at the repository root.

Process

1. Check code-context status

{"op": "get status"}

If indexing is incomplete (TS or LSP indexed < 90%), wait and re-check. The quality of the map depends on having a fully indexed codebase.

2. Gather structural data

Run these queries to build a complete picture:

File inventory — understand what's in the repo:

{"op": "grep code", "pattern": ".", "max_results": 1}

Use the file counts from get status to understand scale.

Key symbols — find the major types, traits, and entry points:

{"op": "search symbol", "kind": "struct", "query": "", "max_results": 50}

{"op": "search symbol", "kind": "function", "query": "main", "max_results": 10}

{"op": "search symbol", "kind": "trait", "query": "", "max_results": 30}

{"op": "search symbol", "kind": "class", "query": "", "max_results": 30}

{"op": "search symbol", "kind": "interface", "query": "", "max_results": 30}

Module structure — list symbols in key files to understand organization:

{"op": "list symbols", "file_path": "<entry-point-file>"}

Call graph — trace key flows from entry points:

{"op": "get callgraph", "symbol": "<entry-point>", "direction": "outbound", "max_depth": 2}

Dependencies — understand module relationships:

{"op": "get blastradius", "file_path": "<key-file>", "max_hops": 2}

3. Analyze project files

Read key configuration files to understand the project structure:

• Cargo.toml / package.json / go.mod / pyproject.toml — dependencies and workspace layout
• Entry point files (main.rs, lib.rs, index.ts, main.go, etc.)

4. Synthesize into ARCHITECTURE.md

Write ARCHITECTURE.md at the repository root with the following sections:

Header

# Architecture

> Auto-generated by SwissArmyHammer `/map` — [timestamp]

## Overview

[2-3 sentence summary: what this project is, what it does, what language/framework]

Module/Package Dependency Diagram

Use graph TD to show how modules, crates, or packages depend on each other.

```mermaid
graph TD
    A[module-a] --> B[module-b]
    A --> C[module-c]
    B --> D[shared-lib]
    C --> D
```

Group by layer (e.g., CLI → core libraries → data layer) when the project has clear layers.

Key Types and Relationships

Use classDiagram for important types, traits/interfaces, and their relationships.

```mermaid
classDiagram
    class Server {
        +start()
        +handle_request()
    }
    class Handler {
        <<trait>>
        +execute()
    }
    Server --> Handler
```

Focus on the 10-20 most important types, not every struct in the codebase.

Key Flows

Use sequenceDiagram for 1-3 critical paths through the system (e.g., request handling, data pipeline, build process).

```mermaid
sequenceDiagram
    participant Client
    participant Server
    participant Handler
    participant DB
    Client->>Server: request
    Server->>Handler: dispatch
    Handler->>DB: query
    DB-->>Handler: result
    Handler-->>Server: response
    Server-->>Client: reply
```

Codebase Composition

Use pie to show the relative size of different areas.

```mermaid
pie title Codebase by Module
    "Core" : 45
    "CLI" : 20
    "Tests" : 25
    "Config" : 10
```

Directory Structure

A brief annotated tree of the top-level directories and what they contain.

## Directory Structure

- `src/` — Main source code
  - `server/` — HTTP server and routing
  - `handlers/` — Request handlers
  - `models/` — Data models
- `tests/` — Integration tests
- `config/` — Configuration files

Symbol Index

A table of major public types and functions grouped by module.

## Key Symbols

| Module | Symbol | Kind | Description |
|--------|--------|------|-------------|
| server | Server | struct | Main server instance |
| server | start | fn | Entry point |
| handler | Handler | trait | Request handler interface |

5. Print summary

After writing the file, print a brief summary to the terminal:

Wrote ARCHITECTURE.md

- [N] modules/packages mapped
- [N] key types documented
- [N] flows diagrammed
- [N] Mermaid diagrams generated

Diagrams render on GitHub, VS Code, and Obsidian.

Rules

• Write ARCHITECTURE.md at the repo root, always. Overwrite if it exists.
• Every section must have at least one Mermaid diagram.
• Diagrams must use valid Mermaid syntax that renders on GitHub.
• Focus on architecture, not implementation details. Show the forest, not the trees.
• Use data from code-context, not guesses. Every claim should be backed by a query result.
• If the codebase is a monorepo or workspace, show the workspace-level view first, then drill into key packages.
• If the user provides a path or module name as an argument, scope the map to that area instead of the whole repo.
• Keep the file under 500 lines. Be selective — map the important parts, not everything.