potluck CLAUDE.md

Potluck — AI Context

Privacy-first personal knowledge database for your AI. Local-first: SQLite + FTS5, FastAPI + React SPA, MCP-native. v1 is a ground-up rewrite; the master plan (phases, architecture, perf budgets, locked decisions) lives in pinned GitHub issue #98 — update it as phases close.

Architecture

src/potluck/
  core/      config (pydantic-settings), paths (platformdirs), errors
  models/    Pydantic DTOs only — NO ORM
  storage/   SQLite: pragmas, single writer thread, NNN_*.sql migrations (PRAGMA user_version)
  ingest/    streaming ETL plane: readers, sources/<name>/, content-hash ledger (P1+)
  enrich/    derived-data reconciler plane: anti-join work discovery, executors (P5+)
  search/    FTS5 query builder, VecIndex protocol, hybrid RRF (P1+)
  services/  THE shared layer — plain sync functions (ctx, req) -> resp with Pydantic DTOs
  api/ mcp/ cli/   thin adapters over services (enforced by import-linter)
  testing/   synthetic generators (shipped; reused by tests, fixtures, bench)
  bench/     scenario registry, runner, compare
web/         Vite + React + TS + Tailwind + shadcn/ui (dist built in CI, served by FastAPI)

Absolute rules

1. Service-layer rule: api/, mcp/, cli/ import only services + models (+ core infrastructure) — never storage/ingest/enrich/search directly. CI enforces this (import-linter contracts in pyproject.toml).
2. No conditional imports. No optional dependencies / extras — ever. All imports top-of-file. ML dependencies become core dependencies when their phase lands. One install shape for everyone.
3. Batch-first: data paths take batches (one IN(...) dedup query + one executemany per batch); no per-item DB round-trips. Ingestion stays a single-threaded loop until a bench scenario proves otherwise.
4. All writes go through Database.write() (single writer thread owns the sole write connection); reads use the per-thread query-only connections from Database.read().
5. Pydantic DTOs at boundaries; mypy strict; avoid Any. Raise Potluck-specific exceptions from core/errors.py, adding each one only with the feature that raises it.
6. Fixtures are generated: tests/fixtures/ contains only potluck.testing generator output. The PII guard (scripts/check_fixtures.py) runs in pre-commit + CI. Never commit real export content; consult real exports locally for shape only.