Skip to main content

Codebase Map

A single-page architecture map of the whole repo: services, modules, API endpoints, Celery tasks, database tables, frontend pages, agent tools, and the edges between them.

👉 Open the codebase map (loads in this browser tab; works offline since both the HTML and the JSON are static assets in this docs site).

What's in it​

  • Service diagram — every container in docker-compose.yml plus the depends_on edges (waldo-app → postgres, redis, minio, ollama; profile-gated workers; the LLM sidecar).
  • API endpoints — every /api/v1/* route, grouped by router file, with method, auth requirement, and one-line summary.
  • Celery tasks — every @app.task(name="waldo.…") with its queue and a one-line summary.
  • DB tables — every SQLAlchemy model with __tablename__, columns, and foreign-key targets.
  • Frontend pages — every route from ui/src/pages/*.tsx plus the /api/v1/* endpoints that page calls.
  • Agent tools — the 10 LangChain tools the local agent can call, split into read vs. action.
  • Module tree — every Python file in lib/, app/, labeler/, trainer/, tests/, alembic/, install/, plus the React pages, collapsible by directory.

The page has a search box (matches across all categories) and per-section filter pills, so you can pivot between "show me all the endpoints" and "show me everything that mentions training_runs."

Underlying JSON​

The HTML is a thin viewer over a static JSON inventory: /codebase-map.json

Schema (see docs-site/scripts/build-codebase-map.py for the source of truth):

{
  "generated_at": "YYYY-MM-DD",
  "services":       [{ "id", "kind", "depends_on", "ports", "profile", … }],
  "modules":        [{ "path", "kind", "lines", "summary", "exports" }],
  "api_endpoints":  [{ "method", "path", "module", "auth", "summary" }],
  "celery_tasks":   [{ "name", "module", "queue", "summary" }],
  "db_tables":      [{ "name", "columns", "fk_to", "summary" }],
  "frontend_pages": [{ "route", "file", "lazy", "calls_endpoints", "summary" }],
  "agent_tools":    [{ "name", "kind", "module", "summary" }],
  "graphs": {
    "service_to_service": [{ "from", "to", "label" }],
    "endpoint_to_task":   [{ "endpoint", "task" }],
    "task_to_table":      [{ "task", "writes": [...] }]
  }
}

Refresh​

The map is regenerated by a stdlib-only Python script that walks the repo:

python3 docs-site/scripts/build-codebase-map.py

The script reads docstrings, parses docker-compose.yml, scans @router.* and @app.task decorators, and resolves SQLAlchemy column declarations. It writes docs-site/static/codebase-map.json and prints a summary line; the HTML viewer picks up the new data on next load.

If you've added a service, endpoint, table, or agent tool, run the script and commit the regenerated JSON. CI does not auto-regenerate on PR — the map is a hand-maintained snapshot, intentionally.