97 lines
6 KiB
Markdown
97 lines
6 KiB
Markdown
|
# Cross-cutting
|
||
|
|
|
||
|
|
Components that serve multiple pillars or are infrastructure beneath them.
|
||
|
|
|
||
|
|
## Install identity (internal: fleet)
|
||
|
|
|
||
|
|
Product term: **Devices** / **install**. One operator identity + registered
|
||
|
|
devices. Not a sixth pillar — **Devices pillar** owns the registry; governor
|
||
|
|
still reads `fleet.json` until rename.
|
||
|
|
|
||
|
|
| Concern | Watch | Library | Download | Devices | Net |
|
||
|
|
|---------|-------|---------|----------|---------|-----|
|
||
|
|
| Device registry | Playback targets | Scan roots | `mediaRoot`, duties | **Owner** | `installId` on observations |
|
||
|
|
| `fleet.json` | — | — | Governor | Install config | `net.subscriptions[]` |
|
||
|
|
| Mesh join | Gate | — | Transport | **Owner UX** | Editions |
|
||
|
|
|
||
|
|
Files: `DeviceConfig.swift`, `Mesh/`, `governor/src/fleet/registry.ts`.
|
||
|
|
See [pillars/devices.md](../pillars/devices.md).
|
||
|
|
|
||
|
|
## Transport layers (not pillars)
|
||
|
|
|
||
|
|
| Layer | Used by | Note |
|
||
|
|
|-------|---------|------|
|
||
|
|
| VLC HTTP | Watch | Local control plane |
|
||
|
|
| mpv SSH IPC | Watch | Black control plane |
|
||
|
|
| HTTP bridge `:8787` | Watch, Download (iOS) | Thin client path (being thinned further by the control-plane HTTP daemon on the always-on host) |
|
||
|
|
| WireGuard overlay | Download, Net (designed) | `10.9.0.x` mesh (enables f2f_only for Net friends + Devices re-pin) |
|
||
|
|
| `friend_mesh` torrent swarms | Download bytes, Net editions, Devices re-pin | Peer route in **BitTorrentDrive** |
|
||
|
|
| **BitTorrentDrive** | Net (external) + Devices (internal) | [packages/bittorrentdrive.md](../packages/bittorrentdrive.md) |
|
||
|
|
| SSH rsync | Watch offline cache, Download re-pin | (being replaced by BTD internal for extension tier) |
|
||
|
|
|
||
|
|
Do not name transport **Net**. Net is the data product on top.
|
||
|
|
|
||
|
|
## Infra Security Surfaces (mcp, governor, bridge, ssh, daemons, HTTP, fleet serve, control-plane daemon Phase 7)
|
||
|
|
Cross-cutting infra (MCP subprocess façade, governor 24/7 daemon incl. fleet/* + future net/* tick, bridge HTTP :8787 / stdio, SSH rsync/IPC for blacktv/mpv, fleet serve HTTP peers_for/registry, Phase 7 always-on control-plane daemon) must not default-open. Current: optional bearer (serve.ts 'OFF — open', http TOKEN-empty=true); bake **mandatory** for all new (net/ daemons/bridges/serves). Path inputs: model on mcp bridge/library.ts resolveStreamId (strict realpath + roots + ext guard); extract as reusable PathGuard package for blacktv (direct play-file paths in black-tv.sh), MCP dispatch, Swift (LibraryScanner/MediaPaths prefix checks), future Net/BTD. Least-privilege ssh/sudo (review root for sockets; dedicated users); secrets (FLEET_TOKEN/BRIDGE_TOKEN mgmt, no env leakage). Untrusted data (torrents/obs/editions): strict validate + contentKey + generic errs (contrast current blacktv die "no such path"). No default-open on /health or probes where possible. Update components.md (tag new guards/net infra primary=cross or net), manifest paths, plan App C/checklist. Aligns pillars/net trust model + download peer sources (f2f_only forced). See plan.md phases 7/2/4 + packages faces for ACL separation.
|
||
|
|
|
||
|
|
## Theming (cross-cutting chrome, Watch-heavy)
|
||
|
|
|
||
|
|
See [plan.md Appendix C](../plan.md#appendix-c--best-coding-practices-pillar-separation-dry-switching-and-ui-theming) + [pillars/watch-appearance.md](../pillars/watch-appearance.md) + [pillars/settings.md](../pillars/settings.md) (cross section).
|
||
|
|
|
||
|
|
- **Not pure SwiftUI legoblocks**: Custom hybrid (SwiftUI views + AppKit NSImage sprites from real .wsz BMPs + text parsers). Exact retro fidelity (nearest-neighbor, 7-seg LED, bevels, spectrum).
|
||
|
|
- **Implementation**: ThemePalette (colors + viz + sidebarSelection) + environment(\.themePalette). WinampSkinLoader/Package/Sprites (core, data only). WinampSkinStore + custom WinampSkin*Views + PlayerView/MiniTransport conditionals on `appTheme.usesWinampChrome`. Fallback WinampComponents (built-in bevel/LED/spectrum). `merging(skin:)` for PLEDIT/VISCOLOR tint.
|
||
|
|
- **Scope**: Whole shell gets palette accents + sidebar tint (optional). Heavy chrome (transport, title bar, spectrum, LED) is Player/Watch only. iOS unaffected.
|
||
|
|
- **Persistence + API**: settings.json cross section (appTheme, winampSkinId/Name). AppLocalAPI + MCP section patches. Bundled base skin in app Resources.
|
||
|
|
- **Extension**: New sheets or built-in themes update ThemePalette + sprite consumers + tests. Always update correlation + v2/plan Appendix C.
|
||
|
|
|
||
|
|
Future control-plane HTTP daemon on the always-on host thins the Watch control plane but theming (local preference) stays in the native shells.
|
||
|
|
|
||
|
|
## Governor split
|
||
|
|
|
||
|
|
One daemon, multiple pillar jobs:
|
||
|
|
|
||
|
|
```
|
||
|
|
portable-net-tv
|
||
|
|
├── watch + keeper → Watch history + Download prefetch
|
||
|
|
└── fleet/* → Download retention + peers_for
|
||
|
|
└── (future) net/* → Net edition tick
|
||
|
|
```
|
||
|
|
|
||
|
|
## MCP / CLI bridge
|
||
|
|
|
||
|
|
`mcp/` is the subprocess façade the Swift app shells to:
|
||
|
|
|
||
|
|
- **Watch:** vlc, blacktv, display, media library, bridge stream/remote
|
||
|
|
- **Download:** transmission, search, bridge torrents, bridge fleet
|
||
|
|
|
||
|
|
Single binary, pillar-tagged domains — see [components.md](./components.md).
|
||
|
|
|
||
|
|
## Tools & release
|
||
|
|
|
||
|
|
| Script | Role |
|
||
|
|
|--------|------|
|
||
|
|
| `build-install.sh` | Dev build → install app |
|
||
|
|
| `tools/release.sh` | Tag + Forgejo release |
|
||
|
|
| `tools/update.sh` | Pull release per platform |
|
||
|
|
| `tools/platform.sh` | OS detection (single source) |
|
||
|
|
| `deploy.sh`, `mcp/deploy/` | Remote deploy helpers |
|
||
|
|
|
||
|
|
## External hosts (topology)
|
||
|
|
|
||
|
|
| Host | Typical pillars |
|
||
|
|
|------|-----------------|
|
||
|
|
| Roaming client (e.g. laptop) | Watch primary, governor, bridge |
|
||
|
|
| Central always-on host | Watch stream target, Download transmission + library root |
|
||
|
|
| Secondary always-on / seedbox | Download custody (designed) |
|
||
|
|
| vps-0 (Iceland) | Download broadcast anchor (designed) |
|
||
|
|
| iPhone | Watch + Download via bridge |
|
||
|
|
|
||
|
|
## Docs map
|
||
|
|
|
||
|
|
| Legacy | v2 lens |
|
||
|
|
|--------|---------|
|
||
|
|
| `docs/architecture.md` | All pillars + two-plane split |
|
||
|
|
| `docs/data-model.md` | State tables → [state.md](./state.md) |
|
||
|
|
| `docs/glossary.md` | Extended in [v2/glossary.md](../glossary.md) |
|
||
|
|
| `docs/roadmap.md` | Supplemented by [v2/roadmap.md](../roadmap.md) |
|
||
|
|
| `.project/history/20260608_fleet-manager-mesh-design.md` | Download + Net origin |
|