Architecture

Architecture overview

TrueStream uses a layered architecture with a Flutter frontend and a Python download engine. The frontend and engine communicate through a platform-specific IPC layer.

Tech stack

Layer	Technology	Role
UI framework	Flutter with Impeller renderer	Cross-platform UI at 120fps. Single Dart codebase for Android, Windows, and Linux.
State management	Riverpod	Download queue, active downloads, settings, engine status, presets, playlists, resume.
Download engine	Python with yt-dlp (YoutubeDL class API)	Media extraction, format selection, downloading, and post-processing. Never subprocess.
Python bridge (Android)	Chaquopy	Embeds CPython 3.11 into the APK. Flutter calls Python via platform channels.
Python bridge (Desktop)	JSON over stdin/stdout	Flutter spawns Python as a managed subprocess. Structured messages over stdio.
Media processing	FFmpeg (static binary)	Muxing DASH streams, audio extraction, subtitle/thumbnail embedding, chapter splitting.
Download accelerator	aria2c (static binary, optional)	Parallel fragment downloading with configurable chunks.
Persistence	SharedPreferences	Settings, presets, playlists, auth state, cookies path.
Fonts	Instrument Sans (body), Iosevka Charon Mono (mono)	Typography via Google Fonts + TrueStreamTextStyles extension.

Layered architecture

Flutter UI Layer
    (AppShell, Home, Library, Settings + sub-screens)
        |
Riverpod State Layer
    (settings, download, engine_status, preset, playlist, resume providers)
        |
Engine Service Abstraction
    (EngineService interface: bootstrap, startDownload,
     cancelDownload, progressStream, getFormats, ...)
    |
    ├── PlatformChannelEngineService (Android via Chaquopy)
    ├── DesktopEngineService (Windows/Linux via JSON stdio)
    └── MockEngineService (testing)
        |
IPC Transport Layer
    ├── Android: MethodChannel + EventChannel
    └── Desktop: JSON-RPC over stdin/stdout
        |
Python Engine Layer
    (13 modules: paths, config, opts_builder, format_selector,
     site_profiles, downloader, hooks, errors, formats, playlist,
     bootstrap, resume, po_token)

Flutter UI layer

The Flutter layer is organized into features, each with its own screen files under lib/features/<feature>/screens/. There are 18 screens total, covering onboarding, the main shell with three tabs, settings with 10 sub-screens, and various download-related screens like the format picker and batch download interface.

Riverpod state layer

All shared state flows through Riverpod providers. Settings, presets, and playlists are persisted to SharedPreferences so they survive app restarts. Transient state, like active downloads and progress, stays in memory via a download notifier that subscribes to the engine's progress stream.

Engine service abstraction

EngineService defines a unified interface for all engine operations, from bootstrap and format fetching to download start/cancel and progress streaming. Three implementations exist: one for Android (using Chaquopy platform channels), one for desktop (using JSON over stdin/stdout), and one mock service used in testing. The correct implementation is selected automatically at runtime based on the current platform.

Python engine layer

The Python engine consists of 13 modules, each responsible for a single concern. The downloader module runs downloads in a background thread with a cancel event. The opts builder constructs yt-dlp options from user configuration. The bootstrap module handles binary downloads (FFmpeg, aria2c) with SHA-256 verification. All engine tests are written with pytest.

Navigation

The AppShell uses IndexedStack with three tabs:

• Home (Tab 0) — URL input, active downloads, format picker
• Library (Tab 1) — completed downloads, grid/list toggle
• Settings (Tab 2) — all settings grouped by section

On narrow screens (less than 600px), navigation uses a BottomNavigationBar. On wide screens (600px and above), it switches to a NavigationRail layout.

Platform selection

The engine implementation is selected automatically at startup:

• Android uses PlatformChannelEngineService with Chaquopy
• Windows and Linux use DesktopEngineService with JSON-RPC over stdin/stdout
• Other platforms (web, etc.) fall back to MockEngineService

Theme system

Colors follow the "Earth & Ethos" palette defined in DESIGN.md tokens. TrueStreamColors provides light and dark color constants used by the app theme.

• Body text uses Instrument Sans via GoogleFonts.instrumentSans()
• Monospace text (speeds, URLs, format codes) uses IosevkaCharonMono through the TrueStreamTextStyles extension on TextTheme

The app supports light, dark, and system theme modes. On Android 12+, dynamic color theming is available.

Testing

The project includes:

• 91 Python unit tests across 7 test files covering config, errors, format selection, opts building, paths, and playlists
• 3+ Flutter widget tests for screens like onboarding, settings, and navigation
• Performance audit framework with frame rate checks for all screens

Run tests with flutter test for Flutter and pytest engine/tests/ -v for Python.

GitHub Actions

Two CI workflows are available:

• Build workflow (build.yml) — manual trigger only. Builds Android APK, Windows release, and Linux release in parallel.
• Verification workflow (verify.yml) — triggers on push/PR to main. Runs flutter analyze, flutter test, and pytest engine/tests/ -v.