# Leader/Follower Tournament Sync

Backend supports one-way tournament replication:

- leader tournament stays writable
- follower tournament stays read only
- leader pushes full snapshots asynchronously
- follower never pulls
- follower never needs to reach leader

This fits live topology:

- leader = local laptop / Raspberry Pi / LAN host without public IP
- follower = internet VM with public HTTPS endpoint
- only leader needs outbound access to follower

## Live Setup

### 1. Create follower tournament on remote backend

Create empty tournament with:

- `read_only_mode: true`
- `sync_auth_token: <shared secret>`

Do not send `teams` payload for follower. Backend allows empty read only follower tournament creation.

### 2. Create normal leader tournament on local backend

Create tournament as usual. This remains normal writable tournament.

### 3. Configure leader to push to follower

Update leader tournament with:

- `sync_target_url: https://remote.example/tournaments/:id/sync_state`
- `sync_auth_token: <same shared secret as follower>`

Leader becomes push source. Follower accepts only authenticated snapshot pushes.

### 4. Run tournament normally on leader

These leader-side actions enqueue async snapshot push:

- tournament updates
- timer updates
- team renames
- match state changes
- match score changes
- stage finish / playoff generation

Queue retries with backoff until follower accepts snapshot.

## Takeover

If remote must become writable after sync phase:

1. disable `read_only_mode` on follower
2. backend clears follower token when no longer needed
3. follower becomes normal standalone tournament again

After takeover, leader should no longer push to old follower URL.

## API Contract

### Leader-side writable config

Tournament push mode active when:

- `sync_target_url` present
- `sync_auth_token` present
- `read_only_mode` false

### Follower-side push receiver

Tournament accepts push when:

- `read_only_mode` true
- `sync_auth_token` present

Push endpoint:

- `PATCH /tournaments/:id/sync_state`

Auth:

- `Authorization: Bearer <token>`

Payload:

- `{ snapshot: ... }`

Snapshot import replaces tournament graph using `sync_source_id` mapping, not local DB ids.

## Frontend Integration Notes

Frontend does not need separate "follower UI mode" for normal viewers. Remote tournament should look same for non-owner users.

Owner-facing frontend can expose:

- `read_only_mode` toggle
- `sync_target_url` input
- `sync_auth_token` input
- sync health display:
  - `sync_last_pushed_at`
  - `sync_last_push_error`

Recommended owner UX:

1. create remote follower first
2. copy remote `sync_auth_token`
3. paste remote `sync_state` URL into leader
4. save leader sync config
5. show last push time / error state
6. allow explicit follower takeover by disabling `read_only_mode`

Frontend should block owner edits on follower when `read_only_mode` true. Backend already enforces this with `423 Locked`.

## Future Feature Rule

Any new persisted tournament state must be handled in three places:

1. leader write path
2. snapshot export/import path
3. follower/read-only behavior

Guardrail now exists:

- `TournamentSyncSchema` lists every synced and ignored model column
- spec fails when new DB column appears without explicit sync decision

This does not auto-implement sync for new features. It makes missing sync work fail loudly in tests instead of silently drifting.

For every new tournament feature, add:

1. schema decision in `TournamentSyncSchema`
2. snapshot builder/importer support if state must replicate
3. one follower lifecycle test or roundtrip spec that proves behavior survives sync

## Coverage Today

Current backend coverage includes:

- async push queue and retry behavior
- follower auth and read-only lock
- full follower lifecycle HTTP E2E with unrelated tournaments and mismatched ids
- team renames
- multiple decider matches
- playoff generation blocked before deciders finish
- playoff generation after deciders finish
- follower takeover
- large roundtrip graph coverage for 32 groups, 4 teams each, 64-team playoffs

Still not magic:

- if new feature adds new state and nobody updates sync contract, tests will fail
- if new feature changes behavior but not schema, add behavior test too