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