# itszechs/drivestream architecture

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

- Interactive diagram: https://gitdiagram.com/itszechs/drivestream
- Repository: https://github.com/itszechs/drivestream

## Overview

1. **What this repo is**
   - This is an Android streaming client for Google Drive video files.
   - The app is Kotlin-based and organized around a classic MVVM-style split between UI, view models, repositories, and data sources.

2. **Top-level module structure**
   - `app/` is the main application module and contains the Drive client, UI, persistence, and networking.
   - `mpv/` is a separate player module that wraps native `mpv` playback through JNI, with prebuilt native libraries and a Java/Kotlin-facing bridge.

3. **UI surface and navigation**
   - `MainActivity` appears to be the app shell that hosts the main navigation graph.
   - Primary screens are `HomeFragment`, `SignInFragment`, `FilesFragment`, and `SettingsFragment`.
   - Playback is split into dedicated activities: `PlayerActivity` for the ExoPlayer-based experience and `MPVActivity` for the mpv-based player.

4. **Presentation layer boundaries**
   - Each screen has a corresponding ViewModel: `HomeViewModel`, `SignInViewModel`, `FilesViewModel`, `MainViewModel`, and `PlayerViewModel`.
   - Fragments handle UI state and navigation; view models own the screen logic and call into repositories.
   - `BaseFragment` and small extension utilities suggest shared UI behaviors and navigation helpers.

5. **Drive data model and remote APIs**
   - The app’s core domain objects are `DriveFile`, `DriveClient`, and response/request models like `FilesResponse`, `DriveResponse`, `TokenRequest`, and `TokenResponse`.
   - Network access is split across three Retrofit-style APIs:
     - `DriveApi` for listing and downloading Drive content
     - `TokenApi` for OAuth token exchange/refresh
     - `GithubApi` for GitHub release metadata

6. **Repository layer**
   - `DriveRepository` coordinates Drive file listing and file access.
   - `WatchListRepository` manages local watchlist state.
   - `GithubRepository` likely powers release/update checks.
   - `TokenAuthenticator` sits at the boundary between authenticated requests and token renewal, so expired credentials can be refreshed without exposing that complexity to the UI.

7. **Authentication and session flow**
   - The app uses Google OAuth with a required Drive scope, because it must both list files and fetch file content for streaming.
   - `SessionManager` and the token-related models indicate persisted auth/session state.
   - The sign-in flow is user-driven, then the resulting token is reused by the repositories and the player networking stack.

8. **Local persistence**
   - Watchlist data is stored locally with Room via `WatchListDatabase` and `WatchListDao`.
   - `WatchList` is the persisted entity/domain model for saved or favorited files.
   - This local store is separate from Drive metadata, so user preferences survive independently of remote state.

9. **Streaming pipeline**
   - The core flow is: user browses Drive files, selects a video, then the player requests the file stream directly from Google Drive.
   - `AuthenticatingDataSource` in the player utilities is the key bridge that injects auth into media loading.
   - Supporting classes like `BufferConfig` and `CustomTrackNameProvider` suggest player tuning and playback metadata customization.

10. **Playback stack**
   - The main app references ExoPlayer and includes an FFmpeg extension AAR, so standard playback is likely the default path with broader codec support.
   - The `mpv/` module provides an alternate player implementation using native `mpv`, JNI bindings (`MPVLib`, `MPVView`), and native rendering/event code.
   - This gives the architecture two playback backends: one Android-native and one embedded native media engine.

11. **Dependency injection and app bootstrap**
   - `ThisApp` is the application class, and `ApiModule`, `AppModule`, and `DatabaseModule` indicate dependency injection wiring.
   - These modules centralize creation of network clients, repositories, and the Room database so UI code stays thin.

12. **External services and supporting concerns**
   - External dependencies that materially shape the architecture are Google Drive API for content access and GitHub API for release/update checks.
   - There are also utility layers for settings, orientation, notification keys, and theme management, which support the app shell but do not define the core data flow.

Main entry points: [`app/src/main/java/zechs/drive/stream/ui/main/MainActivity.kt`](https://github.com/itszechs/drivestream/blob/main/app/src/main/java/zechs/drive/stream/ui/main/MainActivity.kt) (MainActivity), [`app/src/main/java/zechs/drive/stream/ui/files/FilesFragment.kt`](https://github.com/itszechs/drivestream/blob/main/app/src/main/java/zechs/drive/stream/ui/files/FilesFragment.kt) (Files), [`app/src/main/java/zechs/drive/stream/ui/signin/SignInViewModel.kt`](https://github.com/itszechs/drivestream/blob/main/app/src/main/java/zechs/drive/stream/ui/signin/SignInViewModel.kt) (SignInViewModel), [`app/src/main/java/zechs/drive/stream/ui/files/FilesViewModel.kt`](https://github.com/itszechs/drivestream/blob/main/app/src/main/java/zechs/drive/stream/ui/files/FilesViewModel.kt) (FilesViewModel)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["app module"]
  node_thisapp(("ThisApp<br/>[ThisApp.kt]"))
  node_main_activity["MainActivity<br/>shell activity<br/>[MainActivity.kt]"]
  node_nav_home["Home<br/>fragment<br/>[HomeFragment.kt]"]
  node_nav_signin["Sign In<br/>fragment<br/>[SignInFragment.kt]"]
  node_nav_files["Files<br/>fragment<br/>[FilesFragment.kt]"]
  node_nav_settings["Settings<br/>fragment"]
  node_player_activity["Player<br/>activity<br/>[PlayerActivity.kt]"]
  node_mpv_activity["MPV Player<br/>activity<br/>[MPVActivity.kt]"]
  node_home_vm{{"HomeViewModel<br/>view model<br/>[HomeViewModel.kt]"}}
  node_signin_vm{{"SignInViewModel<br/>view model<br/>[SignInViewModel.kt]"}}
  node_files_vm{{"FilesViewModel<br/>view model<br/>[FilesViewModel.kt]"}}
  node_main_vm{{"MainViewModel<br/>view model<br/>[MainViewModel.kt]"}}
  node_player_vm{{"PlayerViewModel<br/>view model<br/>[PlayerViewModel.kt]"}}
  node_drive_repo[("DriveRepository<br/>[DriveRepository.kt]")]
  node_watch_repo[("WatchListRepository")]
  node_github_repo[("GithubRepository")]
  node_token_auth{{"TokenAuthenticator<br/>auth interceptor"}}
  node_drive_api["DriveApi<br/>remote api<br/>[DriveApi.kt]"]
  node_token_api["TokenApi<br/>remote api<br/>[TokenApi.kt]"]
  node_github_api["GithubApi<br/>remote api<br/>[GithubApi.kt]"]
  node_watch_db[("WatchListDB<br/>room database")]
  node_watch_dao["WatchListDao<br/>[WatchListDao.kt]"]
  node_session_mgr(("SessionManager<br/>session store<br/>[SessionManager.kt]"))
  node_auth_ds{{"Auth DataSource<br/>media datasource"}}
  node_player_utils["Player Utils<br/>player helpers<br/>[BufferConfig.kt]"]
end

subgraph group_mpv["mpv module"]
  node_mpv_lib["MPVLib<br/>jni bridge<br/>[MPVLib.java]"]
  node_mpv_view["MPVView<br/>player view<br/>[MPVView.kt]"]
end

node_thisapp -->|"starts"| node_main_activity
node_main_activity -->|"binds"| node_main_vm
node_main_activity -->|"hosts"| node_nav_home
node_main_activity -->|"hosts"| node_nav_signin
node_main_activity -->|"hosts"| node_nav_files
node_main_activity -->|"hosts"| node_nav_settings
node_nav_home -->|"uses"| node_home_vm
node_nav_signin -->|"uses"| node_signin_vm
node_nav_files -->|"uses"| node_files_vm
node_player_activity -->|"uses"| node_player_vm
node_files_vm -->|"reads"| node_drive_repo
node_files_vm -->|"writes"| node_watch_repo
node_signin_vm -->|"exchanges"| node_token_api
node_signin_vm -->|"persists"| node_session_mgr
node_drive_repo -->|"calls"| node_drive_api
node_drive_repo -->|"uses"| node_token_auth
node_token_auth -->|"refreshes"| node_token_api
node_github_repo -->|"calls"| node_github_api
node_watch_repo -->|"stores"| node_watch_db
node_watch_db -->|"exposes"| node_watch_dao
node_player_vm -->|"streams via"| node_auth_ds
node_player_vm -->|"configures"| node_player_utils
node_mpv_activity -->|"hosts"| node_mpv_view
node_mpv_view -->|"bridges"| node_mpv_lib
node_nav_files -.->|"opens"| node_player_activity
node_nav_files -.->|"opens"| node_mpv_activity

click node_thisapp "https://github.com/itszechs/drivestream/blob/main/app/src/main/java/zechs/drive/stream/ThisApp.kt"
click node_main_activity "https://github.com/itszechs/drivestream/blob/main/app/src/main/java/zechs/drive/stream/ui/main/MainActivity.kt"
click node_nav_home "https://github.com/itszechs/drivestream/blob/main/app/src/main/java/zechs/drive/stream/ui/home/HomeFragment.kt"
click node_nav_signin "https://github.com/itszechs/drivestream/blob/main/app/src/main/java/zechs/drive/stream/ui/signin/SignInFragment.kt"
click node_nav_files "https://github.com/itszechs/drivestream/blob/main/app/src/main/java/zechs/drive/stream/ui/files/FilesFragment.kt"
click node_nav_settings "https://github.com/itszechs/drivestream/blob/main/app/src/main/java/zechs/drive/stream/ui/settings/SettingsFragment.kt"
click node_player_activity "https://github.com/itszechs/drivestream/blob/main/app/src/main/java/zechs/drive/stream/ui/player/PlayerActivity.kt"
click node_mpv_activity "https://github.com/itszechs/drivestream/blob/main/app/src/main/java/zechs/drive/stream/ui/player2/MPVActivity.kt"
click node_home_vm "https://github.com/itszechs/drivestream/blob/main/app/src/main/java/zechs/drive/stream/ui/home/HomeViewModel.kt"
click node_signin_vm "https://github.com/itszechs/drivestream/blob/main/app/src/main/java/zechs/drive/stream/ui/signin/SignInViewModel.kt"
click node_files_vm "https://github.com/itszechs/drivestream/blob/main/app/src/main/java/zechs/drive/stream/ui/files/FilesViewModel.kt"
click node_main_vm "https://github.com/itszechs/drivestream/blob/main/app/src/main/java/zechs/drive/stream/ui/main/MainViewModel.kt"
click node_player_vm "https://github.com/itszechs/drivestream/blob/main/app/src/main/java/zechs/drive/stream/ui/player/PlayerViewModel.kt"
click node_drive_repo "https://github.com/itszechs/drivestream/blob/main/app/src/main/java/zechs/drive/stream/data/repository/DriveRepository.kt"
click node_watch_repo "https://github.com/itszechs/drivestream/blob/main/app/src/main/java/zechs/drive/stream/data/repository/WatchListRepository.kt"
click node_github_repo "https://github.com/itszechs/drivestream/blob/main/app/src/main/java/zechs/drive/stream/data/repository/GithubRepository.kt"
click node_token_auth "https://github.com/itszechs/drivestream/blob/main/app/src/main/java/zechs/drive/stream/data/repository/TokenAuthenticator.kt"
click node_drive_api "https://github.com/itszechs/drivestream/blob/main/app/src/main/java/zechs/drive/stream/data/remote/DriveApi.kt"
click node_token_api "https://github.com/itszechs/drivestream/blob/main/app/src/main/java/zechs/drive/stream/data/remote/TokenApi.kt"
click node_github_api "https://github.com/itszechs/drivestream/blob/main/app/src/main/java/zechs/drive/stream/data/remote/GithubApi.kt"
click node_watch_db "https://github.com/itszechs/drivestream/blob/main/app/src/main/java/zechs/drive/stream/data/local/WatchListDatabase.kt"
click node_watch_dao "https://github.com/itszechs/drivestream/blob/main/app/src/main/java/zechs/drive/stream/data/local/WatchListDao.kt"
click node_session_mgr "https://github.com/itszechs/drivestream/blob/main/app/src/main/java/zechs/drive/stream/utils/SessionManager.kt"
click node_auth_ds "https://github.com/itszechs/drivestream/blob/main/app/src/main/java/zechs/drive/stream/ui/player/utils/AuthenticatingDataSource.kt"
click node_player_utils "https://github.com/itszechs/drivestream/blob/main/app/src/main/java/zechs/drive/stream/ui/player/utils/BufferConfig.kt"
click node_mpv_lib "https://github.com/itszechs/drivestream/blob/main/mpv/src/main/java/zechs/mpv/MPVLib.java"
click node_mpv_view "https://github.com/itszechs/drivestream/blob/main/mpv/src/main/java/zechs/mpv/MPVView.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_thisapp,node_main_activity,node_nav_home,node_nav_signin,node_nav_files,node_nav_settings,node_player_activity,node_mpv_activity,node_home_vm,node_signin_vm,node_files_vm,node_main_vm,node_player_vm,node_drive_repo,node_watch_repo,node_github_repo,node_token_auth,node_drive_api,node_token_api,node_github_api,node_watch_db,node_watch_dao,node_session_mgr,node_auth_ds,node_player_utils toneBlue
class node_mpv_lib,node_mpv_view toneAmber
```

## Components

### app module

Main Android application with UI, data, and DI.

- [ThisApp](https://github.com/itszechs/drivestream/blob/main/app/src/main/java/zechs/drive/stream/ThisApp.kt): application · Application bootstrap and global setup. · `app/src/main/java/zechs/drive/stream/ThisApp.kt`
- [MainActivity](https://github.com/itszechs/drivestream/blob/main/app/src/main/java/zechs/drive/stream/ui/main/MainActivity.kt): shell activity · App shell hosting primary navigation. · `app/src/main/java/zechs/drive/stream/ui/main/MainActivity.kt`
- [Home](https://github.com/itszechs/drivestream/blob/main/app/src/main/java/zechs/drive/stream/ui/home/HomeFragment.kt): fragment · Landing screen for browsing and entry flows. · `app/src/main/java/zechs/drive/stream/ui/home/HomeFragment.kt`
- [Sign In](https://github.com/itszechs/drivestream/blob/main/app/src/main/java/zechs/drive/stream/ui/signin/SignInFragment.kt): fragment · OAuth sign-in screen and session entry. · `app/src/main/java/zechs/drive/stream/ui/signin/SignInFragment.kt`
- [Files](https://github.com/itszechs/drivestream/blob/main/app/src/main/java/zechs/drive/stream/ui/files/FilesFragment.kt): fragment · Drive file browser and selection screen. · `app/src/main/java/zechs/drive/stream/ui/files/FilesFragment.kt`
- [Settings](https://github.com/itszechs/drivestream/blob/main/app/src/main/java/zechs/drive/stream/ui/settings/SettingsFragment.kt): fragment · App configuration and preference screen. · `app/src/main/java/zechs/drive/stream/ui/settings/SettingsFragment.kt`
- [Player](https://github.com/itszechs/drivestream/blob/main/app/src/main/java/zechs/drive/stream/ui/player/PlayerActivity.kt): activity · Primary ExoPlayer-based playback activity. · `app/src/main/java/zechs/drive/stream/ui/player/PlayerActivity.kt`
- [MPV Player](https://github.com/itszechs/drivestream/blob/main/app/src/main/java/zechs/drive/stream/ui/player2/MPVActivity.kt): activity · Alternate playback activity backed by mpv. · `app/src/main/java/zechs/drive/stream/ui/player2/MPVActivity.kt`
- [HomeViewModel](https://github.com/itszechs/drivestream/blob/main/app/src/main/java/zechs/drive/stream/ui/home/HomeViewModel.kt): view model · Home screen logic and state. · `app/src/main/java/zechs/drive/stream/ui/home/HomeViewModel.kt`
- [SignInViewModel](https://github.com/itszechs/drivestream/blob/main/app/src/main/java/zechs/drive/stream/ui/signin/SignInViewModel.kt): view model · Sign-in flow state and token exchange orchestration. · `app/src/main/java/zechs/drive/stream/ui/signin/SignInViewModel.kt`
- [FilesViewModel](https://github.com/itszechs/drivestream/blob/main/app/src/main/java/zechs/drive/stream/ui/files/FilesViewModel.kt): view model · File listing, filtering, and user actions. · `app/src/main/java/zechs/drive/stream/ui/files/FilesViewModel.kt`
- [MainViewModel](https://github.com/itszechs/drivestream/blob/main/app/src/main/java/zechs/drive/stream/ui/main/MainViewModel.kt): view model · App-level navigation and shell state. · `app/src/main/java/zechs/drive/stream/ui/main/MainViewModel.kt`
- [PlayerViewModel](https://github.com/itszechs/drivestream/blob/main/app/src/main/java/zechs/drive/stream/ui/player/PlayerViewModel.kt): view model · Playback state and media preparation. · `app/src/main/java/zechs/drive/stream/ui/player/PlayerViewModel.kt`
- [DriveRepository](https://github.com/itszechs/drivestream/blob/main/app/src/main/java/zechs/drive/stream/data/repository/DriveRepository.kt): repository · Coordinates Drive listing and file access. · `app/src/main/java/zechs/drive/stream/data/repository/DriveRepository.kt`
- [WatchListRepository](https://github.com/itszechs/drivestream/blob/main/app/src/main/java/zechs/drive/stream/data/repository/WatchListRepository.kt): repository · Persists and serves local watchlist state. · `app/src/main/java/zechs/drive/stream/data/repository/WatchListRepository.kt`
- [GithubRepository](https://github.com/itszechs/drivestream/blob/main/app/src/main/java/zechs/drive/stream/data/repository/GithubRepository.kt): repository · Fetches release metadata and update info. · `app/src/main/java/zechs/drive/stream/data/repository/GithubRepository.kt`
- [TokenAuthenticator](https://github.com/itszechs/drivestream/blob/main/app/src/main/java/zechs/drive/stream/data/repository/TokenAuthenticator.kt): auth interceptor · Refreshes expired credentials for authenticated requests. · `app/src/main/java/zechs/drive/stream/data/repository/TokenAuthenticator.kt`
- [DriveApi](https://github.com/itszechs/drivestream/blob/main/app/src/main/java/zechs/drive/stream/data/remote/DriveApi.kt): remote api · Retrofit API for Drive listing and streaming. · `app/src/main/java/zechs/drive/stream/data/remote/DriveApi.kt`
- [TokenApi](https://github.com/itszechs/drivestream/blob/main/app/src/main/java/zechs/drive/stream/data/remote/TokenApi.kt): remote api · OAuth token exchange and refresh endpoints. · `app/src/main/java/zechs/drive/stream/data/remote/TokenApi.kt`
- [GithubApi](https://github.com/itszechs/drivestream/blob/main/app/src/main/java/zechs/drive/stream/data/remote/GithubApi.kt): remote api · Release metadata lookup from GitHub. · `app/src/main/java/zechs/drive/stream/data/remote/GithubApi.kt`
- [WatchListDB](https://github.com/itszechs/drivestream/blob/main/app/src/main/java/zechs/drive/stream/data/local/WatchListDatabase.kt): room database · Room persistence for saved files. · `app/src/main/java/zechs/drive/stream/data/local/WatchListDatabase.kt`
- [WatchListDao](https://github.com/itszechs/drivestream/blob/main/app/src/main/java/zechs/drive/stream/data/local/WatchListDao.kt): dao · Database access for watchlist records. · `app/src/main/java/zechs/drive/stream/data/local/WatchListDao.kt`
- [SessionManager](https://github.com/itszechs/drivestream/blob/main/app/src/main/java/zechs/drive/stream/utils/SessionManager.kt): session store · Persists sign-in and token session state. · `app/src/main/java/zechs/drive/stream/utils/SessionManager.kt`
- [Auth DataSource](https://github.com/itszechs/drivestream/blob/main/app/src/main/java/zechs/drive/stream/ui/player/utils/AuthenticatingDataSource.kt): media datasource · Injects authorization into player media loading. · `app/src/main/java/zechs/drive/stream/ui/player/utils/AuthenticatingDataSource.kt`
- [Player Utils](https://github.com/itszechs/drivestream/blob/main/app/src/main/java/zechs/drive/stream/ui/player/utils/BufferConfig.kt): player helpers · Buffering and track-name customization helpers. · `app/src/main/java/zechs/drive/stream/ui/player/utils/BufferConfig.kt`

### mpv module

Native mpv player wrapper and JNI bridge.

- [MPVLib](https://github.com/itszechs/drivestream/blob/main/mpv/src/main/java/zechs/mpv/MPVLib.java): jni bridge · Java-facing bridge into native mpv. · `mpv/src/main/java/zechs/mpv/MPVLib.java`
- [MPVView](https://github.com/itszechs/drivestream/blob/main/mpv/src/main/java/zechs/mpv/MPVView.kt): player view · Kotlin view wrapper for mpv rendering. · `mpv/src/main/java/zechs/mpv/MPVView.kt`

## Connections

- ThisApp → MainActivity: starts · Bootstraps the app shell.
- MainActivity → MainViewModel: binds · Main activity observes shell state.
- MainActivity → Home: hosts · Primary navigation destination.
- MainActivity → Sign In: hosts · Authentication entry screen.
- MainActivity → Files: hosts · File browsing destination.
- MainActivity → Settings: hosts · Settings destination.
- Home → HomeViewModel: uses · Home UI state and actions.
- Sign In → SignInViewModel: uses · Sign-in workflow logic.
- Files → FilesViewModel: uses · File list state and actions.
- Player → PlayerViewModel: uses · Playback screen logic.
- FilesViewModel → DriveRepository: reads · Requests Drive metadata and items.
- FilesViewModel → WatchListRepository: writes · Updates local saved items.
- SignInViewModel → TokenApi: exchanges · Obtains and refreshes OAuth tokens.
- SignInViewModel → SessionManager: persists · Stores authenticated session state.
- DriveRepository → DriveApi: calls · Fetches Drive data and streams.
- DriveRepository → TokenAuthenticator: uses · Ensures authenticated requests remain valid.
- TokenAuthenticator → TokenApi: refreshes · Renews access tokens when needed.
- GithubRepository → GithubApi: calls · Checks release metadata.
- WatchListRepository → WatchListDB: stores · Uses Room database for persistence.
- WatchListDB → WatchListDao: exposes · DAO access to watchlist entities.
- PlayerViewModel → Auth DataSource: streams via · Loads Drive media with auth headers.
- PlayerViewModel → Player Utils: configures · Applies buffering and track naming helpers.
- MPV Player → MPVView: hosts · Embeds native mpv rendering view.
- MPVView → MPVLib: bridges · Delegates playback control to JNI layer.
- Files → Player: opens · Launches standard playback.
- Files → MPV Player: opens · Launches alternate mpv playback.
