# 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:

```bash
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:

```dotenv
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:

```bash
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.