Overview

Big-picture map of how Auth, Meta, Sync, Scrobble, and the Orchestrator fit together.

CW architecture map

This is the one page architectural overview of CrossWatch (CW).

It shows how configuration, orchestration, sync modules, metadata, and scrobbling connect.

Want setup steps, not internals? Use First-time setup.

The 5 building blocks

1. Auth: stores credentials and provider URLs in config.json.

2. Meta: resolves stable IDs (TMDb) and builds image URLs.

3. Sync modules: provider-specific read/write implementations (sync/_mod_*.py).

4. Scrobble: real-time playback events → trackers (Watcher/Webhooks).

5. Orchestrator: the runtime that loads modules, plans changes, applies writes, and persists state.

• Blueprint deep dives:

  • Orchestrator

  • Auth

  • Meta

  • Sync

  • Scrobble

High-level system diagram

Where data lives (and why)

CW keeps “truth” in two places:

• config.json: your credentials + settings (UI owned).

• state files: orchestrator and scrobble runtime memory.

Why two different state areas?

• state.json is orchestrator state. It is used for planning safely.

• .cw_state/* is scrobble/UI state. It is transient and best-effort.

Syncing: what happens in one run

The orchestrator is the “periodic batch” engine.

It is built to fail safe.

Matching: where Meta fits

Syncing and scrobbling both depend on stable IDs.

Meta exists to reduce “title + year guessing”.

Scrobbling: real-time pipeline

Scrobble is the “live stream” engine.

Watcher (recommended) polls/listens to the media server.

Webhooks (legacy) accept push events.

How the pieces reinforce each other

• Auth enables both Sync and Scrobble.

• Meta improves both Sync matching and Scrobble ID resolution.

• Scrobble keeps trackers “fresh” between sync runs.

• Sync backfills or aligns large sets safely (dry run + guardrails).

• Orchestrator is the safety boundary for destructive writes.

“Pick your path” cheat sheet

Periodic alignment

Use when you want:

• watchlist parity

• rating parity

• history backfills

Start here:

• Syncing

• Configure Pairs

Real-time plays

Use when you want:

• “Now watching”

• live progress

• fast completion updates

Start here:

• Scrobble

• Watcher

Deep dives (when you’re debugging)

• Orchestrator core: Orchestrator

• Provider contracts and quirks:

  • Sync

  • Auth

  • Meta

  • Scrobble

Want an even deeper “engine map”?

Start at Orchestrator and follow the links:

• Snapshots

• Planner

• Applier

• Guardrails

• State