# Technical appendix

For builders, technical press, and HN comment depth. Consumer copy lives in
[one-pager.md](./one-pager.md).

---

## Product shape

TV Anarchy is **one app shell** with pillar-owned subsystems — not three apps.

```
TV Anarchy
├── Watch      — playback, Home, Player, queue
├── Library    — catalog, scan, metadata, titles
├── Download   — search, transmission, custody
├── Net        — sync TV facts between installs (roadmap)
└── Devices    — registry, pairing, shared storage (partial)
```

Full spec: [`../../README.md`](../../README.md), [`../../plan.md`](../../plan.md).

---

## Architecture (shipped)

```mermaid
flowchart TB
    subgraph client [Mac / iOS]
        UI[SwiftUI app]
        Core[TVAnarchyCore]
    end

    subgraph data [Data plane — subprocesses]
        MCP[mcp CLI]
        Gov[governor daemon]
        Rec[recommender]
        Search[search]
    end

    subgraph targets [Playback targets]
        VLC[VLC HTTP localhost]
        MPV[mpv JSON-IPC SSH]
        QT[QuickTime AppleScript]
    end

    subgraph storage [Home storage]
        TX[transmission]
        FS[media tree]
    end

    UI --> Core
    Core --> MCP
    Core --> VLC
    Core --> MPV
    Core --> QT
    Gov --> TX
    Gov --> FS
    MCP --> Search
    MCP --> TX
    Rec --> FS
```

| Layer | Role |
|-------|------|
| **Control plane** | Native Swift — players, UI, library read path |
| **Data plane** | `mcp`, `governor`, `recommender`, `search` — no MCP in app binary |
| **Governor** | Independent daemon — watch tracking, prefetch, fleet custody |
| **State** | `~/.local/state/tv-anarchy/` — library, titles, settings, future `net/` |

---

## Net pillar (roadmap — the act-two story)

**Job:** Sync **TV Anarchy data** between installs. Not video. Not VPN. Not the
HTTP bridge.

### Vocabulary

| Term | Meaning |
|------|---------|
| **part** | Dataset type: `intro-markers`, `grouping`, `quality`, `signal`, … |
| **edition** | Versioned snapshot of a part — small torrent |
| **observation** | One install's contribution (value + confidence) |
| **merge** | Local policy → subscribed view |
| **trust** | `friends` (f2f_only) or `network` (k-anon aggregates) |

### Trust model

| Trust | Transport | Payload |
|-------|-----------|---------|
| `friends` | `f2f_only` mesh | Per-`contentKey` observations |
| `network` | Aggregated editions only | k-anon counts; no per-user rows below K |

**Privacy invariant:** observations use **contentKey** (stable content identity),
never file paths. Path keys are forbidden in Net editions.

### First shipping slice

1. **Local** — observation JSONL + merge → Player skip intro
2. **Single-fleet editions** — always-on host publishes small torrent; LAN subscriber imports
3. **Friend mesh** — cross-install subscribe when Download stage 4 ships

Schemas: [`../../schema/net/`](../../schema/net/)

### BitTorrentDrive (shared package, planned)

One engine, three faces:

| Face | Pillar | Payload |
|------|--------|---------|
| Internal | Devices | Media pins within install |
| External | Net | Edition blobs |
| Acquisition | Download | Public media swarms |

Net and Download share peer routing; they do **not** share custody logic.

---

## Library highlights (shipped)

- **Title Library** — local episode-title dataset keyed by `contentKey`; MLX/API
  on miss only.
- **LibraryDisplayNames** — canonical `S01E04 · Title` in UI, denormalized into
  `library.json`.
- **Watch state** — per-show continue watching, unified playlist queue.

---

## Platforms

| Target | Implementation |
|--------|----------------|
| macOS | SwiftUI + TVAnarchyCore |
| iOS | Bridge client → Mac/host HTTP; VLCKit local play |
| Governor | TypeScript / Bun on always-on host |
| MCP | TypeScript CLI for library, torrents, bridge |

---

## What is deliberately not in v1 GTM

| Item | Status |
|------|--------|
| Universal web client | North star (`docs/roadmap.md`) |
| Roku channel | Designed |
| Public multi-tenant service | Out of scope — installs not accounts |
| Central metadata API | Local Title Library + optional enrich |

---

## Build & verify

```sh
xcodegen generate
./run (preferred) or xcodebuild -scheme TVAnarchy -destination 'platform=macOS' build
./run test
```

Governor: `bun test` in `governor/`. Operator setup: `docs/operations.md` (not
for press distribution).

---

## Open spec index

| Doc | Contents |
|-----|----------|
| [`../../pillars/net.md`](../../pillars/net.md) | Net product definition |
| [`../../packages/bittorrentdrive.md`](../../packages/bittorrentdrive.md) | Shared drive faces |
| [`../../correlation/components.md`](../../correlation/components.md) | Repo → pillar map |
| [`../../manifest.json`](../../manifest.json) | Machine-readable index |

---

## Interview pull-quotes (technical)

> "Net is watchlog-shaped facts without exporting watchlogs — content keys only,
> trust per part."

> "Swift owns the read path for skip intro; the governor owns the 24/7 publish
tick — same split as custody today."

> "We're not rewriting Watch or Download for v2; we're adding a federation layer
for TV metadata with explicit trust boundaries."