AI Project Brain

Turn any GitHub repository into an interactive software engineering course.

AI Project Brain analyzes a codebase and teaches it — explaining what the software does, why it exists, its architecture, and the engineering decisions behind it, using a Tree-sitter → embeddings → vector-search → RAG pipeline.

This repository currently contains the project scaffold: a runnable, standards-compliant skeleton with tooling and structure in place, but no feature logic yet. See docs/specs/ for the full product and engineering specifications that drive the roadmap.

Stack

Layer	Technology
Frontend	Next.js (App Router), TypeScript, Tailwind, shadcn/ui
Backend	FastAPI, SQLAlchemy, Pydantic (Clean Architecture)
Database	PostgreSQL
Cache / Queue	Redis, Celery
Vector DB	Qdrant
Parser	Tree-sitter
Auth	GitHub OAuth

Repository layout

.
├── backend/        FastAPI service — domain / application / infrastructure / presentation
├── frontend/       Next.js app — dashboard, learn, code explorer, flow explorer, docs …
├── docs/specs/     Product & engineering specifications (SRS, UI/UX, Constitution, …)
├── docker-compose.yml   Local Postgres + Redis + Qdrant
├── .env.example    Environment template — copy to `.env`
└── README.md

Getting started

Prerequisites

• Node.js ≥ 20 and npm
• Python ≥ 3.11
• Docker Desktop (for the Postgres / Redis / Qdrant dev services)

1. Configure environment

cp .env.example .env
# edit .env and fill in secrets as needed

2. Start backing services

docker compose up -d      # Postgres, Redis, Qdrant
docker compose ps         # confirm all healthy

3. Run the backend

cd backend
python -m venv .venv
# Windows:  .venv\Scripts\activate     |  macOS/Linux:  source .venv/bin/activate
pip install -e ".[dev]"
uvicorn app.main:app --reload
# → http://localhost:8000/api/v1/health  should return {"status":"ok"}

4. Run the frontend

cd frontend
npm install
npm run dev
# → http://localhost:3000  (redirects to /dashboard)

Quality gates

Every contribution must pass linting, formatting, and tests, per the Engineering Constitution.

# Backend
cd backend && ruff check . && black --check . && pytest

# Frontend
cd frontend && npm run lint && npm run build

Roadmap

• Phase 1 – Foundation: GitHub OAuth, repository import, cloning, parsing, database.
• Phase 2 – Knowledge Engine: embeddings, vector search, RAG.
• Phase 3 – Learning Platform: overview, learn mode, code explorer, documentation.
• Phase 4 – Advanced: flow explorer, developer thinking.
• Phase 5 – Future: VS Code extension, AI software architect, git assistant.