tv-anarchy/v2/docs/marketing/technical-appendix.md

Technical appendix

For builders, technical press, and HN comment depth. Consumer copy lives in 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, ../../plan.md.

---

Architecture (shipped)

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/

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

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	Net product definition
../../packages/bittorrentdrive.md	Shared drive faces
../../correlation/components.md	Repo → pillar map
../../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."