# pdavis68/repomapper architecture

> Architecture diagram of the GitHub repository pdavis68/repomapper, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/pdavis68/repomapper
- Repository: https://github.com/pdavis68/repomapper

## Overview

RepoMap turns selected repository files into a ranked, token-bounded code map, exposed through a CLI and an MCP server. Its central workflow discovers files, extracts definitions and references with Tree-sitter queries, ranks related files and symbols, then renders a map sized to the token budget. The MCP server also offers identifier search. The core engine excerpt shows caching, ranking, and rendering behavior; the README documents the broader analysis stages and language support, while unsampled server details are represented only where the shown excerpt supports them.

Main entry points: [`repomap_class.py`](https://github.com/pdavis68/repomapper/blob/main/repomap_class.py) (RepoMap engine), [`repomap.py`](https://github.com/pdavis68/repomapper/blob/main/repomap.py) (CLI entry point), [`repomap_server.py`](https://github.com/pdavis68/repomapper/blob/main/repomap_server.py) (MCP server), [`scm.py`](https://github.com/pdavis68/repomapper/blob/main/scm.py) (Query lookup)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User Interfaces"]
  node_cli["CLI entry point<br/>[repomap.py]"]
  node_mcp_server["MCP server<br/>[repomap_server.py]"]
  node_map_tool["Map tool<br/>[repomap_server.py]"]
  node_search_tool["Identifier search<br/>[repomap_server.py]"]
end

subgraph group_analysis["Code Analysis"]
  node_discovery["File discovery<br/>[repomap.py]"]
  node_engine["RepoMap engine<br/>[repomap_class.py]"]
  node_tag_extraction["Tag extraction<br/>[repomap_class.py]"]
  node_tag_cache[("Tag cache<br/>[repomap_class.py]")]
end

subgraph group_ranking["Ranking and Output"]
  node_reference_graph["Reference graph<br/>[repomap_class.py]"]
  node_pagerank["PageRank ranking<br/>[repomap_class.py]"]
  node_importance["Important file rules<br/>[importance.py]"]
  node_token_fit["Token-budget fitting<br/>[repomap_class.py]"]
  node_map_render["Map rendering<br/>[repomap_class.py]"]
end

subgraph group_support["Parsing Support"]
  node_token_utils["Token counting<br/>[utils.py]"]
  node_file_utils["Text reading<br/>[utils.py]"]
  node_scm_lookup["Query lookup<br/>[scm.py]"]
  node_query_files["Language queries"]
end

node_cli_user(("CLI user"))
node_mcp_client(("MCP client"))

node_cli_user -->|"invokes"| node_cli
node_cli -->|"expands paths"| node_discovery
node_cli -->|"runs mapping"| node_engine
node_mcp_client -->|"requests tools"| node_mcp_server
node_mcp_server -.->|"registers tools"| node_map_tool
node_map_tool -->|"scans files"| node_discovery
node_map_tool -->|"runs mapping"| node_engine
node_mcp_server -.->|"serves search"| node_search_tool
node_search_tool -->|"gets tags"| node_engine
node_search_tool -->|"renders context"| node_map_render
node_engine -->|"extracts tags"| node_tag_extraction
node_tag_extraction -->|"reads writes"| node_tag_cache
node_tag_extraction -.->|"selects queries"| node_scm_lookup
node_scm_lookup -->|"locates query"| node_query_files
node_engine -->|"builds references"| node_reference_graph
node_reference_graph -->|"ranks graph"| node_pagerank
node_engine -->|"filters files"| node_importance
node_engine -->|"fits map budget"| node_token_fit
node_token_fit -->|"formats snippets"| node_map_render
node_engine -.->|"counts tokens"| node_token_utils
node_engine -.->|"reads source"| node_file_utils

click node_cli "https://github.com/pdavis68/repomapper/blob/main/repomap.py"
click node_mcp_server "https://github.com/pdavis68/repomapper/blob/main/repomap_server.py"
click node_map_tool "https://github.com/pdavis68/repomapper/blob/main/repomap_server.py"
click node_search_tool "https://github.com/pdavis68/repomapper/blob/main/repomap_server.py"
click node_discovery "https://github.com/pdavis68/repomapper/blob/main/repomap.py"
click node_engine "https://github.com/pdavis68/repomapper/blob/main/repomap_class.py"
click node_tag_extraction "https://github.com/pdavis68/repomapper/blob/main/repomap_class.py"
click node_tag_cache "https://github.com/pdavis68/repomapper/blob/main/repomap_class.py"
click node_reference_graph "https://github.com/pdavis68/repomapper/blob/main/repomap_class.py"
click node_pagerank "https://github.com/pdavis68/repomapper/blob/main/repomap_class.py"
click node_importance "https://github.com/pdavis68/repomapper/blob/main/importance.py"
click node_token_fit "https://github.com/pdavis68/repomapper/blob/main/repomap_class.py"
click node_map_render "https://github.com/pdavis68/repomapper/blob/main/repomap_class.py"
click node_token_utils "https://github.com/pdavis68/repomapper/blob/main/utils.py"
click node_file_utils "https://github.com/pdavis68/repomapper/blob/main/utils.py"
click node_scm_lookup "https://github.com/pdavis68/repomapper/blob/main/scm.py"
click node_query_files "https://github.com/pdavis68/repomapper/tree/main/queries"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_mcp_server,node_map_tool,node_search_tool,node_cli_user,node_mcp_client toneBlue
class node_discovery,node_engine,node_tag_extraction,node_tag_cache toneAmber
class node_reference_graph,node_pagerank,node_importance,node_token_fit,node_map_render toneMint
class node_token_utils,node_file_utils,node_scm_lookup,node_query_files toneRose
```

## Components

### User Interfaces

- [CLI entry point](https://github.com/pdavis68/repomapper/blob/main/repomap.py): `repomap.py`
- [MCP server](https://github.com/pdavis68/repomapper/blob/main/repomap_server.py): `repomap_server.py`
- [Map tool](https://github.com/pdavis68/repomapper/blob/main/repomap_server.py): `repomap_server.py`
- [Identifier search](https://github.com/pdavis68/repomapper/blob/main/repomap_server.py): `repomap_server.py`

### Code Analysis

- [File discovery](https://github.com/pdavis68/repomapper/blob/main/repomap.py): `repomap.py`
- [RepoMap engine](https://github.com/pdavis68/repomapper/blob/main/repomap_class.py): `repomap_class.py`
- [Tag extraction](https://github.com/pdavis68/repomapper/blob/main/repomap_class.py): `repomap_class.py`
- [Tag cache](https://github.com/pdavis68/repomapper/blob/main/repomap_class.py): `repomap_class.py`

### Ranking and Output

- [Reference graph](https://github.com/pdavis68/repomapper/blob/main/repomap_class.py): `repomap_class.py`
- [PageRank ranking](https://github.com/pdavis68/repomapper/blob/main/repomap_class.py): `repomap_class.py`
- [Important file rules](https://github.com/pdavis68/repomapper/blob/main/importance.py): `importance.py`
- [Token-budget fitting](https://github.com/pdavis68/repomapper/blob/main/repomap_class.py): `repomap_class.py`
- [Map rendering](https://github.com/pdavis68/repomapper/blob/main/repomap_class.py): `repomap_class.py`

### Parsing Support

- [Token counting](https://github.com/pdavis68/repomapper/blob/main/utils.py): `utils.py`
- [Text reading](https://github.com/pdavis68/repomapper/blob/main/utils.py): `utils.py`
- [Query lookup](https://github.com/pdavis68/repomapper/blob/main/scm.py): `scm.py`
- [Language queries](https://github.com/pdavis68/repomapper/tree/main/queries): `queries`

### Other components

- **CLI user**
- **MCP client**

## Connections

- CLI user → CLI entry point: invokes (evidence: `README.md`)
- CLI entry point → File discovery: expands paths (evidence: `repomap.py`)
- CLI entry point → RepoMap engine: runs mapping (evidence: `repomap.py`)
- MCP client → MCP server: requests tools (evidence: `README.md`)
- MCP server → Map tool: registers tools (evidence: `repomap_server.py`)
- Map tool → File discovery: scans files (evidence: `repomap_server.py`)
- Map tool → RepoMap engine: runs mapping (evidence: `repomap_server.py`)
- MCP server → Identifier search: serves search (evidence: `repomap_server.py`)
- Identifier search → RepoMap engine: gets tags (evidence: `repomap_server.py`)
- Identifier search → Map rendering: renders context (evidence: `repomap_server.py`)
- RepoMap engine → Tag extraction: extracts tags (evidence: `repomap_class.py`)
- Tag extraction → Tag cache: reads writes (evidence: `repomap_class.py`)
- Tag extraction → Query lookup: selects queries (evidence: `repomap_class.py`)
- Query lookup → Language queries: locates query (evidence: `scm.py`)
- RepoMap engine → Reference graph: builds references (evidence: `repomap_class.py`)
- Reference graph → PageRank ranking: ranks graph (evidence: `repomap_class.py`)
- RepoMap engine → Important file rules: filters files (evidence: `repomap_class.py`)
- RepoMap engine → Token-budget fitting: fits map budget (evidence: `repomap_class.py`)
- Token-budget fitting → Map rendering: formats snippets (evidence: `repomap_class.py`)
- RepoMap engine → Token counting: counts tokens (evidence: `repomap_class.py`)
- RepoMap engine → Text reading: reads source (evidence: `repomap_class.py`)