Search architecture

The data model behind Vetrix search: what every OpenSearch document carries, how the indexes are mapped and queried, which actor may see which hit, and which legacy HTTP routes remain mounted only for back-compat. These pages are the contract the indexers, the query builders and the auth filter are all written against.

Data model and access control

• ACL-aware OpenSearch index schema — The authoritative document schema. Defines the common ACL field block carried by every index (repo_id, the legacy is_private boolean alongside the three-tier visibility enum, owner_id, collaborator_user_ids, group_ids, and the page-only share_token), the additive per-entity fields for code, symbols, issues, merge requests, comments and pages, the ingest-pipeline rejection rules, the ban on null_value for ACL arrays, the Postgres source-of-truth query for each field, the denormalisation caps and their overflow booleans, the per-event staleness SLAs, the doc-side/query-side split for group grants versus group membership, the page lifecycle and cascade hooks, the seven-clause page visibility predicate with its minimum_should_match: 1 latch, the degraded-mode Postgres fallback response contract, and the synchronous revoke fast-path.
• Search permission matrix — The actor × repo-visibility × entity table of expected HIT/MISS outcomes (owner, collaborator, group member, non-member, admin and anonymous), plus the page-scoped addenda for explicit page grants and share-token access. Records which cells are pinned today by the clause-level unit tests and the hostile non-member regressions, and the shape of the deferred live-cluster matrix that would exercise the same cells over a real cluster and the Postgres fallback as a parity gate.

Indexes and endpoints

• OpenSearch index mappings and query patterns — The copy-verbatim reference for rebuilding indexes by hand: the two custom analyzers (code_analyzer for identifier splitting, path_analyzer for path prefixes) with worked tokenisation examples, the full dynamic: "strict" mapping JSON for vetrix-code, vetrix-symbols, vetrix-issues / vetrix-mrs and vetrix-pages, the per-environment shard and replica strategy with its app.toml overrides, the query DSL emitted for each search endpoint with its filter/aggregation/highlight blocks, and the dual-write, shadow-query, flag-cutover and cleanup phases that move search off the Postgres ILIKE and tsvector implementation.
• Deprecated search endpoints — The deprecation contract for legacy search routes: the route keeps serving traffic, the handler doc-comment names its replacement, no new feature work lands on it, and removal waits on telemetry showing negligible external traffic. Carries the status table for every search route and the per-endpoint detail for the deprecated per-type code search, the type-ahead suggest route and the Postgres page-search route — including which frontend callers were retired, what is still consumed internally, and the removal criteria for each.