CodeAtlas

Try it · How the numbers are computed · How well it works · How it is built

Point CodeAtlas at a repository and it produces a browsable report: an architecture map, where to start reading, who owns what, which files change together, hotspots and concrete findings. Most of the report is computed from the code (Tree-sitter) and the git history (JGit), so every number can be traced back to a file, line or commit. An LLM is optional and only used for Q&A.

Status: milestones M1-M5 of PLAN.md are done. The reading order and the question-answering search have both been measured, which is how their current behaviour was chosen: see docs/evaluation.md, including where they only tie simple baselines.

Reading order for pallets/flask: 5,557 commits and 236 files reduced to "read these first, and here is why".

Ask, with every citation checked

The model sees only the retrieved excerpts. Each citation it writes is then checked against them and labelled exact, inside an excerpt or unsupported, so a confident-sounding wrong line number is visible rather than hidden. Here it also says plainly that the excerpts do not contain Serializer.load, which is the behaviour the prompt asks for.

More of the report (findings, ownership, architecture, graph)

Findings — each with the file and line evidence behind it, linked to GitHub:

Ownership — who last changed each current line, bus factor per directory, single-owner flags:

Architecture — directories stacked in layers by import direction, cycles marked:

Import graph — grouped by directory, with optional co-change links:

Change coupling and hotspots:

What it produces today

• Overview: commits, contributors, files, lines of code, languages, test-file ratio, history span.
• Reading order: Python files ranked by churn, reach (how much of the codebase a file pulls in) and fan-in, each with the parts of its score and plain-language reasons. The weights were chosen on half of 20 repositories and checked on the other half: docs/evaluation.md.
• Import graph: interactive, grouped by directory, showing what a file imports and what imports it, optionally with co-change links.
• Ownership: who last changed each current line (git blame, whitespace ignored, .git-blame-ignore-revs honoured), per file and directory, with bus factor and single-owner / orphaned flags. One person's different emails and names are merged (.mailmap, same email, same full name); bots are excluded.
• Change coupling: files and top-level areas that change in the same commits, marking pairs with no import between them (hidden dependencies).
• Hotspots: code that is both frequently changed and deeply nested (indentation complexity).
• Architecture: directories stacked in layers by import direction, with import cycles marked.
• Findings, each with file and line evidence linked to GitHub: near-duplicate files and same-named module versions, identical function bodies, the same client rewritten in several services (by file name), import cycles between directories, committed build output, caches and .env files (never read), areas without tests, and modules no code imports ("no static import found", not "dead code").
• File details: owners, files it usually changes with, imports, importers, definitions with GitHub links.
• Ask: questions about the analyzed code. Matching code is always shown, found by symbol-aware full-text search. If a language model is configured, it answers from those excerpts only, and every citation is marked exact, inside an excerpt or unsupported so its evidence can be checked.
• JSON export of the whole report. Format: docs/report-schema.md.

Pre-computed reports in frontend/public/demo/ open without any backend.

The live site

https://code-atlas-app.vercel.app/ — the UI on Vercel, the API on Render's free tier (https://codeatlas-api-w5qr.onrender.com), one small Postgres beside it.

Two things to expect there, both consequences of the free tier rather than bugs:

• The API sleeps after about 15 minutes idle, so the first analysis you start may wait 30-60 seconds for the instance to wake. The five demo reports are static files served by Vercel, so they open instantly whether or not the API is awake; that is what they are for.
• One shared CPU, so analyses run one at a time and a large repository is slow. itsdangerous and click are good ones to try; flask with its 5,557 commits will take a while.

The deployed instance refuses local filesystem paths (CODEATLAS_ALLOW_LOCAL_PATHS=false) and caps commits, blamed files, queue length and questions per hour. See render.yaml.

Run locally

Requires Docker.

docker compose up --build

Then open http://localhost:3000. The API is at http://localhost:8080.

Endpoint	Purpose
POST /api/analyses with {"repo": "https://github.com/owner/repo"}	Queue an analysis (202)
GET /api/analyses/{id}	Status and progress
GET /api/analyses/{id}/report	The report JSON, once done
GET /api/analyses	Recently completed analyses
GET /api/info, GET /actuator/health	Version and health

Offline analysis (no server or database)

Writes a report JSON file; used for the demo reports and the evaluation.

cd backend
./mvnw -q compile dependency:build-classpath -Dmdep.outputFile=cp.txt
java -cp "target/classes:$(cat cp.txt)" io.github.shrishaanth.codeatlas.cli.AnalyzeCommand https://github.com/pallets/flask ../frontend/public/demo/flask.json

(On Windows use ; instead of : in the classpath.)

Without Docker (development)

docker compose up -d db            # Postgres only
cd backend && ./mvnw spring-boot:run
cd frontend && npm install && npm run dev    # http://localhost:5173, proxies /api to :8080

Configuration

All settings come from environment variables.

Variable	Used by	Default
DATABASE_URL	backend	jdbc:postgresql://localhost:5432/codeatlas
DATABASE_USER / DATABASE_PASSWORD	backend	codeatlas / codeatlas
PORT	backend	8080
CODEATLAS_CORS_ALLOWED_ORIGINS	backend	http://localhost:5173
CODEATLAS_ALLOW_LOCAL_PATHS	backend: accept filesystem paths (never on a public server)	false
CODEATLAS_MAX_COMMITS	backend: history walk cap	20000
CODEATLAS_CLONE_TIMEOUT_SECONDS	backend	120
CODEATLAS_MAX_QUEUED	backend: waiting analyses before refusing	20
CODEATLAS_MAX_BLAME_FILES	backend: files blamed per analysis, most-changed first	3000
CODEATLAS_THREADS	backend: parallel blame workers, 0 = one per CPU	0
CODEATLAS_QA_MODEL	backend: model for answers; unset means no model, and questions return matching code only	unset
CODEATLAS_QA_BASE_URL	backend: any OpenAI-compatible endpoint (Ollama, Gemini, Groq, OpenAI)	http://localhost:11434/v1
CODEATLAS_QA_API_KEY	backend: key for that endpoint; empty for a local model. Never commit it.	empty
CODEATLAS_QA_MAX_QUESTIONS_PER_HOUR	backend: per visitor; 0 disables the limit	30
VITE_API_BASE_URL	frontend (build time)	empty, meaning same origin

Question answering

Answering is optional and off by default: with no model configured, a question returns the code that matches it, which is the evidence an answer would cite. Any OpenAI-compatible endpoint works:

# Local and free (needs Ollama running):
CODEATLAS_QA_BASE_URL=http://localhost:11434/v1  CODEATLAS_QA_MODEL=qwen2.5-coder:7b
# Hosted (Gemini shown; Groq, OpenAI and OpenRouter work the same way):
CODEATLAS_QA_BASE_URL=https://generativelanguage.googleapis.com/v1beta/openai
CODEATLAS_QA_MODEL=gemini-3.8-flash  CODEATLAS_QA_API_KEY=...

The model only ever sees the retrieved excerpts, never the whole repository, and its citations are checked against them (docs/metrics.md).

How good is it?

Measured, not asserted. On 10 repositories that took no part in choosing the formula, the reading order places documentation-mentioned files at mean percentile 0.69, against 0.67 for sorting by file size, 0.67 for sorting by commit count and 0.50 for random order. The first version of the formula scored 0.66 and lost to both baselines; measuring it is what led to replacing it. Ownership matched CODEOWNERS for the top owner in 6 of 16 directories, across the only 2 repositories in the set that have a CODEOWNERS file. Question-answering search finds the definition of a named symbol in the top 8 results in 98-100% of cases on two repositories. Method, per-repository numbers and limits: docs/evaluation.md.

Repository layout

Path	Contents
backend/	Spring Boot service: analysis engine, evaluation harness and API
frontend/	React + TypeScript + Vite UI
docs/	Architecture, metrics, evaluation, report schema
eval/	Evaluation inputs and results
spikes/	Throwaway experiments and their measured results

How it is built

docs/architecture.md covers the pipeline, the storage choices and why the analysis engine has no Spring in it (so the same code runs the web service, the offline CLI and the evaluation harness). What every number means is in docs/metrics.md.

Tech stack

Java 17, Spring Boot 4, Tree-sitter (JNI binding), JGit, PostgreSQL, React, TypeScript, Vite, Cytoscape.js, Docker Compose, GitHub Actions. Backend tests use Testcontainers (Postgres in Docker).