nisanray/mediatubepro

1. Overall shape: MediaTube Pro is a Flutter application with a desktop-first UI, but it still ships standard platform shells for Android, iOS, Linux, macOS, Windows, and web. The native folders are mostly thin launch/config wrappers; the app logic lives under lib/.

2. Layered architecture: The Dart code is split into core, domain, data, presentation, and routes. Dependency flow is intentionally inward: UI talks to controllers, controllers call use cases, use cases depend on repository interfaces, and the concrete repository implementations live in data/.

3. UI and navigation: lib/presentation contains the visible app surfaces: downloader, download details, history, logs, and settings. main_layout.dart plus the sidebar/topbar/right-sidebar widgets form the desktop shell, while lib/routes holds named route definitions used for GetX-style navigation.

4. Controller-driven state: Each major screen has a controller in lib/presentation/controllers. These controllers own reactive state such as queue items, filters, selected task details, logs, and settings values, and they coordinate user actions like retry, pause, cancel, open-folder, and search.

5. Use-case boundary: The domain layer models the app’s intent with DownloadTask and HistoryEntry, plus repository contracts and use cases such as start_download, cancel_download, and get_history. This keeps the business logic independent from process execution and storage details.

6. Download execution boundary: The main external integration is yt-dlp, launched from lib/data/datasources/process/ytdlp_datasource.dart. That datasource is the subprocess boundary where URL extraction, progress output, completion, and failures are translated into app events. ffmpeg is a required companion for merge/processing steps.

7. Local binary resolution: lib/core/utils/binary_locator.dart and config/constants files determine where the app finds executables. The repo expects local binaries under asset/bin/ as a bundled fallback, but settings can override the executable paths. This is a key architectural boundary because downloads cannot proceed without valid local tool paths.

8. Persistence and settings: lib/data/datasources/local/history_datasource.dart and settings_datasource.dart handle local storage of completed downloads and user preferences. Repository implementations adapt those records into domain entities and expose them to the rest of the app. The README indicates GetStorage is used for task/state persistence.

9. Queue and playlist management: download_repository_impl.dart and playlist_task_tracker.dart manage the reactive download queue, including playlist expansion and item-level tracking. This is why the UI can show per-item status, detail views, retry/cancel controls, and playlist child entries rather than treating each URL as a single opaque job.

10. History and diagnostics: Completed downloads are written into a searchable history view with metadata such as channel, thumbnail, and format. Separate logs screens capture runtime/process issues, which is important because most failures come from binary discovery, subprocess output, or merge problems rather than Flutter UI errors.

11. Shared foundation: lib/core contains app-wide constants, theme, typography, spacing, formatters, filename helpers, and exception types. These utilities keep UI styling and download metadata formatting consistent across screens.

12. Platform packages and tests: The native Android/iOS/desktop folders are standard Flutter host projects; they do not contain major business logic. The test/ folder focuses on wiring and behavior around download tasks, cancellation settings, details-page actions, and the logs controller, which matches the app’s architecture around task orchestration and local state.