notes/000-project-setup.md

Note 000 — Project Setup

Date: 2026-03-22 PR: Initial setup (no PR — baseline)

---

What was set up

• Project structure created: backend/, ingestion/, retrieval/, notes/, .claude/
• PLAN.md written with full architecture, phases, and tech stack decisions
• CLAUDE.md written with project instructions for Claude Code
• LEARN.md started — will grow as each phase is built
• Git repo initialized

---

Key architectural decisions

Why Qdrant over ChromaDB? ChromaDB is local-only — data lives on disk and disappears if you redeploy. Qdrant Cloud has a permanent free tier (1GB), making the app deployable without paying for storage. It also has native hybrid search (sparse + dense vectors), eliminating the need for our manual BM25 index.

Why nomic-embed-code over all-MiniLM-L6-v2? all-MiniLM-L6-v2 was trained on natural language. Code has different patterns: identifier names, function signatures, call chains. nomic-embed-code was fine-tuned on code and produces better semantic similarity for code queries.

Why AST chunking over character windows? Character windows split wherever they hit the size limit — often mid-function. A function is the natural unit of code: it has a name, a purpose, inputs/outputs. Chunking at function boundaries keeps each chunk semantically complete and makes citations meaningful ("see embed_text() in retrieval/embedder.py").

---

What's next

Phase 1: Core ingestion pipeline

• repo_fetcher.py — clone public repos
• file_filter.py — skip binaries, lock files, node_modules
• code_chunker.py — AST-based chunking for Python