CodeEngine — AI Codebase Understanding Platform

Submit any GitHub repository and get instant AI-powered analysis: architecture diagrams, interactive dependency graphs, bug detection, refactoring suggestions, and RAG-powered Q&A.

---

Overview

CodeEngine is a full-stack SaaS developer tool built to help engineers understand unfamiliar codebases quickly. Point it at any public GitHub repository and within minutes it produces:

• A plain-English architecture summary generated by an LLM
• An interactive dependency graph (files → classes → functions)
• A prioritized list of bugs and code issues found by both static analysis and LLM reasoning
• Actionable refactoring suggestions with side-by-side code diffs
• A RAG-powered Q&A chat — ask anything about the code in plain English

The platform is designed to the same quality bar as Linear or Vercel: dark-first, animation-rich, and dense without feeling cluttered.

---

Tech Stack

Layer	Technology
Frontend	React 18, Vite, TypeScript, Tailwind CSS, shadcn/ui, Framer Motion
Routing	wouter
State	Zustand (auth), TanStack Query (server state)
Graph Visualization	@xyflow/react (ReactFlow)
Backend API	Python 3.11, FastAPI, Uvicorn
Auth	JWT (python-jose) + bcrypt
Database	PostgreSQL + SQLAlchemy ORM (SQLite fallback for dev)
Vector Store	ChromaDB with local sentence-transformer embeddings
Graph DB	NetworkX in-process (optional Neo4j adapter)
Task Queue	Celery + Redis (FastAPI BackgroundTasks in dev)
Cache	Redis with in-memory fallback
LLM	OpenAI GPT-4o-mini (swappable via Strategy pattern)
Proxy	Nginx reverse proxy
Containers	Docker + Docker Compose

---

Architecture

Browser
   │
   ▼
Nginx  (/engine → FastAPI :8000 · / → React :3000)
   │                          │
   ▼                          ▼
React + Vite SPA        FastAPI (Python)
  /                       /engine/auth/*
  /login                  /engine/analyze-repo
  /register               /engine/repo-summary/:id
  /dashboard              /engine/dependency-graph/:id
  /repo/:id               /engine/issues/:id
    ├─ Overview           /engine/refactor/:id
    ├─ Issues             /engine/ask
    ├─ Refactoring        /engine/my-repos
    ├─ Dependency Graph   /engine/ws/progress/:id  ← WebSocket
    └─ Q&A Chat
                               │
              ┌────────────────┼────────────────┐
              ▼                ▼                 ▼
         PostgreSQL          Redis           ChromaDB
         (users, repos,   (cache + Celery)  (vector store)
          issues, etc.)

Clean Architecture (Python backend)

api/              FastAPI routes + WebSocket
core/             Config, logging, exceptions
domain/           Models + interfaces (ports)
services/         Business logic (AuthService, RAGService, …)
infrastructure/   DB adapters, ChromaDB, NetworkX/Neo4j, Redis
parsers/          AST parsers — Factory + Visitor patterns
workers/          Celery background tasks
tests/            18 unit + integration tests

Design Patterns Used

Pattern	Where
Factory	parsers/factory.py — selects parser by file extension
Visitor	parsers/python_parser.py — walks Python AST
Strategy	domain/interfaces.py — ICodeParser, ILLMClient
Repository	infrastructure/database/repositories/ — DB abstraction
Dependency Injection	FastAPI Depends() for auth, sessions
Clean Architecture	Domain → Services → Infrastructure, no inward deps

---

Features

Analysis Pipeline

POST /engine/analyze-repo
  │
  ├─ RepoIngestionService   clone via GitPython
  ├─ ParserService          Python AST / JS regex → FileAnalysis
  ├─ EmbeddingService       chunk code → ChromaDB vectors
  ├─ BugDetectionService    static rules + LLM semantic scan
  ├─ RefactorService        code-smell detection + LLM suggestions
  └─ SummaryService         LLM architecture narrative
        │
        └─ status = "complete"   WebSocket notifies frontend

Frontend Pages

Route	Description
/	Marketing landing — hero, features, how it works
/login	Split-screen auth with testimonial panel
/register	Split-screen auth with platform stats
/dashboard	Repo grid + inline submit form
/repo/:id	5-tab analysis view

API Reference

Auth

POST /engine/auth/register   → { access_token, user_id, email, username }
POST /engine/auth/login      → { access_token, user_id, email, username }
GET  /engine/auth/me         → user profile  [Bearer]

Repositories

POST   /engine/analyze-repo           submit GitHub URL
GET    /engine/repo-summary           list all repos
GET    /engine/repo-summary/{id}      status + architecture summary
GET    /engine/my-repos               user's repos  [Bearer]
DELETE /engine/repo/{id}              delete repo   [Bearer, owner]

Analysis

GET  /engine/dependency-graph/{id}    node-link graph
GET  /engine/issues/{id}              bugs (filter: severity, file)
GET  /engine/refactor/{id}            suggestions (filter: effort)
POST /engine/ask                      RAG Q&A + source citations

Real-time

WS   /engine/ws/progress/{id}         analysis progress stream

---

Getting Started

Option A — Docker Compose (recommended)

git clone <this-repo>
cd <this-repo>/artifacts/codebase-engine

cp .env.example .env
# Edit .env — set OPENAI_API_KEY and JWT_SECRET

docker compose up -d

Service	URL
Frontend	http://localhost
API docs (Swagger)	http://localhost/engine/docs
Celery monitor	docker compose --profile monitoring up -d → http://localhost:5555

Option B — Local Development

Requirements: Python 3.11+, Node.js 20+, pnpm

# 1. Clone
git clone <this-repo> && cd <this-repo>

# 2. Install JS dependencies
pnpm install

# 3. Python backend
cd artifacts/codebase-engine
pip install -r requirements.txt
cp .env.example .env   # add OPENAI_API_KEY + JWT_SECRET
PYTHONPATH=. python main.py   # starts on :8000

# 4. Frontend (new terminal, from repo root)
pnpm --filter @workspace/codebase-ui run dev   # starts on :19556

---

Environment Variables

Copy artifacts/codebase-engine/.env.example to .env and fill in:

Variable	Required	Description
OPENAI_API_KEY	Yes	Your OpenAI API key
JWT_SECRET	Yes	Random string for signing JWTs — change in production
DATABASE_URL	No	PostgreSQL URL (defaults to SQLite)
REDIS_URL	No	Redis URL (defaults to in-memory fallback)
LLM_MODEL	No	Default gpt-4o-mini
NEO4J_URI	No	Activates Neo4j graph store

---

Running Tests

cd artifacts/codebase-engine
PYTHONPATH=. pytest tests/ -v

18 unit tests covering AST parser, bug detection, domain model status transitions, and auth service. All run with no external dependencies (in-memory SQLite + mocked LLM).

---

Project Structure

.
├── artifacts/
│   ├── codebase-engine/        Python FastAPI backend
│   │   ├── api/
│   │   │   ├── routes/         auth, analyze, summary, graph, qa,
│   │   │   │                   issues, refactor, user_repos, progress
│   │   │   └── middleware/     logging, CORS
│   │   ├── core/               config, logging, exceptions
│   │   ├── domain/             models + interfaces
│   │   ├── infrastructure/     postgres, chromadb, networkx, redis
│   │   ├── services/           auth, ingestion, parser, embedding,
│   │   │                       bug detection, refactor, RAG, summary
│   │   ├── parsers/            Python AST, JavaScript (regex)
│   │   ├── workers/            Celery tasks
│   │   ├── tests/              unit + integration tests
│   │   ├── docker-compose.yml  full stack orchestration
│   │   ├── nginx.conf          reverse proxy
│   │   ├── Dockerfile
│   │   └── .env.example
│   │
│   └── codebase-ui/            React + Vite frontend
│       └── src/
│           ├── pages/          Home, Login, Register, Dashboard, RepoDetails
│           ├── components/     layout (Navbar) + shadcn/ui
│           └── lib/            api.ts (Axios client), auth-store.ts (Zustand)
│
├── .gitignore
├── LICENSE
├── README.md
└── pnpm-workspace.yaml

---

License

MIT — see LICENSE