# cineva-stream/cineva architecture

> Architecture diagram of the GitHub repository cineva-stream/cineva, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/cineva-stream/cineva
- Repository: https://github.com/cineva-stream/cineva

## Overview

Cineva is a Flutter streaming app for discovering movies and series, viewing details, selecting a stream, and watching through an adaptive player; it also offers live TV and local-first personalization. The graph preserves README-documented capabilities and major feature areas visible in the tree. Most Dart implementation files were not sampled, so feature-to-feature links are limited to documented workflow relationships; native Android update-check links are supported by the excerpts.

Main entry points: [`lib/shared/widgets/main_shell.dart`](https://github.com/cineva-stream/cineva/blob/main/lib/shared/widgets/main_shell.dart) (Navigation shell), [`lib/features/player/presentation/screens/player_screen.dart`](https://github.com/cineva-stream/cineva/blob/main/lib/features/player/presentation/screens/player_screen.dart) (Media player), [`lib/features/home/presentation/screens/home_screen.dart`](https://github.com/cineva-stream/cineva/blob/main/lib/features/home/presentation/screens/home_screen.dart) (Home discovery), [`lib/features/home/data/datasources/tmdb_remote_datasource.dart`](https://github.com/cineva-stream/cineva/blob/main/lib/features/home/data/datasources/tmdb_remote_datasource.dart) (TMDB catalog)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App shell"]
  node_app["Flutter app<br/>[main.dart]"]
  node_navigation["Navigation shell<br/>[main_shell.dart]"]
  node_network["Network client<br/>[dio_client.dart]"]
  node_update_worker["Android update worker"]
  node_alarm["Update alarm receiver"]
end

subgraph group_catalog["Discovery and catalog"]
  node_home["Home discovery<br/>[home_screen.dart]"]
  node_search["Search<br/>[search_screen.dart]"]
  node_metadata["TMDB catalog"]
  node_details["Media details"]
  node_calendar["Airing calendar"]
  node_collections["Collections"]
  node_people["People details"]
  node_tv_universe["TV universes"]
  node_live["Live TV"]
end

subgraph group_watch["Playback and streams"]
  node_player["Media player<br/>[player_screen.dart]"]
  node_streams["Stream providers"]
  node_subtitles["Subtitle service"]
  node_downloads["Offline downloads"]
end

subgraph group_personal["Personal features"]
  node_history[("Watch history")]
  node_watchlist[("Watchlist")]
  node_profile["Profiles"]
  node_backup["Backup and sync"]
  node_party["Watch party"]
  node_handoff["Device handoff"]
end

node_viewer(("Viewer"))
node_tmdb["TMDB service"]
node_opensubtitles["OpenSubtitles"]
node_github["GitHub releases"]

node_viewer -->|"opens"| node_app
node_app -->|"presents"| node_navigation
node_navigation -->|"browses"| node_home
node_navigation -->|"searches"| node_search
node_home -.->|"loads catalog"| node_metadata
node_search -.->|"searches catalog"| node_metadata
node_metadata -->|"requests metadata"| node_tmdb
node_home -.->|"opens media"| node_details
node_navigation -->|"views schedule"| node_calendar
node_home -.->|"browses collections"| node_collections
node_details -.->|"opens credits"| node_people
node_home -.->|"explores universes"| node_tv_universe
node_navigation -->|"watches channels"| node_live
node_details -.->|"starts playback"| node_player
node_player -.->|"loads streams"| node_streams
node_player -->|"loads subtitles"| node_subtitles
node_subtitles -->|"discovers subtitles"| node_opensubtitles
node_player -->|"saves progress"| node_history
node_navigation -->|"manages favorites"| node_watchlist
node_player -->|"saves offline"| node_downloads
node_navigation -.->|"edits profile"| node_profile
node_profile -.->|"backs up data"| node_backup
node_player -.->|"watches together"| node_party
node_player -.->|"hands off playback"| node_handoff
node_metadata -.->|"uses client"| node_network
node_update_worker -->|"checks releases"| node_github
node_alarm -->|"schedules checks"| node_update_worker

click node_app "https://github.com/cineva-stream/cineva/blob/main/lib/main.dart"
click node_navigation "https://github.com/cineva-stream/cineva/blob/main/lib/shared/widgets/main_shell.dart"
click node_home "https://github.com/cineva-stream/cineva/blob/main/lib/features/home/presentation/screens/home_screen.dart"
click node_search "https://github.com/cineva-stream/cineva/blob/main/lib/features/search/presentation/screens/search_screen.dart"
click node_metadata "https://github.com/cineva-stream/cineva/blob/main/lib/features/home/data/datasources/tmdb_remote_datasource.dart"
click node_details "https://github.com/cineva-stream/cineva/blob/main/lib/features/detail/presentation/screens/movie_detail_screen.dart"
click node_calendar "https://github.com/cineva-stream/cineva/blob/main/lib/features/calendar/presentation/screens/airing_calendar_screen.dart"
click node_collections "https://github.com/cineva-stream/cineva/blob/main/lib/features/collection/presentation/screens/collection_detail_screen.dart"
click node_people "https://github.com/cineva-stream/cineva/blob/main/lib/features/person/presentation/screens/person_detail_screen.dart"
click node_tv_universe "https://github.com/cineva-stream/cineva/blob/main/lib/features/tv_universe/presentation/screens/tv_universe_screen.dart"
click node_live "https://github.com/cineva-stream/cineva/blob/main/lib/features/live_tv/presentation/screens/live_tv_screen.dart"
click node_player "https://github.com/cineva-stream/cineva/blob/main/lib/features/player/presentation/screens/player_screen.dart"
click node_streams "https://github.com/cineva-stream/cineva/blob/main/lib/features/player/data/services/provider_loader_service.dart"
click node_subtitles "https://github.com/cineva-stream/cineva/blob/main/lib/features/player/data/services/subtitle_service.dart"
click node_downloads "https://github.com/cineva-stream/cineva/blob/main/lib/features/download/data/services/video_download_service.dart"
click node_history "https://github.com/cineva-stream/cineva/blob/main/lib/features/history/data/repositories/watch_history_repository.dart"
click node_watchlist "https://github.com/cineva-stream/cineva/blob/main/lib/features/watchlist/data/watchlist_repository.dart"
click node_profile "https://github.com/cineva-stream/cineva/blob/main/lib/features/profile/data/profile_service.dart"
click node_backup "https://github.com/cineva-stream/cineva/blob/main/lib/features/backup/data/backup_restore_service.dart"
click node_party "https://github.com/cineva-stream/cineva/blob/main/lib/features/watch_party/data/services/watch_party_service.dart"
click node_handoff "https://github.com/cineva-stream/cineva/blob/main/lib/features/sync/data/services/device_handoff_service.dart"
click node_network "https://github.com/cineva-stream/cineva/blob/main/lib/core/network/dio_client.dart"
click node_update_worker "https://github.com/cineva-stream/cineva/blob/main/android/app/src/main/kotlin/com/primadev/cineva/UpdateCheckWorker.kt"
click node_alarm "https://github.com/cineva-stream/cineva/blob/main/android/app/src/main/kotlin/com/primadev/cineva/UpdateAlarmReceiver.kt"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app,node_navigation,node_network,node_update_worker,node_alarm,node_viewer toneBlue
class node_home,node_search,node_metadata,node_details,node_calendar,node_collections,node_people,node_tv_universe,node_live toneAmber
class node_player,node_streams,node_subtitles,node_downloads toneMint
class node_history,node_watchlist,node_profile,node_backup,node_party,node_handoff toneRose
class node_tmdb,node_opensubtitles,node_github toneIndigo
```

## Components

### App shell

- [Flutter app](https://github.com/cineva-stream/cineva/blob/main/lib/main.dart): `lib/main.dart`
- [Navigation shell](https://github.com/cineva-stream/cineva/blob/main/lib/shared/widgets/main_shell.dart): `lib/shared/widgets/main_shell.dart`
- [Network client](https://github.com/cineva-stream/cineva/blob/main/lib/core/network/dio_client.dart): `lib/core/network/dio_client.dart`
- [Android update worker](https://github.com/cineva-stream/cineva/blob/main/android/app/src/main/kotlin/com/primadev/cineva/UpdateCheckWorker.kt): `android/app/src/main/kotlin/com/primadev/cineva/UpdateCheckWorker.kt`
- [Update alarm receiver](https://github.com/cineva-stream/cineva/blob/main/android/app/src/main/kotlin/com/primadev/cineva/UpdateAlarmReceiver.kt): `android/app/src/main/kotlin/com/primadev/cineva/UpdateAlarmReceiver.kt`

### Discovery and catalog

- [Home discovery](https://github.com/cineva-stream/cineva/blob/main/lib/features/home/presentation/screens/home_screen.dart): `lib/features/home/presentation/screens/home_screen.dart`
- [Search](https://github.com/cineva-stream/cineva/blob/main/lib/features/search/presentation/screens/search_screen.dart): `lib/features/search/presentation/screens/search_screen.dart`
- [TMDB catalog](https://github.com/cineva-stream/cineva/blob/main/lib/features/home/data/datasources/tmdb_remote_datasource.dart): `lib/features/home/data/datasources/tmdb_remote_datasource.dart`
- [Media details](https://github.com/cineva-stream/cineva/blob/main/lib/features/detail/presentation/screens/movie_detail_screen.dart): `lib/features/detail/presentation/screens/movie_detail_screen.dart`
- [Airing calendar](https://github.com/cineva-stream/cineva/blob/main/lib/features/calendar/presentation/screens/airing_calendar_screen.dart): `lib/features/calendar/presentation/screens/airing_calendar_screen.dart`
- [Collections](https://github.com/cineva-stream/cineva/blob/main/lib/features/collection/presentation/screens/collection_detail_screen.dart): `lib/features/collection/presentation/screens/collection_detail_screen.dart`
- [People details](https://github.com/cineva-stream/cineva/blob/main/lib/features/person/presentation/screens/person_detail_screen.dart): `lib/features/person/presentation/screens/person_detail_screen.dart`
- [TV universes](https://github.com/cineva-stream/cineva/blob/main/lib/features/tv_universe/presentation/screens/tv_universe_screen.dart): `lib/features/tv_universe/presentation/screens/tv_universe_screen.dart`
- [Live TV](https://github.com/cineva-stream/cineva/blob/main/lib/features/live_tv/presentation/screens/live_tv_screen.dart): `lib/features/live_tv/presentation/screens/live_tv_screen.dart`

### Playback and streams

- [Media player](https://github.com/cineva-stream/cineva/blob/main/lib/features/player/presentation/screens/player_screen.dart): `lib/features/player/presentation/screens/player_screen.dart`
- [Stream providers](https://github.com/cineva-stream/cineva/blob/main/lib/features/player/data/services/provider_loader_service.dart): `lib/features/player/data/services/provider_loader_service.dart`
- [Subtitle service](https://github.com/cineva-stream/cineva/blob/main/lib/features/player/data/services/subtitle_service.dart): `lib/features/player/data/services/subtitle_service.dart`
- [Offline downloads](https://github.com/cineva-stream/cineva/blob/main/lib/features/download/data/services/video_download_service.dart): `lib/features/download/data/services/video_download_service.dart`

### Personal features

- [Watch history](https://github.com/cineva-stream/cineva/blob/main/lib/features/history/data/repositories/watch_history_repository.dart): `lib/features/history/data/repositories/watch_history_repository.dart`
- [Watchlist](https://github.com/cineva-stream/cineva/blob/main/lib/features/watchlist/data/watchlist_repository.dart): `lib/features/watchlist/data/watchlist_repository.dart`
- [Profiles](https://github.com/cineva-stream/cineva/blob/main/lib/features/profile/data/profile_service.dart): `lib/features/profile/data/profile_service.dart`
- [Backup and sync](https://github.com/cineva-stream/cineva/blob/main/lib/features/backup/data/backup_restore_service.dart): `lib/features/backup/data/backup_restore_service.dart`
- [Watch party](https://github.com/cineva-stream/cineva/blob/main/lib/features/watch_party/data/services/watch_party_service.dart): `lib/features/watch_party/data/services/watch_party_service.dart`
- [Device handoff](https://github.com/cineva-stream/cineva/blob/main/lib/features/sync/data/services/device_handoff_service.dart): `lib/features/sync/data/services/device_handoff_service.dart`

### Other components

- **Viewer**
- **TMDB service**
- **OpenSubtitles**
- **GitHub releases**

## Connections

- Viewer → Flutter app: opens (evidence: `README.md`)
- Flutter app → Navigation shell: presents (evidence: `README.md`)
- Navigation shell → Home discovery: browses (evidence: `README.md`)
- Navigation shell → Search: searches (evidence: `README.md`)
- Home discovery → TMDB catalog: loads catalog
- Search → TMDB catalog: searches catalog
- TMDB catalog → TMDB service: requests metadata (evidence: `README.md`)
- Home discovery → Media details: opens media
- Navigation shell → Airing calendar: views schedule (evidence: `README.md`)
- Home discovery → Collections: browses collections
- Media details → People details: opens credits
- Home discovery → TV universes: explores universes
- Navigation shell → Live TV: watches channels (evidence: `README.md`)
- Media details → Media player: starts playback
- Media player → Stream providers: loads streams
- Media player → Subtitle service: loads subtitles (evidence: `README.md`)
- Subtitle service → OpenSubtitles: discovers subtitles (evidence: `README.md`)
- Media player → Watch history: saves progress (evidence: `README.md`)
- Navigation shell → Watchlist: manages favorites (evidence: `README.md`)
- Media player → Offline downloads: saves offline (evidence: `README.md`)
- Navigation shell → Profiles: edits profile
- Profiles → Backup and sync: backs up data
- Media player → Watch party: watches together
- Media player → Device handoff: hands off playback
- TMDB catalog → Network client: uses client
- Android update worker → GitHub releases: checks releases (evidence: `android/app/src/main/kotlin/com/primadev/cineva/UpdateCheckWorker.kt`)
- Update alarm receiver → Android update worker: schedules checks (evidence: `android/app/src/main/kotlin/com/primadev/cineva/UpdateAlarmReceiver.kt`)
