# Meilisearch Index Sync

## Objective

Keep a Meilisearch index current so search, filters, and sorting reflect the live data.

A background sync that mirrors app records into a Meilisearch index, with attribute configuration, batched updates, and a swap-based rebuild.

## Before You Begin

This feature is being added to an application that already exists and already
works. Do not scaffold a new project, and do not assume a blank slate.

Inspect the codebase first and establish:

- The existing application structure and where code of this kind already lives.
- The framework and version in use.
- The existing design system — colours, spacing, typography, and component conventions.
- Existing UI components you can reuse instead of writing new ones.
- The existing database structure, if this feature needs to persist anything.
- The existing authentication and authorization system, if this feature is user-scoped.
- Dependencies already installed, so you don't add a library that duplicates one.
- The existing test setup and conventions.

Only start writing code once you understand the above. If the application
already implements part of this feature, extend it rather than replacing it.

## Implementation Instructions

1. Declare the searchable, filterable, and sortable attributes as configuration that is applied before the first query relies on them, and re-apply it as part of deploy or rebuild. An attribute that is queried but not configured will silently return nothing useful.
2. Batch changes through the app's existing background-job system and treat every write as asynchronous: record the task the engine returns, poll it to completion, and only mark the record synced once the engine confirms it. Do not assume a successful submission means the document is queryable.
3. Compose the tenant and permission constraint on the server for every search and never merge a filter expression supplied by the client. A user who can inject a filter clause can read outside their workspace.
4. Perform schema and attribute changes by indexing into a second index and swapping it into place once it is fully populated, so queries are never served by a half-built index.
5. Typesense Index Sync is the same feature for a different engine, and the surrounding search UI, ranking, and result rendering belong to the app's existing search screens. This brief owns only the pipeline from record to index; do not rebuild the search interface here.

## UI and UX Requirements

Match the application's existing design system exactly. Reuse its components,
spacing, and typography. This feature should look like it was always there.

## Responsive Requirements

Works on mobile, tablet, and desktop. Touch targets are large enough to hit on a
phone, and nothing overflows horizontally at 320px.

## Accessibility Requirements

- Fully keyboard navigable.
- Correct semantic elements and ARIA roles.
- Visible focus states.
- Meets WCAG AA contrast.
- Dynamic changes are announced to screen readers.
- Respects prefers-reduced-motion.

## Edge Cases

- Queries that filter or sort on an attribute the index was never configured for return misleading results rather than an error, so verify the attribute configuration at boot and fail loudly when it drifts from what the code expects.
- Tenant isolation has to live outside anything the user controls. Filters assembled from query parameters, or passed straight through from the browser, are the standard way this leaks across customers.
- Because updates are processed asynchronously, a user who saves and immediately searches may not see their own change. Track the engine's task state, retry the ones that fail, and surface a short indexing delay rather than pretending the write was instant.
- Deletes and permission changes must remove documents, not merely stop linking to them. A record that is unshared, archived, or soft-deleted while its index entry survives is still discoverable by title and snippet.
- Schema changes must be zero-downtime: build the replacement index alongside the live one, verify counts and sample queries, then swap, keeping the old index available to swap back.
- Batches that exceed the engine's payload or document size limits must be split, and a single oversized document must be truncated or skipped with a logged reason instead of failing its whole batch.
- Rate limiting and a queue backlog after an outage need bounded retries with exponential backoff and jitter, plus a dead-letter path for documents that fail repeatedly.
- When the engine is down, degrade to a database-backed query with a visible notice about reduced result quality. An empty page reads to the user as an absence of data.

## Testing

Exercise the feature end to end in the running application. Cover every edge case
above, then run the existing test suite and confirm nothing regressed.

## Acceptance Criteria

- [ ] Searchable, filterable, and sortable attributes are configured declaratively and verified before queries depend on them.
- [ ] Record changes reach the index through background jobs whose asynchronous tasks are tracked to completion.
- [ ] Tenant scoping is enforced server-side and no client-supplied filter expression reaches the engine.
- [ ] Deleted records and records the user has lost access to disappear from results promptly.
- [ ] An index rebuild or schema change swaps in without search downtime and can be reverted.
- [ ] Failed and oversized documents land in a dead-letter path with a reason instead of blocking the queue.
- [ ] An engine outage degrades to database search with an explicit notice rather than an empty state.
- [ ] The feature matches the existing design system.
- [ ] No existing functionality is broken.

## Adaptation Rules

- Match the existing design system. Do not introduce a new colour palette,
  spacing scale, or component library.
- Reuse existing components and utilities wherever they fit.
- Follow the naming, file layout, and code style already present.
- Do not upgrade, replace, or remove existing dependencies to make this
  feature fit. Adapt the feature to the app, not the app to the feature.
- Do not break existing functionality. If a change is genuinely required in
  existing code, make the smallest one that works and say so.
- If something in these instructions conflicts with how the application is
  built, follow the application and explain the deviation.

## Final Verification

Before you report the work as done:

1. Re-read the acceptance criteria above and check each one against what you
   actually built.
2. Run the application and exercise the feature end to end.
3. Run the existing test suite and confirm you have broken nothing.
4. Check the feature on mobile, tablet, and desktop widths.
5. Check keyboard navigation and focus handling.
6. Summarize what changed: files added, files modified, and anything you
   deliberately did differently because of how this application is built.

If any acceptance criterion is unmet, fix it before reporting completion.