Repository Guidelines

Project Structure & Module Organization

cmd/similarityd/: Go REST server (/similar, /healthz, /config).
cmd/decktech/: Bubble Tea TUI for import/batching (Download, Schema, Single/Continuous, Clean, Re-embed, Config).
cmd/deckbrowser/: Bubble Tea TUI to browse/search and run similarity queries.
cmd/web/: SSR web app (search, browse, detailed card view with images/legalities/keywords/sets, all printings, similar).
scripts/: Data, embedding, ingestion, and maintenance scripts.
weaviate/: Schema (schema.json). ops/: Docker Compose for Weaviate.
docs/, README.md, ARCHITECTURE.md: Design, setup, and flows.
pkg/weaviateclient/: shared typed GraphQL client for Card queries/search.
pkg/progress/: embedding checkpoint utilities (next_offset, totals).

DB up/down: make weaviate-up / make weaviate-down
Schema: make schema-apply
Data: make data-download
Sample embed+ingest: make embed-sample ingest-sample
Continuous batches: make embed-batches BATCH=1000 (resumes via checkpoint)
Clean/restart: make clean-embeddings (wipes local batches/checkpoint; suggests DB reset)
Server: make run (uses WEAVIATE_URL)
TUIs: make tui (importer) / make browser (DB browser)
Web SSR: make web (runs on :8090)

Go: gofmt-formatted; small handlers/helpers; env via WEAVIATE_URL.
Bubble Tea: simple Update/View; stream logs with tea.Println; avoid blocking the UI.
Python: PEP 8; pure functions; avoid global state; scripts runnable standalone.
Templates: minimal HTML/CSS; avoid inline JS.
Files/dirs: lowercase with hyphens/underscores; JSON config minified unless hand-edited.

Current: manual/e2e via TUIs and web (GraphQL readiness, /similar, browse/search, similar from card pages).
Additions welcome: unit tests for cmd/similarityd (vector averaging, query building) + script fixtures for embed/extract tags.
Test naming: <package>_test.go, test_* functions; keep tests fast and deterministic.

Keep PRs small and focused; include a clear description and test evidence (commands/output snippets).
Prefer Conventional Commits: feat:, fix:, docs:, chore:, refactor:.
Link issues where applicable; note any network/download requirements (models, Docker images).

No secrets required; service uses WEAVIATE_URL (default http://localhost:8080).
Weaviate: vectorizer: none, cosine distance (see weaviate/schema.json).
Embedding config: Tags weight emphasized via EMBED_TAGS_WEIGHT (configurable in TUI).
Large downloads (models, bulk JSON) — commit only code and small configs, not data.

See ARCHITECTURE.md for diagrams and flows; core service code lives in cmd/similarityd/main.go (name lookup → vector average → nearVector). UIs: cmd/decktech, cmd/deckbrowser, cmd/web.