DevRunbook-Public/adr/ADR-004-postgres-search-first.md

ADR-004 — PostgreSQL search before semantic infrastructure

Status

Accepted

Context

The library requires fast title, tag, category and intent search with filters. A vector database adds operational complexity and less explainable ranking.

Decision

Use PostgreSQL full-text search plus structured filters and optional trigram matching. Add semantic search only after measured unmet discovery needs.

Consequences

• one datastore and simple self-hosting;
• explainable matching;
• adequate scale for initial catalog and private content;
• synonyms and curated intent terms need content governance;
• future embedding index remains possible behind a search port.