Skip to content

About

An intelligent codebase visualizer.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

CodeAtlas

An intelligent codebase visualizer. Point it at any repository — a Git URL or a local folder — and glide from a bird's-eye architectural map down to individual statement blocks, with cross-linked explanations at every level.

CodeAtlas exploring Django

Quick start (one command, no keys)

./run.sh          # or: make run

Requirements: Python 3.10+ and git on your PATH. That's it — the first run creates a virtualenv, installs pinned dependencies, starts the server on http://localhost:4870 and opens your browser. The frontend ships pre-built; Node is only needed if you want to hack on the UI.

The app self-demonstrates immediately with two built-in repositories:

  • Orbit (sample) — a small, real task-tracker (Python server + JS web client + CLI). Every one of its 200+ units ships with a curated, cross-linked explanation, so the full experience works offline.
  • CodeAtlas (this app) — the tool visualizing its own source.

Add your own repo via + Add repo (Git URL or absolute local path) — it's cloned shallowly and indexed in the background with live progress. A 600k-line repository (Django) indexes in about 5 seconds.

The idea: semantic zoom

CodeAtlas builds a five-level hierarchy and lets you move through it fluidly:

Level Unit Example
L4 System the whole repo: subsystems, dependency arrows, entry points
L3 Module a directory/package: purpose, key files, internal structure
L2 File / class responsibilities, members, collaborators
L1 Function / method contract, side effects, callers/callees
L0 Statement block line-level explanation inside a function

Zoom in (scroll) or double-click and containers expand in place to reveal their internals — true semantic zoom that reveals/hides detail, not pixel scaling. Zoom out and they fold away again. Every explanation cross-references related units — callers, callees, imports, subclasses, parents — and every reference is a link that navigates and re-centers the map. Explanations are generated bottom-up (a module's summary synthesizes its files' summaries), so higher levels are grounded rather than hallucinated.

Panels: the zoomable map, a syntax-highlighted source view (an L1 function's blocks are clickable line-regions → L0 explanations), the explanation panel with cross-links and related-unit chips, a breadcrumb across levels, a file tree, and symbol search (⌕ box, arrow keys + Enter).

LLM configuration (optional)

Explanations come from a pluggable Explainer with four backends, resolved in this order:

  1. Anthropic — set ANTHROPIC_API_KEY (model via ANTHROPIC_MODEL).
  2. OpenAI-compatible — set OPENAI_API_KEY; point OPENAI_BASE_URL at OpenAI, Together, vLLM, LM Studio, or any compatible server (model via OPENAI_MODEL).
  3. Ollama — set CODEATLAS_BACKEND=ollama (defaults: http://localhost:11434, qwen2.5-coder:7b).
  4. Structural (offline) — always available, no network: real explanations derived from the AST and relationship graph (signatures, control flow, callers/callees, hotspots), clearly badged as structural.

You can also copy codeatlas.toml.example → codeatlas.toml. Environment variables win over the file.

Caching: every explanation is cached on disk under data/cache/, keyed by sha256(prompt_version | level | code-hash) — unchanged code is never re-explained, which is what makes large repos affordable. Structural entries are transparently upgraded the moment a live backend is configured (there's also a ↻ button per unit). The sample's curated explanations live in the same cache and are served by the same code path, so adding a key later changes nothing except quality of new explanations. The live path for all three protocols is exercised by scripts/verify_llm_backends.py against a mock server.

Supported languages

Full AST parsing (bundled tree-sitter grammars, no network): Python, JavaScript, TypeScript/TSX, Java, Go, C, C++, Rust.

Best-effort symbol detection (regex): Ruby, PHP, C#, Swift, Kotlin, Scala, shell, Lua, Perl, Elixir, R, Dart, SQL, Zig. Anything else still appears with a structural file summary. Vendored/build directories (node_modules, dist, venv, target, …), binaries, lockfiles and minified bundles are skipped automatically; files stream in with progress so big repos never freeze the UI.

Architecture

backend/codeatlas/
  ingest.py      clone/walk: skip-lists, binary sniff, size caps
  languages.py   grammar registry + per-language node-type specs
  parsing.py     tree-sitter extraction → files/classes/functions/blocks
  linker.py      import & call resolution (heuristic, precision-first)
  indexer.py     pipeline: parse → hierarchy → edges → SQLite (data/index/)
  store.py       SQLite store, one db per repo
  explain/       Explainer interface, 4 backends, disk cache, context builder
  main.py        FastAPI: graph/tree/units/explanations/search + static UI
frontend/src/
  components/Canvas.tsx   semantic-zoom map (custom SVG, no graph lib)
  lib/layout.ts           nested dependency-column layout
  …                       panels, breadcrumb, tree, search, theme
sample_repo/orbit/        the bundled demo codebase
scripts/                  smoke tests, LLM-path verification, cache seeding

Notable choices (rationale in BUILD_LOG.md): SQLite over JSON for indexes; official per-language tree-sitter wheels over runtime grammar downloads; a hand-rolled SVG canvas + layered layout instead of a graph library (in-place container expansion is the whole point); highlight.js over Monaco/Shiki.

Edges (calls, imports, inheritance) are stored at the finest level and aggregated on demand to whatever nodes are visible, so the arrows stay meaningful at every zoom depth.

Development

make dev-frontend     # Vite dev server with hot reload (proxies /api)
make build-frontend   # rebuild frontend/dist
make smoke            # API smoke test against the sample
python3 scripts/verify_llm_backends.py   # mock-server test of the live path

Troubleshooting

  • Port busy — CODEATLAS_PORT=5000 ./run.sh.
  • A repo fails to index — the progress overlay shows the error; git must be on PATH for URL sources.
  • Corporate proxy breaks LLM calls — proxy env vars are honored when possible and bypassed when the proxy scheme is unsupported.
  • Windows — run python -m venv .venv && .venv\Scripts\pip install -r backend\requirements.txt && cd backend && ..\.venv\Scripts\python -m uvicorn codeatlas.main:app --port 4870 (run.sh is macOS/Linux).

About

An intelligent codebase visualizer.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages