FLX

FLX is a personal media platform focused on making a very large local media library feel immediate, predictable, and pleasant to use. The MVP spike is a proof of concept and a production-quality foundation, not a feature-complete Plex replacement.

MVP goals

• Browse and search a roughly 140 TB library with extremely low perceived latency.
• Blazing-fast search with useful ranking and incremental results.
• First-class clients for Google TV, tvOS, and Web.
• Preserve the cleanest path to later Android and iOS support.
• Maximize shared product code without forcing identical playback implementations on every platform.
• Smooth playback across a wide codec/container range.
• Feature and playback outcome parity across required platforms.
• Direct play whenever possible, remux or transcode only when necessary.
• Intel Quick Sync and NVIDIA hardware acceleration are MVP requirements.
• Verification, benchmarks, timing, resource accounting, metrics, logs, traces, diagnostics, and failure evidence are foundation features.

Foundation

FLX is Elixir-first and Rust-ready.

• Elixir/OTP + Phoenix + Bandit own the living system, API, orchestration, supervision, sessions, scheduling, and control-plane logic.
• SQLite + Ecto are canonical application state for the MVP. SQLite FTS5 is the initial search engine.
• FFmpeg and ffprobe remain external media executables. FLX supervises them rather than embedding libav into the BEAM.
• MuonTrap is the preferred OS-process boundary for FFmpeg so process trees can be contained, killed, and accounted for with cgroup v2 where available.
• Hardware acceleration is modeled as capability providers, not hard-coded platform branches. Intel QSV, NVIDIA NVDEC/NVENC/CUDA, and software fallback must be actively probed and proven.
• Rust is deliberately kept behind replaceable seams for scanning, search, fingerprinting, watching, and other hot loops if benchmarks justify it.
• Quinn-style verification, property/state-machine testing, runtime oracles, and failure injection are expected from the start.
• Telemetry is the canonical event bus. Logger is the canonical logging API. OpenTelemetry is used primarily for traces until its Erlang metrics/logs story is mature enough to adopt without coupling the application.
• Tidewave is a dev-only runtime introspection tool for Phoenix development.

Clients

The current client direction is React + TypeScript with React Native TV/Expo for Google TV and tvOS, React Native Web/Expo Web for shared UI where appropriate, and narrow platform playback adapters. The product codebase is shared aggressively, but platform-native playback is allowed and expected when it produces a better result.

Architectural rules

1. Source media is immutable. FLX never modifies the original files.
2. Canonical state is precious; search indexes, derivatives, thumbnails, transcode caches, and hardware capability caches are rebuildable projections.
3. Media identity is not a filesystem path. Files may move without becoming new media.
4. Playback planning is pure domain logic with serializable, versioned plans.
5. Live playback belongs to OTP supervision; durable background work belongs to a durable job system.
6. Hardware support is proven with executable probes, not inferred from FFmpeg build flags.
7. Media bytes should not flow through ordinary BEAM messages unless there is a compelling measured reason.
8. Cross-cutting semantics for logs, metrics, and traces are defined once and reused.
9. Performance claims require benchmarks and recorded evidence.
10. New native/Rust code must enter through an explicit contract rather than leaking through domain modules.

Planned operator/developer commands

• mix verify: deterministic tests, property tests, state machines, contract tests, boundary checks, and runtime oracles.
• mix bench: repeatable benchmark scenarios with machine-readable results and environment fingerprints.
• mix doctor: executable environment and hardware certification, including real QSV/NVIDIA smoke probes.

These commands are architectural commitments, not yet implemented.

Documentation

• architecture.md describes the system shape and boundaries.
• AGENTS.md defines working rules for humans and coding agents.
• adrs/ records expensive-to-reverse architectural decisions.