# Overview

## CW architecture map

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

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

{% hint style="info" %}
Want setup steps, not internals? Use [First-time setup](/getting-started/first-time-setup.md).
{% endhint %}

### 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](/blueprint-architecture/orchestrator.md)
  * [Auth](/blueprint-architecture/auth.md)
  * [Meta](/blueprint-architecture/meta.md)
  * [Sync](/blueprint-architecture/sync.md)
  * [Scrobble](/blueprint-architecture/scrobble.md)

### High-level system diagram

<figure><img src="/files/OWm63FpqBJAasuLVgTAF" alt=""><figcaption></figcaption></figure>

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

<figure><img src="/files/kBZrDjwI00r0RGqrsqlL" alt=""><figcaption></figcaption></figure>

<details>

<summary>Why two different state areas?</summary>

* `state.json` is orchestrator state. It is used for planning safely.
* `.cw_state/*` is scrobble/UI state. It is transient and best-effort.

</details>

### Syncing: what happens in one run

The orchestrator is the “periodic batch” engine.

It is built to fail safe.

<figure><img src="/files/YOSMVwTLbqDCn7nHtphO" alt=""><figcaption></figcaption></figure>

### Matching: where Meta fits

Syncing and scrobbling both depend on stable IDs.

Meta exists to reduce “title + year guessing”.

<figure><img src="/files/ShzrQHJGHPnWGYO4Aznx" alt=""><figcaption></figcaption></figure>

### Scrobbling: real-time pipeline

Scrobble is the “live stream” engine.

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

Webhooks (legacy) accept push events.

<figure><img src="/files/sUhQvv6pjSm8orXIB5mW" alt=""><figcaption></figcaption></figure>

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

<figure><img src="/files/tanSyfvrAOfy9M6hdPlX" alt=""><figcaption></figcaption></figure>

### “Pick your path” cheat sheet

{% columns %}
{% column %}

#### Periodic alignment

Use when you want:

* watchlist parity
* rating parity
* history backfills

Start here:

* [Syncing](/getting-started/first-time-setup/what-do-you-need/syncing.md)
* [Configure Pairs](/crosswatch/configure-pairs.md)
  {% endcolumn %}

{% column %}

#### Real-time plays

Use when you want:

* “Now watching”
* live progress
* fast completion updates

Start here:

* [Scrobble](/crosswatch/scrobble.md)
* [Watcher](/crosswatch/scrobble/watcher.md)
  {% endcolumn %}
  {% endcolumns %}

### Deep dives (when you’re debugging)

* Orchestrator core: [Orchestrator](/blueprint-architecture/orchestrator.md)
* Provider contracts and quirks:
  * [Sync](/blueprint-architecture/sync.md)
  * [Auth](/blueprint-architecture/auth.md)
  * [Meta](/blueprint-architecture/meta.md)
  * [Scrobble](/blueprint-architecture/scrobble.md)

<details>

<summary>Want an even deeper “engine map”?</summary>

Start at Orchestrator and follow the links:

* [Snapshots](/blueprint-architecture/orchestrator/snapshots.md)
* [Planner](/blueprint-architecture/orchestrator/planner.md)
* [Applier](/blueprint-architecture/orchestrator/applier.md)
* [Guardrails](/blueprint-architecture/orchestrator/guardrails.md)
* [State](/blueprint-architecture/orchestrator/state.md)

</details>


---

# 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/overview.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.