# Blueprint Architecture

- [Overview](https://wiki.crosswatch.app/blueprint-architecture/overview.md): Big-picture map of how Auth, Meta, Sync, Scrobble, and the Orchestrator fit together.
- [Orchestrator](https://wiki.crosswatch.app/blueprint-architecture/orchestrator.md): How the orchestrator runtime loads providers, plans changes, applies writes, and persists state safely.
- [Snapshots](https://wiki.crosswatch.app/blueprint-architecture/orchestrator/snapshots.md): How the orchestrator builds, normalizes, and caches provider snapshots (indices), including canonical keys, checkpoints, and drop-guard safety.
- [Blackbox](https://wiki.crosswatch.app/blueprint-architecture/orchestrator/blackbox.md): Quarantine noisy “flapping” items so runs stay safe, quiet, and cheap.
- [One-way sync](https://wiki.crosswatch.app/blueprint-architecture/orchestrator/one-way-sync.md): Exact one-way pipeline (src → dst) used by the orchestrator for one feature run, including guardrails and state writes.
- [Two-way sync](https://wiki.crosswatch.app/blueprint-architecture/orchestrator/two-way-sync.md): Exact two-way pipeline (A ↔ B), including tombstones, observed deletions, and guarded removal propagation.
- [Guardrails](https://wiki.crosswatch.app/blueprint-architecture/orchestrator/guardrails.md): Safety mechanisms that prevent transient provider issues from becoming destructive writes.
- [State](https://wiki.crosswatch.app/blueprint-architecture/orchestrator/state.md): Where CrossWatch stores orchestrator baselines, checkpoints, and guardrail internals on disk.
- [Applier](https://wiki.crosswatch.app/blueprint-architecture/orchestrator/applier.md): Write engine that executes provider adds/removes, chunks batches, and normalizes results.
- [Planner](https://wiki.crosswatch.app/blueprint-architecture/orchestrator/planner.md): Diff engine that compares two snapshots and produces add/remove plans.
- [Tombstones](https://wiki.crosswatch.app/blueprint-architecture/orchestrator/tombstones.md): Deletion memory that prevents re-add loops and enables safer delete propagation in two-way sync.
- [Unresolved](https://wiki.crosswatch.app/blueprint-architecture/orchestrator/unresolved.md): Records per-item apply failures so the orchestrator can stop retrying known-bad items.
- [Phantom Guard](https://wiki.crosswatch.app/blueprint-architecture/orchestrator/phantom-guard.md): Watchlist anti-flap guard that blocks “ghost adds” that don’t stick on the destination.
- [Scope](https://wiki.crosswatch.app/blueprint-architecture/orchestrator/scope.md): How pair scoping prevents guardrail state and cache files from bleeding across pairs and modes.
- [Eventing](https://wiki.crosswatch.app/blueprint-architecture/orchestrator/eventing.md): Structured events and log conventions used by the orchestrator and UI during runs.
- [Runtime](https://wiki.crosswatch.app/blueprint-architecture/orchestrator/runtime.md): Runtime config knobs for debug output, snapshot caching, chunking, and telemetry warnings.
- [Conflicts](https://wiki.crosswatch.app/blueprint-architecture/orchestrator/conflicts.md): Two-way conflict resolution for ratings, adds vs deletes, and ambiguous “missing” states.
- [Blocklists](https://wiki.crosswatch.app/blueprint-architecture/orchestrator/blocklists.md): How tombstones, blackbox, and unresolved block planned adds to prevent repeated failures.
- [Health](https://wiki.crosswatch.app/blueprint-architecture/orchestrator/health.md): Provider health checks and how they gate pairs, features, and safe write behavior.
- [Chunking](https://wiki.crosswatch.app/blueprint-architecture/orchestrator/chunking.md): How write batches are split and throttled to reduce rate limits and failure blast radius.
- [Caching layers](https://wiki.crosswatch.app/blueprint-architecture/orchestrator/caching-layers.md): Where snapshots can get stale across orchestrator caching, baselines, and provider-side caches.
- [State.json](https://wiki.crosswatch.app/blueprint-architecture/orchestrator/state-json.md): On-disk schema and semantics of /config/state.json (baselines, checkpoints, manual policy, metrics).
- [Provider contract](https://wiki.crosswatch.app/blueprint-architecture/orchestrator/provider-contract.md): Contract providers implement so the orchestrator can snapshot, plan, and apply changes safely.
- [Provider specifics](https://wiki.crosswatch.app/blueprint-architecture/orchestrator/provider-specifics.md): Real-world provider quirks that affect IDs, freshness, consistency, and write confirmations.
- [Auth](https://wiki.crosswatch.app/blueprint-architecture/auth.md): Internal docs for auth provider modules used by Settings → Authentication.
- [Registry](https://wiki.crosswatch.app/blueprint-architecture/auth/registry.md): Discovers auth provider modules and exposes manifests and HTML blocks to the UI/API.
- [\_auth\_ANILIST](https://wiki.crosswatch.app/blueprint-architecture/auth/_auth_anilist.md): Internal AniList auth provider module (OAuth flow + token storage).
- [\_auth\_base](https://wiki.crosswatch.app/blueprint-architecture/auth/_auth_base.md): Internal base classes and shared helpers for auth provider implementations.
- [\_auth\_EMBY](https://wiki.crosswatch.app/blueprint-architecture/auth/_auth_emby.md): Internal Emby auth provider module (server URL + access token handling).
- [\_auth\_JELLYFIN](https://wiki.crosswatch.app/blueprint-architecture/auth/_auth_jellyfin.md): Internal Jellyfin auth provider module (server URL + access token handling).
- [\_auth\_MDBLIST](https://wiki.crosswatch.app/blueprint-architecture/auth/_auth_mdblist.md): Internal MDBList auth provider module (API key handling).
- [\_auth\_PLEX](https://wiki.crosswatch.app/blueprint-architecture/auth/_auth_plex.md): Internal Plex auth provider module (PIN/device auth and token storage).
- [\_auth\_SIMKL](https://wiki.crosswatch.app/blueprint-architecture/auth/_auth_simkl.md): Internal SIMKL auth provider module (device PIN flow and token refresh handling).
- [\_auth\_TAUTULLI](https://wiki.crosswatch.app/blueprint-architecture/auth/_auth_tautulli.md): Internal Tautulli auth provider module (server URL + API key handling).
- [\_auth\_TMDB](https://wiki.crosswatch.app/blueprint-architecture/auth/_auth_tmdb.md): Internal TMDb (Sync) auth provider module (API key + session flow).
- [\_auth\_TRAKT](https://wiki.crosswatch.app/blueprint-architecture/auth/_auth_trakt.md): Internal Trakt auth provider module (device PIN flow and token refresh handling).
- [Meta](https://wiki.crosswatch.app/blueprint-architecture/meta.md): Internal docs for metadata modules that resolve IDs and enrich items (TMDb).
- [Registry](https://wiki.crosswatch.app/blueprint-architecture/meta/registry.md): Internal registry that discovers metadata modules and exposes manifests to the app.
- [\_meta\_TMDB](https://wiki.crosswatch.app/blueprint-architecture/meta/_meta_tmdb.md): Internal TMDb metadata module (ID resolution and poster/backdrop URL support).
- [Sync](https://wiki.crosswatch.app/blueprint-architecture/sync.md): Low-level sync provider modules under sync/ (used by the Orchestrator).
- [Engine-level features](https://wiki.crosswatch.app/blueprint-architecture/sync/engine-level-features.md): Shared feature semantics the orchestrator uses across providers.
- [History](https://wiki.crosswatch.app/blueprint-architecture/sync/engine-level-features/history.md): Watched-state feature. Uses watched\_at timestamps when available.
- [Ratings](https://wiki.crosswatch.app/blueprint-architecture/sync/engine-level-features/ratings.md): Rating feature. Syncs rating values plus rated\_at when available.
- [Watchlist](https://wiki.crosswatch.app/blueprint-architecture/sync/engine-level-features/watchlist.md): Set-like feature used for “plan to watch” lists.
- [\_mod\_ANILIST](https://wiki.crosswatch.app/blueprint-architecture/sync/_mod_anilist.md): Sync module for AniList (GraphQL). Watchlist only.
- [overview](https://wiki.crosswatch.app/blueprint-architecture/sync/_mod_anilist/overview.md): AniList sync module overview (capabilities and key behaviors).
- [watchlist](https://wiki.crosswatch.app/blueprint-architecture/sync/_mod_anilist/watchlist.md): AniList watchlist feature implementation (anime watchlist reads and writes).
- [ratings](https://wiki.crosswatch.app/blueprint-architecture/sync/_mod_anilist/ratings.md): AniList ratings feature implementation (if enabled) and behavior.
- [history](https://wiki.crosswatch.app/blueprint-architecture/sync/_mod_anilist/history.md): AniList history feature implementation (if enabled) and behavior.
- [\_mod\_CROSSWATCH](https://wiki.crosswatch.app/blueprint-architecture/sync/_mod_crosswatch.md): Local file-backed tracker(watchlist/history/ratings).
- [overview](https://wiki.crosswatch.app/blueprint-architecture/sync/_mod_crosswatch/overview.md): CrossWatch local provider sync module overview (snapshots, restore, and persistence).
- [watchlist](https://wiki.crosswatch.app/blueprint-architecture/sync/_mod_crosswatch/watchlist.md): CrossWatch local provider watchlist feature (file-backed set semantics).
- [ratings](https://wiki.crosswatch.app/blueprint-architecture/sync/_mod_crosswatch/ratings.md): CrossWatch local provider ratings feature (file-backed ratings store).
- [history](https://wiki.crosswatch.app/blueprint-architecture/sync/_mod_crosswatch/history.md): CrossWatch local provider history feature (file-backed watched events store).
- [\_mod\_EMBY](https://wiki.crosswatch.app/blueprint-architecture/sync/_mod_emby.md): Sync module for Emby (MediaBrowser API).
- [overview](https://wiki.crosswatch.app/blueprint-architecture/sync/_mod_emby/overview.md): Emby sync module overview (capabilities, setup links, and matching notes).
- [watchlist](https://wiki.crosswatch.app/blueprint-architecture/sync/_mod_emby/watchlist.md): Emby watchlist feature implementation (favorites/playlist modes and writes).
- [ratings](https://wiki.crosswatch.app/blueprint-architecture/sync/_mod_emby/ratings.md): Emby ratings feature implementation and limitations.
- [history](https://wiki.crosswatch.app/blueprint-architecture/sync/_mod_emby/history.md): Emby history feature implementation (watched state indexing and writes).
- [progress](https://wiki.crosswatch.app/blueprint-architecture/sync/_mod_emby/progress.md): Emby progress feature implementation (resume position indexing and writes).
- [\_mod\_JELLYFIN](https://wiki.crosswatch.app/blueprint-architecture/sync/_mod_jellyfin.md): Sync engine module for Jellyfin (watchlist/history indexing and writes).
- [overview](https://wiki.crosswatch.app/blueprint-architecture/sync/_mod_jellyfin/overview.md): Jellyfin sync module overview (capabilities, setup links, and matching notes).
- [watchlist](https://wiki.crosswatch.app/blueprint-architecture/sync/_mod_jellyfin/watchlist.md): Jellyfin watchlist feature implementation (favorites/playlist modes and write behavior).
- [ratings](https://wiki.crosswatch.app/blueprint-architecture/sync/_mod_jellyfin/ratings.md): Jellyfin ratings feature implementation and limitations.
- [history](https://wiki.crosswatch.app/blueprint-architecture/sync/_mod_jellyfin/history.md): Jellyfin history feature implementation (watched state indexing and writes).
- [progress](https://wiki.crosswatch.app/blueprint-architecture/sync/_mod_jellyfin/progress.md): Jellyfin progress feature implementation (resume position indexing and writes).
- [\_mod\_MDBLIST](https://wiki.crosswatch.app/blueprint-architecture/sync/_mod_mdblist.md): Sync engine module for MDBList (watchlist/history/ratings indexing and writes).
- [overview](https://wiki.crosswatch.app/blueprint-architecture/sync/_mod_mdblist/overview.md): MDBList sync module overview (capabilities, setup links, and rate-limit notes).
- [watchlist](https://wiki.crosswatch.app/blueprint-architecture/sync/_mod_mdblist/watchlist.md): MDBList watchlist feature implementation (indexing and batch writes).
- [ratings](https://wiki.crosswatch.app/blueprint-architecture/sync/_mod_mdblist/ratings.md): MDBList ratings feature implementation (indexing and batch writes).
- [history](https://wiki.crosswatch.app/blueprint-architecture/sync/_mod_mdblist/history.md): MDBList history feature implementation (watched/unwatched writes and pagination).
- [\_mod\_PLEX](https://wiki.crosswatch.app/blueprint-architecture/sync/_mod_plex.md): Sync engine module for Plex (watchlist/history/ratings indexing and writes).
- [overview](https://wiki.crosswatch.app/blueprint-architecture/sync/_mod_plex/overview.md): Plex sync module overview (capabilities, setup links, and matching behavior).
- [watchlist](https://wiki.crosswatch.app/blueprint-architecture/sync/_mod_plex/watchlist.md): Plex watchlist feature implementation (Discover-driven reads and writes).
- [ratings](https://wiki.crosswatch.app/blueprint-architecture/sync/_mod_plex/ratings.md): Plex ratings feature implementation (indexing and rating writes).
- [history](https://wiki.crosswatch.app/blueprint-architecture/sync/_mod_plex/history.md): Plex history feature implementation (watched-state indexing and writes).
- [progress](https://wiki.crosswatch.app/blueprint-architecture/sync/_mod_plex/progress.md): Plex progress feature implementation (resume position indexing and writes).
- [\_mod\_SIMKL](https://wiki.crosswatch.app/blueprint-architecture/sync/_mod_simkl.md): Sync engine module for SIMKL (activity-based indexing and batch writes).
- [overview](https://wiki.crosswatch.app/blueprint-architecture/sync/_mod_simkl/overview.md): SIMKL sync module overview (activities/watermarks, caching, and rate-limit notes).
- [watchlist](https://wiki.crosswatch.app/blueprint-architecture/sync/_mod_simkl/watchlist.md): SIMKL watchlist feature implementation (indexing and batch writes).
- [ratings](https://wiki.crosswatch.app/blueprint-architecture/sync/_mod_simkl/ratings.md): SIMKL ratings feature implementation (indexing, scale behavior, and writes).
- [history](https://wiki.crosswatch.app/blueprint-architecture/sync/_mod_simkl/history.md): SIMKL history feature implementation (watched events indexing and writes).
- [\_mod\_TAUTULLI](https://wiki.crosswatch.app/blueprint-architecture/sync/_mod_tautulli.md): Sync engine module for Tautulli (Plex history import support).
- [overview](https://wiki.crosswatch.app/blueprint-architecture/sync/_mod_tautulli/overview.md): Tautulli sync module overview (history import behavior and limitations).
- [watchlist](https://wiki.crosswatch.app/blueprint-architecture/sync/_mod_tautulli/watchlist.md): Tautulli watchlist feature placeholder and notes (if supported).
- [ratings](https://wiki.crosswatch.app/blueprint-architecture/sync/_mod_tautulli/ratings.md): Tautulli ratings feature placeholder and notes (if supported).
- [history](https://wiki.crosswatch.app/blueprint-architecture/sync/_mod_tautulli/history.md): Tautulli history feature implementation (Plex play history import).
- [\_mod\_TMDB](https://wiki.crosswatch.app/blueprint-architecture/sync/_mod_tmdb.md): Sync engine module for TMDb account sync (watchlist/ratings indexing and writes).
- [overview](https://wiki.crosswatch.app/blueprint-architecture/sync/_mod_tmdb/overview.md): TMDb sync module overview (account sync behavior and limitations).
- [watchlist](https://wiki.crosswatch.app/blueprint-architecture/sync/_mod_tmdb/watchlist.md): TMDb watchlist feature implementation (account watchlist reads and writes).
- [ratings](https://wiki.crosswatch.app/blueprint-architecture/sync/_mod_tmdb/ratings.md): TMDb ratings feature implementation (account ratings reads and writes).
- [history](https://wiki.crosswatch.app/blueprint-architecture/sync/_mod_tmdb/history.md): TMDb history feature notes (if supported) and behavior.
- [\_mod\_TRAKT](https://wiki.crosswatch.app/blueprint-architecture/sync/_mod_trakt.md): Sync engine module for Trakt (watchlist/history/ratings indexing and writes).
- [overview](https://wiki.crosswatch.app/blueprint-architecture/sync/_mod_trakt/overview.md): Trakt sync module overview (ETag caching, batching, and rate-limit notes).
- [watchlist](https://wiki.crosswatch.app/blueprint-architecture/sync/_mod_trakt/watchlist.md): Trakt watchlist feature implementation (indexing, ETag caching, and batch writes).
- [ratings](https://wiki.crosswatch.app/blueprint-architecture/sync/_mod_trakt/ratings.md): Trakt ratings feature implementation (indexing and batch writes).
- [history](https://wiki.crosswatch.app/blueprint-architecture/sync/_mod_trakt/history.md): Trakt history feature implementation (watched events indexing and writes).
- [Scrobble](https://wiki.crosswatch.app/blueprint-architecture/scrobble.md): Internal blueprint for the scrobble pipeline (event parsing, filtering, and sink dispatch).
- [Sink](https://wiki.crosswatch.app/blueprint-architecture/scrobble/sink.md): Scrobble sink modules that send playback events to trackers (Trakt, SIMKL, MDBList).
- [Sink: SIMKL](https://wiki.crosswatch.app/blueprint-architecture/scrobble/sink/sink-simkl.md): Scrobble sink implementation for sending playback events to SIMKL.
- [Sink: Trakt](https://wiki.crosswatch.app/blueprint-architecture/scrobble/sink/sink-trakt.md): Scrobble sink implementation for sending playback events to Trakt.
- [Sink: MDBList](https://wiki.crosswatch.app/blueprint-architecture/scrobble/sink/sink-mdblist.md): Scrobble sink implementation for sending playback events to MDBList.
- [Providers](https://wiki.crosswatch.app/blueprint-architecture/scrobble/providers.md): Scrobble provider modules that produce playback events (Plex, Jellyfin, Emby).
- [Watch: PLEX](https://wiki.crosswatch.app/blueprint-architecture/scrobble/providers/watch-plex.md): Scrobble provider implementation for Plex (live sessions and playback events).
- [Watch: Jellyfin](https://wiki.crosswatch.app/blueprint-architecture/scrobble/providers/watch-jellyfin.md): Scrobble provider implementation for Jellyfin (live sessions and playback events).
- [Watch: Emby](https://wiki.crosswatch.app/blueprint-architecture/scrobble/providers/watch-emby.md): Scrobble provider implementation for Emby (live sessions and playback events).
- [Webhooks](https://wiki.crosswatch.app/blueprint-architecture/scrobble/webhooks.md): Legacy webhook-based scrobble integrations (deprecated; use Watcher when possible).
- [Webhook: embytrakt](https://wiki.crosswatch.app/blueprint-architecture/scrobble/webhooks/webhook-embytrakt.md): Legacy webhook bridge for Emby → Trakt scrobbling (deprecated).
- [Webhook: jellyfintrakt](https://wiki.crosswatch.app/blueprint-architecture/scrobble/webhooks/webhook-jellyfintrakt.md): Legacy webhook bridge for Jellyfin → Trakt scrobbling (deprecated).
- [Webhook: plextrakt](https://wiki.crosswatch.app/blueprint-architecture/scrobble/webhooks/webhook-plextrakt.md): Legacy webhook bridge for Plex → Trakt scrobbling (deprecated).
- [Services](https://wiki.crosswatch.app/blueprint-architecture/scrobble/services.md): Scrobble service helpers and state files under /config/.cw\_state (now playing, auto-remove, etc.).
- [Overview](https://wiki.crosswatch.app/blueprint-architecture/scrobble/services/overview.md): Overview of scrobble service state files under /config/.cw\_state, including currently\_watching and auto-remove dedupe.
- [Auto remove watchlist](https://wiki.crosswatch.app/blueprint-architecture/scrobble/services/auto-remove-watchlist.md): How Watcher can auto-remove items from watchlists on completion (and how it dedupes deletes).
- [Currently watching](https://wiki.crosswatch.app/blueprint-architecture/scrobble/services/currently-watching.md): State file format and behavior for the “currently watching” scrobble output.
- [API](https://wiki.crosswatch.app/blueprint-architecture/api.md): Use the CrossWatch REST API from your own self-hosted instance. Includes base URL and the OpenAPI reference link.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://wiki.crosswatch.app/blueprint-architecture.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.