Overview
:::info Source
Sourced from services/search-service/SERVICE_OVERVIEW.md in the documentation repo.
:::
Bounded context: Search (Supporting domain). Read-side projection over many authoritative domains. Companion docs: DOMAIN_MODEL.md · API_CONTRACTS.md · EVENT_SCHEMAS.md · DATA_MODEL.md · AI_INTEGRATION.md
1. Mission
Provide one unified, tenant-isolated, low-latency discovery surface across every piece of content, person, and artifact on the Ghasi-edTech platform. Two query shapes converge here: lexical full-text (OpenSearch) and semantic vector (pgvector via ai-gateway-service). A hybrid ranker blends the two. A recommendation engine on top of the same corpus drives "continue learning," "next step," and marketplace discovery.
Search is never authoritative. Every record is a projection of an event from a domain service. The source service owns the truth; search-service owns the index, the ranker, and the recommendation model.
2. Responsibilities
| Responsibility | In scope | Out of scope |
|---|---|---|
| Full-text search across courses, lessons, blocks, listings, users, assignments, certificates | yes | authoring drafts not yet saved |
| Semantic (embedding) search | yes | generating embeddings (delegated to ai-gateway) |
| Hybrid lexical+semantic ranking | yes | learn-to-rank model training (offline job) |
| Autocomplete / suggest | yes | spell-correction dictionary ownership (shipped with index) |
| Personalized recommendations | yes | deciding who sees what (authorization = identity/enrollment) |
| Reindex / backfill | yes | event log retention (NATS JetStream) |
| Tenant isolation of query surface | yes | tenant CRUD (owned by tenant-service) |
| Taxonomy & facet aggregations | yes | taxonomy authoring (owned by catalog-service) |
3. Upstream / Downstream Map
4. Service-Level Objectives
| SLO | Target | Window |
|---|---|---|
| Query latency p50 (lexical) | ≤ 80 ms | rolling 7d |
| Query latency p95 (lexical) | ≤ 250 ms | rolling 7d |
| Query latency p95 (hybrid) | ≤ 450 ms | rolling 7d |
| Autocomplete latency p95 | ≤ 120 ms | rolling 7d |
| Recommendation latency p95 | ≤ 300 ms | rolling 7d |
| Indexing lag (event → searchable) p95 | ≤ 2 s | rolling 24h |
| Availability | 99.9% | rolling 30d |
| NDCG@10 on interaction-labeled set | ≥ 0.72 | rolling 30d |
| Recommendation CTR lift vs baseline | ≥ +15% | rolling 30d |
5. Readiness Trajectory
| Milestone | Level | Functional scope |
|---|---|---|
| M1 | L1 – walking skeleton | OpenSearch stood up; single-tenant lexical search on course titles |
| M2 | L2 | Multi-tenant index aliases; taxonomy + facet filters; autocomplete |
| M3 | L3 | Semantic embeddings live; basic hybrid ranker; reindex tooling |
| M4 | L4 – production | Full hybrid ranker + recommendations; offline prefetch; L2R retraining |
| M5 | L4+ | AI query expansion v2; multi-locale embeddings; on-device semantic fallback |
6. Functional Slices
| Slice | Milestone | Description |
|---|---|---|
| S2 | M2 | Basic full-text over courses + lessons with tenant filter |
| S4 | M3 | Taxonomy filters + autocomplete; listing + user search |
| S5 | M4 | Hybrid semantic + lexical + personalized recommendations |
| S6 (stretch) | M5 | Offline semantic search with on-device micro-model |
7. Non-Goals
- Not a data warehouse — aggregate reporting goes to analytics-service.
- Not a knowledge graph — taxonomy relations belong to catalog-service.
- Not an AI inference host — all embeddings routed through ai-gateway-service.
- Not authoritative for any entity — every record is a projection.
8. Why a Dedicated Service
Denormalized search columns across eight domain databases would couple every service to OpenSearch schema changes, leak tenant boundaries, and force every domain team to learn L2R and vector maths. Isolating search as a read-side service:
- Lets us swap engines (OpenSearch ↔ Vespa ↔ Typesense) without ripple effects.
- Centralizes the tenant filter — every query is attributable to one place.
- Keeps embedding model governance (versions, cost, PII scrubbing) within ai-gateway-service while search-service just consumes the vector API.
- Creates a natural home for the recommendation engine, which needs cross-domain context anyway.
9. Team & Ownership
| Role | Owner |
|---|---|
| Engineering DRI | Search platform team |
| Product DRI | Discovery PM |
| On-call rotation | Platform SRE (primary), Search team (secondary) |
| Architecture review | Architecture council, quarterly |