OpenNotebookLM: Instructions file for Codex

Repository Guidelines

Project Structure & Module Organization

backend/app/ is the FastAPI application: HTTP routes in routers/, business logic in services/, source importers in adapters/, SQLAlchemy models and column types in db/, shared helpers in utils/. Keep routers thin — they validate, delegate to a service, and shape the response.

backend/scripts/ holds operational scripts, run as python -m scripts.<name> from /app. backend/tests/ has API and lifecycle tests, backend/tests/unit/ focused ones, and backend/tests/eval/ the retrieval evaluation dataset.

frontend/ is a Next.js app: routes in app/, reusable UI in components/, hooks in hooks/, Zustand stores in store/, API client and session handling in lib/.

Deployment lives in deploy/ and the root docker-compose.yml.

Two traps in the layout:

• The root-level app/ (app/adapters/sqlite_vec.py, app/services/monitoring.py, app/routers/monitoring.py) is orphaned. Nothing imports it, and sqlite_vec.py does not use sqlite-vec despite the name. Do not extend it; the live code is under backend/app/.
• docs/ is gitignored. Anything you want tracked belongs in README.md or in a module docstring, not in docs/.

Build, Test, and Development Commands

• docker compose up -d --build runs the stack: backend on :8000, frontend on :3000. Optional services via --profile with-ollama or --profile with-cache.
• cd backend && pip install -r requirements.txt then python -m uvicorn app.main:app --reload runs the API outside Docker.
• cd frontend && npm ci && npm run dev starts Next.js. npm run build for a production build, npm run lint for ESLint.
• docker exec <backend-container> sh -lc "cd /app && python -m pytest tests -q" runs the backend suite.
• cd frontend && npm test runs vitest.

The backend suite needs the ML dependencies importable. app.services.embeddings imports sentence_transformers and torch at module scope, so a bare virtualenv cannot even collect the tests — in practice the container is the place to run them. backend/tests/unit/test_config.py additionally walks up to the repo root for the .env.example files, so run it with the repo root available, not just backend/ mounted.