ADR 0005: Search architecture (PostGIS + Typesense)
Status: Accepted
Date: 2025-10-26
Context
Search is central to Wedissimo (finding vendors and listings by location, category, budget, etc.). We need:
- Accurate geographic filtering (circular service areas, Google Places regions)
- Fast, typo-tolerant text search with faceting
- Reliable pagination and counts (avoid hidden records due to index limits)
A pure Typesense-only or pure database-only approach would either compromise geo accuracy, full-text UX, or reliability at scale.
Decision
Adopt a hybrid two-step search architecture:
- Use PostgreSQL + PostGIS for geographic logic and accurate result sets
- Point-in-circle searches (lat/lng within a listing's service radius)
- Region-overlap searches derived from Google Places viewports
- GIST indexes on
service_centerfor performance
- Use Typesense via Laravel Scout for full-text search and faceting
- Relevance-based ranking, typo tolerance, filters, and sorting
- Combine the two depending on the query shape (see Search Guide)
- Text queries use Typesense for relevance, then apply PostGIS filtering
- Pure geographic queries use PostGIS first for counts and full access to results
- Admin search screens prefer PostgreSQL to ensure all records are visible even if the search index is lagging
Consequences
Positive
- Accurate and performant geographic search using PostGIS
- Rich full-text experience (typo tolerance, facets) via Typesense
- Reliable admin views that are not dependent on search index freshness
- Flexibility to tune behavior per endpoint (public vs admin, geo vs text-heavy)
Negative / trade-offs
- More complex implementation and mental model than a single search technology
- Requires keeping PostGIS schemas and Typesense schemas aligned with domain changes
- Operational overhead: maintaining Typesense in addition to PostgreSQL