# leaflet-search notes

## deployment
- **backend**: push to `main` touching `backend/**` → auto-deploys via GitHub Actions
- **frontend**: manual deploy from `site/` directory (`cd site && wrangler pages deploy . --project-name leaflet-search`)
- **tap**: manual deploy from `tap/` directory (`fly deploy --app leaflet-search-tap`)

## remotes
- `origin`: tangled.sh:zzstoatzz.io/leaflet-search
- `github`: github.com/zzstoatzz/leaflet-search (CI runs here)
- push to both: `git push origin main && git push github main`

## architecture
- **backend** (Zig): HTTP API, FTS5 search, vector similarity
- **tap**: firehose sync via bluesky-social/indigo tap
- **site**: static frontend on Cloudflare Pages
- **db**: Turso (source of truth) + local SQLite read replica (FTS queries)

## platforms
- leaflet, pckt, offprint, greengale, whitewind: known platforms
- leaflet/pckt/offprint/greengale detected via basePath; whitewind via `com.whtwnd.*` collection
- other: site.standard.* documents not from a known platform

## search ranking
- hybrid BM25 + recency: `ORDER BY rank + (days_old / 30)`
- OR between terms for recall, prefix on last word
- unicode61 tokenizer (non-alphanumeric = separator)

## tap operations
- from `tap/` directory: `just check` (status), `just turbo` (catch-up), `just normal` (steady state)
- see `docs/tap.md` for memory tuning and debugging

## zig dependencies
- update a dependency hash: `zig fetch --save <url>` (fetches and updates build.zig.zon automatically)

## MCP server
- hosted: `claude mcp add-json pub-search '{"type": "http", "url": "https://pub-search-by-zzstoatzz.fastmcp.app/mcp"}'`
- local dev: `cd mcp && uv run pytest` for tests
- deployed on fastmcp.app

## common tasks
- check indexing: `curl -s https://leaflet-search-backend.fly.dev/api/dashboard | jq`