Terminal interface to find, download, and stream movies, TV shows, and live TV using local media players.
docs(project): scaffold documentation index and architecture
Samir Hossains12afe6000ce1
diff --git a/README.md b/README.mdindex 9d9f8b7..69ce8df 100644--- a/README.md+++ b/README.md@@ -13,6 +13,12 @@ Search, browse, play, and download movies, series, anime, and IPTV streams from</div>+## Documentation++The [`docs/`](docs/README.md) folder contains detailed documentation — architecture,+providers, players, cache, logging, TV mode, configuration, and debugging — written so+anyone can understand the project without reading the whole codebase.+## Features### Catalogs & Browsingdiff --git a/docs/README.md b/docs/README.mdnew file mode 100644index 0000000..cd1e99f--- /dev/null+++ b/docs/README.md@@ -0,0 +1,26 @@+# MovieBox-Tui Documentation++This folder documents the project so that anyone — human or AI — can understand how it+works without reading the whole codebase. Each document maps concepts to `file:line`+anchors that stay accurate as the code evolves.++## Index++| Document | What it covers | Status |+|---|---|---|+| [architecture.md](architecture.md) | Crate/module map, event loop, async model, data flow | ✅ current |+| [modules.md](modules.md) | Crate/module tree with responsibilities | ⏳ pending (lands with the app.rs split) |+| [providers.md](providers.md) | MovieBox, 4KHDHub, BDIX protocols, signing, resolvers, errors | ⏳ pending |+| [players.md](players.md) | Player detection, mpv/VLC/IINA/AndroidIntent, headers, subtitles, window sizing | ⏳ pending |+| [cache.md](cache.md) | Cache layout, namespaces, TTLs, atomic writes, purge | ⏳ pending |+| [logging.md](logging.md) | File logging, `MOVIEBOX_LOG`, rotation, sanitization, sharing logs | ⏳ pending |+| [tv-mode.md](tv-mode.md) | User-owned M3U playlists, manager, search, playback, config | ⏳ pending |+| [config.md](config.md) | `config.json` fields and `MOVIEBOX_*` environment variables | ⏳ pending |+| [downloads.md](downloads.md) | Download engine: resume, ranges, segments, retry, cancel | ⏳ pending |+| [cross-platform.md](cross-platform.md) | OS support, terminal protocols, Termux, focus handling | ⏳ pending |+| [debugging.md](debugging.md) | Reproducing issues and what to include in GitHub reports | ⏳ pending |+| [contributing.md](contributing.md) | Build, lint gate, commit conventions | ⏳ pending |+| [known-issues.md](known-issues.md) | Known limitations and how they are tracked | ⏳ pending |++> Docs marked ⏳ are written incrementally as the corresponding refactor lands, so they+> always describe the current code rather than a planned state.diff --git a/docs/architecture.md b/docs/architecture.mdnew file mode 100644index 0000000..0fce15f--- /dev/null+++ b/docs/architecture.md@@ -0,0 +1,106 @@+# Architecture++MovieBox-Tui is a terminal client (ratatui + crossterm + tokio) for streaming movies,+series and TV channels from multiple providers. This document describes the shape of the+code and how data flows through it.++## Module map++```+src/+ main.rs entry point: logging init, panic hook, raw mode,+ alternate screen, App::new + App::run+ lib.rs crate root, module declarations+ cache.rs disk cache: provider-namespaced, TTL'd, atomic writes+ download.rs download engine (resume, ranges, segments, retry)+ history.rs watch history persistence+ logging.rs file logging (rotation, sanitization)+ providers/+ mod.rs provider module tree+ models.rs shared typed models (ProviderKind, CatalogItem,+ MediaDetails, Release, PlaybackSource, …)+ moviebox/ primary provider (client + request signing)+ fourkhdhub/ 4KHDHub provider (client, hubcloud resolver, parser)+ bdix/circleftp/ BDIX CircleFTP provider+ bdix/dhakaflix/ BDIX DhakaFlix provider+ iptv_org/m3u.rs M3U playlist parser (URL and local file)+ tui/+ app/ the application object and all behavior+ mod.rs App struct, App::new, handle_action dispatcher,+ run(), draw(), config persistence+ network.rs poster fetch + provider dispatch helpers+ playback.rs player launching + playback actions+ download.rs download orchestration actions+ requests.rs search/homepage/details/preview/episode-stream actions+ navigation.rs list navigation and submit actions+ tv.rs TV mode: playlist manager + playback+ system.rs help, refresh, cache, theme, updates, focus, resize+ keyboard.rs raw key-event handling+ run.rs terminal event loop and rendering+ state.rs AppState: all UI state + in-memory LRU caches+ action.rs the Action enum (event/message model)+ event.rs EventHandler: input events + tick → Action channel+ player.rs player detection and command construction+ overlay.rs popups, pickers, notifications+ screens/ render-only modules (home, details, help, startup)+ terminal.rs terminal capability probes+ theme.rs color themes+ text.rs grapheme-safe text helpers+ updater.rs GitHub release update check+```++## The event loop++`App::run` (in `app/mod.rs`) owns the only loop:++1. If `clear_terminal_before_draw` is set, the terminal buffer is cleared.+2. If `state.dirty`, the screen is drawn (`App::draw`).+3. `tokio::select!` waits for either:+ - an `Action` from the `EventHandler` (keyboard/mouse/focus/resize/tick), or+ - an `Action` pushed by a background task (network results, downloads, posters).++`EventHandler` (`event.rs`) spawns one task that reads crossterm events and a `Tick`+interval, forwarding them into the action channel (capacity 128).++## Async model++- The tokio runtime is multi-threaded (`rt-multi-thread`).+- **State is single-threaded**: all mutations to `AppState` happen inside+ `handle_action`, which is driven by the single event-loop task. Actions are+ serialized through the channel, so there are no data races on UI state.+- **Network** uses async `reqwest` clients (one per provider) plus per-provider signing.+- **Blocking work** (disk cache reads/writes, image decoding, M3U parsing, watch-history+ save, log cleanup) runs on `tokio::task::spawn_blocking` so the event loop is never+ blocked.+- Background tasks send `Action` messages back (e.g. `SearchSuccess`,+ `EpisodeStreamsReady`, `DownloadCompleted`), which `handle_action` consumes.++## Data flow — a typical search++1. User types a query; the `Key` handler updates `search_query` and sends `Action::Search`.+2. `handle_action` resolves the active provider, dispatches to the provider client+ (async), and spawns the request in a background task.+3. On success the task sends `Action::SearchSuccess`; `handle_action` stores+ `search_results`, marks `dirty`, and writes the provider search cache.+4. Posters for result rows are fetched by background tasks and delivered via+ `SearchPosterLoaded`/`PosterSuccess`; image protocols are cached per terminal.+5. `App::draw` renders the results; `dirty` is cleared.++## Playback flow++1. User selects a result → `Action::PlayStream` (moviebox) or 4KHDHub/BDIX resolve.+2. The provider resolves a `PlaybackSource` (url + optional headers/subtitle).+3. `launch_player` builds the player command (`player.rs`), optionally downloads the+ subtitle to a temp file, and spawns the player with null stdin/stdout and piped+ stderr; a blocking task waits and reports crashes.+4. Playback is handed to mpv / VLC / IINA / Android intent per the active player.++## Configuration and persistence++- `config.json` — settings (theme, provider, auto-update, `default_player`, BDIX).+- `tv_config.json` — user M3U playlist sources (URLs or file paths).+- `history.json` — watch history.+- Cache lives under the system cache dir, keyed per provider.+- Logs live under the system data dir with rotation.++See `config.md` and `logging.md` for exact locations and formats.