Development and testing
Repository map, local verification commands, and docs-site conventions.
Repository map
| Path | Responsibility |
|---|---|
src/backend/main.py | FastAPI application and HTTP routes |
src/backend/retrievers/ | BM25, TF-IDF, Word2Vec, dense, hybrid, and reranking |
src/backend/agent/ | Planning, tool execution, generation, and streaming |
src/backend/db.py | PostgreSQL chunks and document operations |
src/backend/store.py | Conversations, messages, feedback, and memories |
scripts/ | Corpus snapshot, benchmark runner, evaluator, and QA dataset |
tests/ | Backend regression suite |
src/ | Next.js app, chat client, and UI |
docs-site/ | Separate Fumadocs app |
Verify the backend and product frontend
From the repository root:
src/backend/.venv/bin/python -m pytest tests/ -q
npm test
npm run lint
npm run typecheck
npm run buildBackend cases that use dense embeddings call the configured embedding endpoint. Start LM Studio and load the chosen model if they fail with a connection error. Database and graph tests also depend on their configured services.
Work on the docs
From docs-site/:
npm run dev
npm run types:check
npm run buildMarkdown pages live in docs-site/content/docs/. meta.json controls page order. Custom MDX components are registered in docs-site/components/mdx.tsx; .source/ is generated output and should not be edited.
Corpus snapshot
scripts/corpus.json is a manual snapshot used by the retrieval-comparison component. Re-export it after changing the live corpus before relying on component 2's result. Run the comparison script from the repository root because it reads the corpus using a working-directory-relative path.