Codenova

AI Codebase Navigator & Autonomous GitHub Engineering Assistant

Overview

Codenova (the FastAPI app identifies itself internally as CodeNavigator) connects to a GitHub repository, indexes it into a searchable knowledge base, and exposes that knowledge through a set of AI-driven workflows: natural-language chat over the codebase, automated documentation generation, automated pull request review, and an autonomous code-editing agent that plans, implements, verifies, and opens pull requests for real code changes.

It's a two-tier web application: a Next.js/React frontend for authentication and all user-facing workflows, and a FastAPI backend that performs repository ingestion, AST parsing, embeddings, knowledge-graph construction, and LLM orchestration. Long-running work (ingestion, autonomous code edits) runs on Celery workers so the API stays responsive, backed by PostgreSQL, Qdrant (vector search), Neo4j (code knowledge graph), and Redis (queueing + live status).

Features

• Repository Ingestion & Indexing — Clones a repo (GitHub API loader with a shallow-git-clone fallback for large/private repos), parses it with Tree-sitter (Python, JavaScript, TypeScript, Go, Java), splits it into symbol-aligned chunks (one per function/class, with a sliding-window fallback for non-code files), embeds the chunks (OpenAI text-embedding-3-small) into Qdrant, and writes a structural graph (files, functions, classes, calls, imports, inheritance) into Neo4j. Runs as a Celery job with live progress over SSE; supports incremental refresh that re-indexes only files changed since the last indexed commit.
• Repository Chat (RAG) — Natural-language Q&A over a codebase. Classifies question intent (regex-first, LLM fallback), retrieves relevant code via Qdrant vector search, enriches answers with Neo4j graph context (callers, class hierarchy, import dependencies), and streams cited, sourced answers. Includes a slash-command layer (/explain, /search, /review, /impact, /trace, /history, /diagram, /link, /unlink) and a multi-repository mode that resolves symbols across "linked" repos via the graph first, with capped vector-search fan-out for scale.
• Documentation Generation — Generates a 15-topic technical document (overview, architecture, API reference, data models, authentication, dependency graph, configuration, error handling, testing strategy, deployment, performance, security, onboarding, etc.), retrieving relevant code and graph context per topic and firing all topic LLM calls in parallel, then assembling one Markdown document with a table of contents.
• Pull Request Review — Fetches a PR's diff and runs four analyses in parallel (code review, plain-language summary, optimization suggestions, and a pure graph-traversal impact analysis via Neo4j), then a synthesis call that produces a decision (approve / request changes / reject), a confidence score, and risk flags. Reviewers can approve, reject, or merge directly from the UI.
• AI Code Editor — Turns a natural-language instruction into a real, verified code change. A LangGraph planner classifies the request, retrieves relevant context, and produces a reviewable plan. A tool-using agent (read_file, write_file, edit_file, list_dir, run_command, delete_file) executes the plan inside an isolated, long-lived Docker container (no bind mounts, dropped capabilities, resource limits). Long sessions stay within the model's context window via an LLM-written transcript-compaction/recap mechanism (with a safe elision fallback if summarization fails). A deterministic, non-LLM verifier auto-discovers each project in the repo and runs its compile/typecheck/build/test steps, feeding failures back into the agent for a bounded repair loop. Approved diffs are reset onto a clean base and reapplied before pushing, so what's pushed always matches what was reviewed; approval opens a GitHub pull request.
• Cross-Repository Impact Analysis — A Neo4j "architecture layer" (services, endpoints, and confidence-scored call edges between them, built from regex-based API-surface detection during ingestion) lets Codenova reason about how a change in one repository affects others — surfaced as breaking-change/blast-radius data in PR review and as graph-first entity resolution in multi-repo chat.
• Diagram Generation — Deterministic, non-LLM rendering of the Neo4j graph into Mermaid diagrams: module-level (auto-grouped by folder, infrastructure-aware), class-level, query-scoped "focus" diagrams, and a cross-repo service-topology view — all node/edge-capped for readability. An LLM-planned "flow" mode also exists for runtime/request-flow diagrams, but the model only ever emits a validated JSON plan; Mermaid syntax is always generated server-side, never by the LLM.
• Repository Change Timeline — A "history" chat intent that fetches live commit and tag data directly from GitHub and requires every claim in the answer to cite a real commit — it reports an explicit failure rather than fabricating a timeline if the GitHub fetch fails. Commits mentioned in an answer are auto-linked to their GitHub pages in the UI.
• Handling Large Repositories — File-size caps and shallow clones bound ingestion cost; AST parsing is concurrency-limited; embeddings and vector upserts are batched with retry/backoff; vector-store point IDs are deterministic so re-indexing is idempotent; cross-repo fan-out and diagram size are hard-capped; Celery is configured for reliability (late acknowledgement, low prefetch) so long-running ingestion and code-edit jobs survive worker restarts.

Architecture

flowchart LR
    User[Browser] -->|Next.js UI| FE[Frontend\nNext.js / React]
    FE -->|REST + SSE / EventSource| BE[Backend\nFastAPI]
    BE --> PG[(PostgreSQL)]
    BE --> RD[(Redis)]
    BE --> QD[(Qdrant\nvector search)]
    BE --> N4[(Neo4j\ncode graph)]
    BE -->|OAuth, PR/commit data| GH[GitHub]
    BE -->|enqueue jobs| CW[Celery Worker]
    CW --> PG
    CW --> QD
    CW --> N4
    CW -->|sandboxed edit sessions| DK[Docker container\ncoding-agent sandbox]
    CW -->|clone, push, open PR| GH
    BE -->|chat / doc / PR / coding models| OR[OpenRouter]
    BE -->|embeddings| OAI[OpenAI]

Loading

Tech Stack

Category	Technology
Frontend	Next.js 16 (App Router), React 19, TypeScript, TanStack Query, Tailwind CSS 4, shadcn/ui + Radix UI, Mermaid.js, react-markdown + remark-gfm, Framer Motion, Sonner (toasts), axios, jose (JWT verification in middleware)
Backend	Python 3.12, FastAPI, Uvicorn, SQLAlchemy 2.0 + Alembic + asyncpg, Celery, LangChain + LangGraph, slowapi (rate limiting), python-jose + passlib/bcrypt
Datastores	PostgreSQL 16 (relational data), Redis 7 (Celery broker/backend + live activity feed), Qdrant (vector search), Neo4j 5 with APOC (code knowledge graph)
AI / LLM layer	OpenAI (text-embedding-3-small embeddings), OpenRouter gateway (default chat/doc/PR model: Gemini 2.5 Flash; coding-agent model independently configurable)
Code analysis	Tree-sitter grammars for Python, JavaScript, TypeScript, Go, Java; regex-based HTTP route/call extraction for the cross-repo architecture graph
Infra	Docker (API image + a separate node:20-bookworm + Python sandbox image for the coding agent), Docker Compose (datastores), GitHub OAuth + REST API (PyGithub / GitPython)

Project Structure

backend/
  app/
    agents/            # LLM-orchestration agents
      chat_agent.py    #   repo chat / RAG pipeline (intent classification, retrieval, graph enrichment, streaming)
      doc_agent.py     #   documentation generation (15-topic catalogue, parallel generation)
      pr_agent.py      #   pull request review (parallel analyses + synthesis decision)
      repo_analyzer.py #   ingestion/refresh orchestration (AST -> chunk -> embed -> graph)
      slash_commands.py#   chat slash-command catalogue and parsing
      coding_agent/    #   autonomous code editor: planner (LangGraph), tool-using editor,
                       #   test-writing agent, deterministic verifier
    api/routes/         # FastAPI route handlers: auth, repositories, chat, docs, pull_request, code_edit, health
    core/               # settings, DB/Redis session setup, security (JWT + password hashing), LLM client config
    models/             # SQLAlchemy ORM models
    schemas/            # Pydantic request/response schemas
    services/           # AST extraction, chunking, embeddings, vector store, graph store, diagram builder,
                        # GitHub API wrapper, Docker sandbox primitives, cross-repo ranking, activity log, etc.
    tasks.py            # Celery app + background jobs (ingestion, refresh, code-edit pipeline, PR push)
  alembic/               # database migrations
  tests/                 # backend tests
  docker-compose.yaml    # Postgres / Redis / Qdrant / Neo4j service definitions
  Dockerfile             # API container image
  Dockerfile.agent        # coding-agent sandbox container image

frontend/
  src/
    app/                # Next.js routes: landing, login, GitHub OAuth callback, dashboard, ingestion,
                        # repo workspace (chat/code modes), docs, pull request views
    components/          # feature UI: chat, code-edit, docs, pull-request, repo (file tree), shared, ui (shadcn)
    hooks/               # session/workspace state hooks (chat session, code-edit workspace/session/activity)
    lib/                 # API clients per feature, shared axios instance, auth context, query-key registry
    providers/           # React Query provider
    types/               # shared TypeScript types

API Overview

Group	Prefix	Representative endpoints
Health	/health	GET /health, GET /health/full
Auth	/api/v1/auth	POST /register, POST /login, GET /github, GET /github/callback, GET /me, POST /logout
Repositories	/api/v1/repos	POST /, GET /, GET /{repo_id}, POST /{repo_id}/refresh, DELETE /{repo_id}, GET /{repo_id}/architecture, GET /{repo_id}/status/stream
Chat	/api/v1/chat	GET /models, GET /commands, POST /sessions, POST /sessions/{id}/stream, DELETE /messages
Docs	/api/v1/docs	GET /topics, POST /generate/{repo_id}, GET /generate/{repo_id}/stream, GET /{doc_id}
Pull Requests	/api/v1/prs	GET /{repo_id}, POST /{repo_id}/{pr_number}/analyze, POST /{repo_id}/{pr_number}/decision
Code Edit	/api/v1/code-edit	POST /{repo_id}, POST /session/{id}/approve-changes, POST /session/{id}/refine, GET /session/{id}/activity

Getting Started

Prerequisites: Python 3.12+, Node.js, Docker (daemon running), a GitHub OAuth App, an OpenRouter API key, and an OpenAI API key (for embeddings).

Backend

cd backend
# create a .env with the variables listed below
docker-compose up -d          # Postgres, Redis, Qdrant, Neo4j
pip install -r requirements.txt
alembic upgrade head
uvicorn app.main:app --reload --port 8000

In a second terminal, start the background worker:

celery -A app.tasks.celery_app worker --loglevel=info

Only required if you'll use the AI Code Editor, build its sandbox image once:

docker build -f Dockerfile.agent -t codenav-agent:latest .

Frontend

cd frontend
# create a .env with the variables listed below
npm install
npm run dev

Visit http://localhost:3000.

Environment Variables

Backend (backend/.env)

Variable	Purpose
APP_ENV, SECRET_KEY, ALLOWED_ORIGINS, FRONTEND_URL	environment mode, JWT signing key, CORS origins, frontend base URL
DATABASE_URL	PostgreSQL connection string
REDIS_URL	Redis connection (activity feed; also the base for the Celery URLs below)
QDRANT_URL, QDRANT_API_KEY, QDRANT_COLLECTION	vector store connection and collection name
NEO4J_URI, NEO4J_USER, NEO4J_PASSWORD	code knowledge graph connection
GITHUB_CLIENT_ID, GITHUB_CLIENT_SECRET, GITHUB_REDIRECT_URI	GitHub OAuth app credentials
OPENROUTER_API_KEY, OPENROUTER_BASE_URL	LLM gateway used for chat, docs, PR review, and the coding agent
CHAT_MODEL, CHAT_MODEL_FALLBACK, EMBED_MODEL, CODING_MODEL	model selection (coding model falls back to CHAT_MODEL if unset)
OPENAI_API_KEY	embeddings provider key
CELERY_BROKER_URL, CELERY_RESULT_BACKEND	Celery queue and result store
REPO_CLONE_DIR	local path repositories are cloned into
SANDBOX_ENABLED, SANDBOX_AGENT_IMAGE, SANDBOX_MEM_LIMIT, SANDBOX_CPUS, SANDBOX_TIMEOUT, SANDBOX_MAX_REPAIR_ATTEMPTS	coding-agent Docker sandbox tuning (all optional, sensible defaults in app/core/config.py)

app/core/config.py also defines further optional tuning defaults (agent iteration/output limits, diagram size caps, chat history fetch limits, planner options) that don't need to be set for normal use.

Frontend (frontend/.env)

Variable	Purpose
NEXT_PUBLIC_BACKEND_URL	base URL of the backend API
NEXT_PUBLIC_JWT_SECRET	used by the Next.js middleware to verify the session JWT cookie