# cyanheads/repo-map architecture

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

- Interactive diagram: https://gitdiagram.com/cyanheads/repo-map
- Repository: https://github.com/cyanheads/repo-map

## Overview

1. **Project shape**
   - `repo-map` is a Python CLI package that analyzes a target repository and produces a Markdown “map” of its structure and files.
   - The architecture is pipeline-oriented: discover files, parse them, enrich findings with an LLM, cache results, then render a report.

2. **Entry points and command handling**
   - `src/repo_map/main.py` is the top-level entry point.
   - `cli_handler.py` likely owns argument parsing, prompt/disclaimer flow, and wiring of CLI options such as target path, model selection, concurrency, and confirmation flags.

3. **Repository discovery boundary**
   - `file_scanner.py` is the local filesystem boundary.
   - It walks the repository tree, applies ignore rules, and determines which files and directories should be included in the analysis.
   - The README emphasizes respect for the root `.gitignore` plus default ignore patterns, so scanning is intentionally selective rather than exhaustive.

4. **Code understanding layer**
   - `code_parser.py` is the static-analysis layer.
   - It extracts structural signals from source files such as imports, classes, functions, and possibly language-specific cues across Python and other supported languages.
   - This layer turns raw file contents into a normalized representation suitable for downstream summarization.

5. **LLM enrichment boundary**
   - `llm_service.py` is the external-service integration boundary.
   - It talks to OpenRouter for model-backed descriptions, developer considerations, and other narrative metadata.
   - The README indicates an API key environment variable and model selection, so this subsystem is the main network dependency and the most failure-prone external boundary.

6. **Caching and incremental behavior**
   - `cache_manager.py` provides the persistence layer for incremental runs.
   - The project uses SQLite to avoid reprocessing unchanged files, which is a key architectural optimization.
   - This makes the tool suitable for repeated use on evolving repositories and reduces LLM/API cost.

7. **Report assembly**
   - `report_generator.py` is the output composition layer.
   - It combines scanned structure, parsed metadata, and LLM-generated annotations into the final Markdown repository map.
   - The report appears tree-like, with per-file summaries and assessments embedded beneath each path.

8. **Shared domain model**
   - `models.py` likely defines the data contracts passed between subsystems: file metadata, parsed code summaries, cache entries, report sections, and LLM output.
   - This is the main internal boundary that keeps scanning, parsing, caching, and rendering decoupled.

9. **Configuration and operational concerns**
   - `config.py` centralizes runtime settings such as defaults for ignore patterns, model choice, concurrency, and environment-based configuration.
   - `logging_utils.py` handles operational visibility across the pipeline, which matters because the tool spans filesystem traversal, parsing, caching, and network calls.

10. **Execution flow**
   - The end-to-end flow is: CLI input → repository scan → file parsing → cache lookup/update → LLM enrichment for selected items → Markdown report generation.
   - The cache likely short-circuits unchanged files, while concurrency is used around API-bound enrichment work.

11. **Technology stack and packaging**
   - This is a typed Python package (`src/` layout with `py.typed`) managed with Poetry, as shown by `pyproject.toml` and the docs.
   - The repo also includes examples and documentation, but they are supporting artifacts rather than runtime subsystems.

12. **Architectural summary**
   - The core design separates local analysis from remote intelligence: filesystem scanning and parsing stay local, while narrative enrichment is delegated to OpenRouter.
   - The result is a modular, incremental pipeline that produces a human-readable Markdown artifact from a source repository.

Main entry points: [`src/repo_map/main.py`](https://github.com/cyanheads/repo-map/blob/main/src/repo_map/main.py) (Main), [`src/repo_map/models.py`](https://github.com/cyanheads/repo-map/blob/main/src/repo_map/models.py) (Models), [`src/repo_map/code_parser.py`](https://github.com/cyanheads/repo-map/blob/main/src/repo_map/code_parser.py) (Parser), [`src/repo_map/cli_handler.py`](https://github.com/cyanheads/repo-map/blob/main/src/repo_map/cli_handler.py) (CLI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Core pipeline"]
  node_main["Main<br/>entrypoint<br/>[main.py]"]
  node_cli["CLI<br/>argument flow<br/>[cli_handler.py]"]
  node_scan["Scanner<br/>filesystem boundary<br/>[file_scanner.py]"]
  node_parse["Parser<br/>static analysis<br/>[code_parser.py]"]
  node_cache[("Cache<br/>sqlite store<br/>[cache_manager.py]")]
  node_llm["LLM<br/>openrouter client<br/>[llm_service.py]"]
  node_report["Report<br/>markdown renderer"]
  node_models{{"Models<br/>domain schema<br/>[models.py]"}}
  node_config["Config<br/>runtime settings<br/>[config.py]"]
  node_log["Logging<br/>ops support<br/>[logging_utils.py]"]
end

subgraph group_support["Support"]
  node_pyproject["Pyproject<br/>package config<br/>[pyproject.toml]"]
  node_readme["README<br/>project docs<br/>[README.md]"]
  node_docs["Docs<br/>documentation"]
  node_example["Example<br/>sample output<br/>[example.md]"]
  node_scripts["Scripts<br/>helper script<br/>[scripts.py]"]
end

node_main -->|"invokes"| node_cli
node_cli -->|"loads"| node_config
node_cli -->|"starts"| node_scan
node_scan -->|"emits"| node_models
node_scan -->|"feeds"| node_parse
node_parse -->|"normalizes"| node_models
node_parse -->|"checks"| node_cache
node_cache -->|"stores"| node_models
node_parse -->|"enriches"| node_llm
node_llm -->|"uses"| node_config
node_llm -->|"returns"| node_models
node_main -->|"orchestrates"| node_report
node_report -->|"consumes"| node_models
node_report -->|"logs"| node_log
node_main -->|"initializes"| node_log
node_pyproject -.->|"packages"| node_main
node_readme -.->|"documents"| node_cli
node_docs -.->|"supports"| node_pyproject
node_example -.->|"illustrates"| node_report
node_scripts -.->|"assists"| node_main

click node_main "https://github.com/cyanheads/repo-map/blob/main/src/repo_map/main.py"
click node_cli "https://github.com/cyanheads/repo-map/blob/main/src/repo_map/cli_handler.py"
click node_scan "https://github.com/cyanheads/repo-map/blob/main/src/repo_map/file_scanner.py"
click node_parse "https://github.com/cyanheads/repo-map/blob/main/src/repo_map/code_parser.py"
click node_cache "https://github.com/cyanheads/repo-map/blob/main/src/repo_map/cache_manager.py"
click node_llm "https://github.com/cyanheads/repo-map/blob/main/src/repo_map/llm_service.py"
click node_report "https://github.com/cyanheads/repo-map/blob/main/src/repo_map/report_generator.py"
click node_models "https://github.com/cyanheads/repo-map/blob/main/src/repo_map/models.py"
click node_config "https://github.com/cyanheads/repo-map/blob/main/src/repo_map/config.py"
click node_log "https://github.com/cyanheads/repo-map/blob/main/src/repo_map/logging_utils.py"
click node_pyproject "https://github.com/cyanheads/repo-map/blob/main/pyproject.toml"
click node_readme "https://github.com/cyanheads/repo-map/blob/main/README.md"
click node_docs "https://github.com/cyanheads/repo-map/blob/main/docs/poetry_cheatsheet.md"
click node_example "https://github.com/cyanheads/repo-map/blob/main/examples/example.md"
click node_scripts "https://github.com/cyanheads/repo-map/blob/main/scripts.py"

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_main,node_cli,node_scan,node_parse,node_cache,node_llm,node_report,node_models,node_config,node_log toneBlue
class node_pyproject,node_readme,node_docs,node_example,node_scripts toneAmber
```

## Components

### Core pipeline

CLI entrypoint and the local-analysis-to-report pipeline.

- [Main](https://github.com/cyanheads/repo-map/blob/main/src/repo_map/main.py): entrypoint · Top-level CLI entry that starts the repo mapping run. · `src/repo_map/main.py`
- [CLI](https://github.com/cyanheads/repo-map/blob/main/src/repo_map/cli_handler.py): argument flow · Parses options and wires user input into the pipeline. · `src/repo_map/cli_handler.py`
- [Scanner](https://github.com/cyanheads/repo-map/blob/main/src/repo_map/file_scanner.py): filesystem boundary · Walks the target repo and applies ignore rules to select files. · `src/repo_map/file_scanner.py`
- [Parser](https://github.com/cyanheads/repo-map/blob/main/src/repo_map/code_parser.py): static analysis · Extracts structural signals such as imports, classes, and functions. · `src/repo_map/code_parser.py`
- [Cache](https://github.com/cyanheads/repo-map/blob/main/src/repo_map/cache_manager.py): sqlite store · Persists analysis results to skip unchanged files on later runs. · `src/repo_map/cache_manager.py`
- [LLM](https://github.com/cyanheads/repo-map/blob/main/src/repo_map/llm_service.py): openrouter client · Fetches narrative metadata and descriptions from the remote model API. · `src/repo_map/llm_service.py`
- [Report](https://github.com/cyanheads/repo-map/blob/main/src/repo_map/report_generator.py): markdown renderer · Combines scan, parse, cache, and LLM outputs into the final map. · `src/repo_map/report_generator.py`
- [Models](https://github.com/cyanheads/repo-map/blob/main/src/repo_map/models.py): domain schema · Shared data contracts passed between scanning, parsing, caching, and rendering. · `src/repo_map/models.py`
- [Config](https://github.com/cyanheads/repo-map/blob/main/src/repo_map/config.py): runtime settings · Centralizes defaults and environment-driven configuration. · `src/repo_map/config.py`
- [Logging](https://github.com/cyanheads/repo-map/blob/main/src/repo_map/logging_utils.py): ops support · Provides logging setup and operational visibility across the pipeline. · `src/repo_map/logging_utils.py`

### Support

Packaging, docs, examples, and auxiliary project files.

- [Pyproject](https://github.com/cyanheads/repo-map/blob/main/pyproject.toml): package config · Poetry-managed project metadata and dependency definition. · `pyproject.toml`
- [README](https://github.com/cyanheads/repo-map/blob/main/README.md): project docs · Primary user-facing overview of usage and behavior. · `README.md`
- [Docs](https://github.com/cyanheads/repo-map/blob/main/docs/poetry_cheatsheet.md): documentation · Supplementary documentation and cheatsheets. · `docs/poetry_cheatsheet.md`
- [Example](https://github.com/cyanheads/repo-map/blob/main/examples/example.md): sample output · Example repository map output used to illustrate the tool. · `examples/example.md`
- [Scripts](https://github.com/cyanheads/repo-map/blob/main/scripts.py): helper script · Auxiliary project-level scripting utilities. · `scripts.py`

## Connections

- Main → CLI: invokes · Main hands execution to CLI handling.
- CLI → Config: loads · CLI resolves runtime settings and defaults.
- CLI → Scanner: starts · CLI triggers repository discovery.
- Scanner → Models: emits · Scanner produces normalized file metadata.
- Scanner → Parser: feeds · Selected files flow into parsing.
- Parser → Models: normalizes · Parser turns source structure into shared contracts.
- Parser → Cache: checks · Parser work is skipped or reused via cache state.
- Cache → Models: stores · Cache persists analysis records in a shared schema.
- Parser → LLM: enriches · Parsed files can be sent for model-backed description.
- LLM → Config: uses · LLM client reads API and model configuration.
- LLM → Models: returns · LLM responses are mapped into internal data objects.
- Main → Report: orchestrates · Main coordinates final report assembly.
- Report → Models: consumes · Renderer reads scan, parse, cache, and LLM results.
- Report → Logging: logs · Report generation emits operational messages.
- Main → Logging: initializes · Startup configures logging for the whole run.
- Pyproject → Main: packages · Project metadata defines the typed Python package layout.
- README → CLI: documents · README explains CLI usage and the analysis flow.
- Docs → Pyproject: supports · Documentation includes Poetry-related guidance.
- Example → Report: illustrates · Example output shows the shape of generated maps.
- Scripts → Main: assists · Auxiliary scripts support running or maintaining the tool.
