tv-anarchy/v2/README.md

TVAnarchy v2 — pillar model

TVAnarchy is organized into product pillars. Everything in the repo maps to one primary pillar, plus cross-pillar settings (theme) and infrastructure (transport, tooling). One app shell hosts all pillar UI.

TVAnarchy
├── Watch      — playback + Home/Player UX
├── Library    — catalog, scan, metadata, grouping
├── Download   — media over BitTorrent (get + keep alive)
├── Net        — TVAnarchy data from other installs (friends → network)
└── Devices    — registry, install pairing, shared media volume

Settings: each pillar owns its section; cross owns theme and shell chrome (pillars/settings.md).

Watch and Download are largely shipped. Net is specified here; code lands in a later stage (see roadmap.md).

All three pillars have UI inside one app — not three apps. Watch and Download each get sidebar tabs; Net uses Settings + Player hooks (see correlation/ui.md).

Docs

Doc	Contents
pillars/watch.md	Playback, Home, Player
pillars/library.md	Catalog, scan, metadata, grouping
pillars/library-display.md	Canonical episode display names
pillars/library-titles.md	Title Library dataset + MLX M2
pillars/download.md	Torrents, custody, governor
pillars/net.md	Federated data editions
pillars/devices.md	Device registry, install pairing
pillars/devices-storage.md	Shared media volume, extension warmup
pillars/settings.md	Per-pillar + cross settings model
pillars/watch-appearance.md	Themes, Winamp .wsz (cross chrome)
correlation/components.md	Full repo → pillar map
correlation/state.md	Config + state files by pillar
correlation/ui.md	macOS + iOS surfaces by pillar + nav details
correlation/cross-cutting.md	Fleet, transport, tools + theming notes
glossary.md	Pillar-aware terms
roadmap.md	Phase checklist (short)
plan.md	Full v1 → v2 build plan (phases, PRs, tests, risks, Appendix C: best practices / pillar sep DRY / switching / theming)
features.md	Feature state comparison table (v1 vs v2: complete / partial / exists)
docs/marketing/	Press & GTM kit (one-pager, demo script, founder post, FAQ, releases)
packages/bittorrentdrive.md	Shared drive: Net external, Devices internal
manifest.json	Machine-readable correlation index

New in this build-out: plan.md Appendix C thoroughly documents best coding practices, how pillars achieve separation while staying DRY (packages + faces + pattern reuse + correlation as spec), how pillar "switching" works (single RootView sidebar + selection-driven detail + subnav), and UI theming (custom hybrid sprite system, not SwiftUI legoblocks; no Godot/Rust). Update these when nav or chrome changes.

How pillars interact

flowchart TB
    subgraph library [Library]
        Cat[Catalog + metadata]
    end
    subgraph watch [Watch]
        Play[Player + Home]
    end
    subgraph devices [Devices]
        Reg[Device registry]
        Vol[Shared media volume]
    end
    subgraph download [Download]
        Acq[Search + Transmission]
        Custody[Custody + Reaper]
    end
    subgraph net [Net]
        Parts[Parts + editions]
    end

    Acq -->|completed files| Cat
    Vol -->|logical paths| Cat
    Cat --> Play
    Reg --> Vol
    Parts -->|grouping, intro-markers| Cat
    Parts -->|intro-markers| Play
    Play -->|extended warmup| Vol
    Play -->|watchlog| Parts
    Custody --> Vol
    subgraph drive [BitTorrentDrive package]
        Int[internal face]
        Ext[external face]
    end
    Vol --> Int
    Parts --> Ext

Feature State Comparison: v1 vs v2

See the dedicated v2/features.md for the full feature state comparison table (v1 vs v2, with states complete / partial / exists).

Legacy docs

Pre-v2 cross-cutting docs remain in ../docs/ (architecture, data-model, operations, roadmap). v2 is the organizational lens; it does not replace operational runbooks until explicitly migrated.

Clarity during transition (no v1/v2 code split)

Per the plan (v2/plan.md §1 and Appendix C): v2 uses a lens (pillars + correlation/* + manifest.json) on the existing single codebase, not a structural v1/ or v2/ folder move in Sources/ (that would create the exact legacy baggage the plan rejects).

Use these for "clear v1 vs v2 view":

• correlation/components.md + state.md + ui.md: every component tagged by primary pillar (e.g. Mesh/* = cross under Devices pillar; DeviceConfig = Devices).
• manifest.json: machine-readable pillar index.
• pillars/*.md + glossary.md: the product model (e.g. Devices pillar owns "install" as group term; "fleet" is internal only).
• Code comments now point back to v2/ (see recent alignments in FleetState, MeshEnrollController, DeviceConfig, MeshJoinView).
• v2/features.md + roadmap.md: exact shipped vs in-progress state.

This gives the separation/clarity benefit without forking the tree. Update correlation/ + this README + pillar comments in the same change as any new code.

v2 directory layout (this tree)

v2 directory layout (this tree)

v2/
├── README.md                 ← you are here
├── manifest.json             ← pillar tags for every component
├── glossary.md
├── roadmap.md
├── pillars/                  ← product definition per pillar
│   └── watch-appearance.md   ← Winamp .wsz (Watch sub-spec)
├── correlation/              ← repo inventory mapped to pillars
├── features.md               ← v1 vs v2 feature state table (complete/partial/exists)
├── packages/                 ← shared engines (not pillars) — [packages/README.md](./packages/README.md)
│   ├── README.md             ← full catalog
│   └── bittorrentdrive.md    ← Net external + Devices internal faces
└── schema/net/               ← Net part schemas (first Net slice)

Future implementation code for Net may live under v2/net/ or the top-level net/ package once the first part ships; schemas are defined now so Watch and Download can subscribe without renaming.