back_end_oudelaa/docs/SEARCH_ARCHITECTURE.md

Search architecture

The public API contract is unchanged:

• GET /api/v1/search
• GET /api/v1/search/users
• GET /api/v1/search/posts
• GET /api/v1/search/hashtags
• GET /api/v1/search/suggestions

The existing q, type, page, limit, and sortOrder query parameters and all response and pagination shapes remain compatible with existing clients.

Search engines

SEARCH_ENGINE accepts:

• auto (default): use Atlas Search and automatically use compatibility search if Atlas Search or its indexes are unavailable.
• atlas: prefer Atlas Search. With SEARCH_FALLBACK_ENABLED=true, service remains available during an Atlas Search failure.
• regex: use the original MongoDB regex implementation only.

When Atlas Search fails, the service logs one warning and waits SEARCH_ATLAS_RETRY_SECONDS before retrying it. Requests continue through the compatibility implementation during that interval.

Ranking

User ranking combines:

1. Exact username relevance.
2. Username, stage name, and display name autocomplete relevance.
3. One-character typo tolerance for queries of at least three characters.
4. Whether the viewer follows the result.
5. Whether the viewer recently liked or saved posts from the result.
6. Verification and a logarithmic follower-count boost.

Post ranking combines:

1. Content, hashtag, style, maqam, and rhythm relevance.
2. Typo tolerance for queries of at least four characters.
3. Follow and recent interaction affinity with the author.
4. A logarithmic engagement boost.
5. A seven-day recency decay.

Blocked users, disabled authors, deleted or archived posts, moderation state, and visibility are hard filters. They never become ranking signals and cannot be bypassed by a high search score.

Atlas Search index deployment

The index definitions are stored in:

• ops/atlas-search/users_search.json
• ops/atlas-search/posts_search.json

Set MONGODB_URI to the target Atlas database and run:

npm run search:sync-indexes

The script creates missing indexes and updates existing indexes using SEARCH_ATLAS_USER_INDEX and SEARCH_ATLAS_POST_INDEX. Atlas builds indexes asynchronously; SEARCH_ENGINE=auto continues using compatibility search until they become queryable.

Recommended production configuration:

SEARCH_ENGINE=auto
SEARCH_ATLAS_USER_INDEX=users_search
SEARCH_ATLAS_POST_INDEX=posts_search
SEARCH_FALLBACK_ENABLED=true
SEARCH_ATLAS_RETRY_SECONDS=300

For local MongoDB Community development, keep auto for production parity or use regex to suppress the initial Atlas capability check.

Verification

Run:

npm run build
npm test -- --runInBand src/modules/search/search.service.spec.ts

The tests verify response compatibility, Atlas result ordering, privacy clauses, and fallback retry throttling.