# tinypinglite/sakuramedia architecture

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

- Interactive diagram: https://gitdiagram.com/tinypinglite/sakuramedia
- Repository: https://github.com/tinypinglite/sakuramedia

## Overview

SakuraMedia is a Flutter client for discovering, tracking, importing, organizing, and watching a personal media library across desktop and mobile platforms. The principal workflow runs from discovery or subscription through resource acquisition and library import, then into playback and personal collections. Feature directories show the client’s domain boundaries; the README documents several backend-driven workflows and optional integrations, but sampled source does not establish detailed client-side call wiring, so links below reflect documented flows rather than inferred implementation calls.

Main entry points: [`lib/routes`](https://github.com/tinypinglite/sakuramedia/tree/main/lib/routes) (Navigation), [`lib/features/subscriptions`](https://github.com/tinypinglite/sakuramedia/tree/main/lib/features/subscriptions) (Subscriptions), [`lib/features/media`](https://github.com/tinypinglite/sakuramedia/tree/main/lib/features/media) (Media Management), [`lib/features/movies/presentation/controllers/player`](https://github.com/tinypinglite/sakuramedia/tree/main/lib/features/movies/presentation/controllers/player) (Playback)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client Shell"]
  node_app["App Shell<br/>[app.dart]"]
  node_routes["Navigation"]
end

subgraph group_discover["Discovery and Tracking"]
  node_search["Search"]
  node_actors["Actor Discovery"]
  node_rankings["Rankings"]
  node_tags["Tags"]
  node_subscriptions["Subscriptions"]
  node_image_search["Image Search"]
end

subgraph group_library["Library Operations"]
  node_movies["Movie Catalog"]
  node_videos["Video Library"]
  node_media_import["Media Import"]
  node_media["Media Management"]
end

subgraph group_watch["Playback and Collections"]
  node_player["Playback"]
  node_external_player["External Player"]
  node_playlists["Playlists"]
  node_moments["Moments"]
  node_clips["Clips"]
  node_collections["Collections"]
  node_clip_collections["Clip Collections"]
end

subgraph group_operations["Tasks and Extensions"]
  node_activity["Tasks and Notices"]
  node_plugins["Plugin Management"]
end

node_user(("Media User"))
node_backend["SakuraMedia Backend"]
node_download_provider["Download Provider"]
node_storage_provider[("Storage Provider")]
node_notification_channel["Notification Channel"]

node_user -->|"uses"| node_app
node_app -->|"navigates"| node_routes
node_routes -->|"opens"| node_search
node_routes -->|"opens"| node_actors
node_routes -->|"opens"| node_rankings
node_routes -->|"opens"| node_tags
node_routes -->|"opens"| node_subscriptions
node_routes -->|"opens"| node_movies
node_routes -->|"opens"| node_videos
node_routes -->|"opens"| node_media_import
node_routes -->|"opens"| node_media
node_routes -->|"opens"| node_image_search
node_routes -->|"opens"| node_player
node_routes -->|"opens"| node_playlists
node_routes -->|"opens"| node_moments
node_routes -->|"opens"| node_clips
node_routes -->|"opens"| node_collections
node_routes -->|"opens"| node_clip_collections
node_routes -->|"opens"| node_activity
node_routes -->|"opens"| node_plugins
node_search -->|"queries"| node_backend
node_actors -->|"queries"| node_backend
node_rankings -->|"loads rankings"| node_backend
node_tags -->|"loads tags"| node_backend
node_subscriptions -->|"submits subscriptions"| node_backend
node_subscriptions -->|"finds resources"| node_download_provider
node_download_provider -->|"writes downloads"| node_storage_provider
node_storage_provider -->|"provides media"| node_media_import
node_media_import -->|"imports metadata"| node_backend
node_media -->|"manages library"| node_backend
node_media -->|"migrates media"| node_storage_provider
node_image_search -.->|"searches images"| node_backend
node_movies -->|"loads catalog"| node_backend
node_videos -->|"loads media"| node_backend
node_player -->|"requests streams"| node_backend
node_player -.->|"launches playback"| node_external_player
node_playlists -->|"saves lists"| node_backend
node_moments -->|"saves moments"| node_backend
node_clips -->|"saves clips"| node_backend
node_collections -->|"loads collections"| node_backend
node_clip_collections -->|"loads collections"| node_backend
node_activity -->|"loads task status"| node_backend
node_backend -.->|"dispatches notices"| node_notification_channel
node_plugins -->|"configures extensions"| node_backend

click node_app "https://github.com/tinypinglite/sakuramedia/blob/main/lib/app/app.dart"
click node_routes "https://github.com/tinypinglite/sakuramedia/tree/main/lib/routes"
click node_search "https://github.com/tinypinglite/sakuramedia/tree/main/lib/features/search"
click node_actors "https://github.com/tinypinglite/sakuramedia/tree/main/lib/features/actors"
click node_rankings "https://github.com/tinypinglite/sakuramedia/tree/main/lib/features/rankings"
click node_tags "https://github.com/tinypinglite/sakuramedia/tree/main/lib/features/tags"
click node_subscriptions "https://github.com/tinypinglite/sakuramedia/tree/main/lib/features/subscriptions"
click node_movies "https://github.com/tinypinglite/sakuramedia/tree/main/lib/features/movies"
click node_videos "https://github.com/tinypinglite/sakuramedia/tree/main/lib/features/videos"
click node_media_import "https://github.com/tinypinglite/sakuramedia/tree/main/lib/features/media_import"
click node_media "https://github.com/tinypinglite/sakuramedia/tree/main/lib/features/media"
click node_image_search "https://github.com/tinypinglite/sakuramedia/tree/main/lib/features/image_search"
click node_player "https://github.com/tinypinglite/sakuramedia/tree/main/lib/features/movies/presentation/controllers/player"
click node_external_player "https://github.com/tinypinglite/sakuramedia/tree/main/lib/features/external_player"
click node_playlists "https://github.com/tinypinglite/sakuramedia/tree/main/lib/features/playlists"
click node_moments "https://github.com/tinypinglite/sakuramedia/tree/main/lib/features/moments"
click node_clips "https://github.com/tinypinglite/sakuramedia/tree/main/lib/features/clips"
click node_collections "https://github.com/tinypinglite/sakuramedia/tree/main/lib/features/moment_collections"
click node_clip_collections "https://github.com/tinypinglite/sakuramedia/tree/main/lib/features/clip_collections"
click node_activity "https://github.com/tinypinglite/sakuramedia/tree/main/lib/features/activity"
click node_plugins "https://github.com/tinypinglite/sakuramedia/tree/main/lib/features/plugins"

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_routes,node_user toneBlue
class node_search,node_actors,node_rankings,node_tags,node_subscriptions,node_image_search,node_storage_provider toneAmber
class node_movies,node_videos,node_media_import,node_media toneMint
class node_player,node_external_player,node_playlists,node_moments,node_clips,node_collections,node_clip_collections toneRose
class node_activity,node_plugins,node_backend,node_download_provider,node_notification_channel toneIndigo
```

## Components

### Client Shell

- [App Shell](https://github.com/tinypinglite/sakuramedia/blob/main/lib/app/app.dart): `lib/app/app.dart`
- [Navigation](https://github.com/tinypinglite/sakuramedia/tree/main/lib/routes): `lib/routes`

### Discovery and Tracking

- [Search](https://github.com/tinypinglite/sakuramedia/tree/main/lib/features/search): `lib/features/search`
- [Actor Discovery](https://github.com/tinypinglite/sakuramedia/tree/main/lib/features/actors): `lib/features/actors`
- [Rankings](https://github.com/tinypinglite/sakuramedia/tree/main/lib/features/rankings): `lib/features/rankings`
- [Tags](https://github.com/tinypinglite/sakuramedia/tree/main/lib/features/tags): `lib/features/tags`
- [Subscriptions](https://github.com/tinypinglite/sakuramedia/tree/main/lib/features/subscriptions): `lib/features/subscriptions`
- [Image Search](https://github.com/tinypinglite/sakuramedia/tree/main/lib/features/image_search): `lib/features/image_search`

### Library Operations

- [Movie Catalog](https://github.com/tinypinglite/sakuramedia/tree/main/lib/features/movies): `lib/features/movies`
- [Video Library](https://github.com/tinypinglite/sakuramedia/tree/main/lib/features/videos): `lib/features/videos`
- [Media Import](https://github.com/tinypinglite/sakuramedia/tree/main/lib/features/media_import): `lib/features/media_import`
- [Media Management](https://github.com/tinypinglite/sakuramedia/tree/main/lib/features/media): `lib/features/media`

### Playback and Collections

- [Playback](https://github.com/tinypinglite/sakuramedia/tree/main/lib/features/movies/presentation/controllers/player): `lib/features/movies/presentation/controllers/player`
- [External Player](https://github.com/tinypinglite/sakuramedia/tree/main/lib/features/external_player): `lib/features/external_player`
- [Playlists](https://github.com/tinypinglite/sakuramedia/tree/main/lib/features/playlists): `lib/features/playlists`
- [Moments](https://github.com/tinypinglite/sakuramedia/tree/main/lib/features/moments): `lib/features/moments`
- [Clips](https://github.com/tinypinglite/sakuramedia/tree/main/lib/features/clips): `lib/features/clips`
- [Collections](https://github.com/tinypinglite/sakuramedia/tree/main/lib/features/moment_collections): `lib/features/moment_collections`
- [Clip Collections](https://github.com/tinypinglite/sakuramedia/tree/main/lib/features/clip_collections): `lib/features/clip_collections`

### Tasks and Extensions

- [Tasks and Notices](https://github.com/tinypinglite/sakuramedia/tree/main/lib/features/activity): `lib/features/activity`
- [Plugin Management](https://github.com/tinypinglite/sakuramedia/tree/main/lib/features/plugins): `lib/features/plugins`

### Other components

- **Media User**
- **SakuraMedia Backend**
- **Download Provider**
- **Storage Provider**
- **Notification Channel**

## Connections

- Media User → App Shell: uses
- App Shell → Navigation: navigates
- Navigation → Search: opens
- Navigation → Actor Discovery: opens
- Navigation → Rankings: opens
- Navigation → Tags: opens
- Navigation → Subscriptions: opens
- Navigation → Movie Catalog: opens
- Navigation → Video Library: opens
- Navigation → Media Import: opens
- Navigation → Media Management: opens
- Navigation → Image Search: opens
- Navigation → Playback: opens
- Navigation → Playlists: opens
- Navigation → Moments: opens
- Navigation → Clips: opens
- Navigation → Collections: opens
- Navigation → Clip Collections: opens
- Navigation → Tasks and Notices: opens
- Navigation → Plugin Management: opens
- Search → SakuraMedia Backend: queries
- Actor Discovery → SakuraMedia Backend: queries
- Rankings → SakuraMedia Backend: loads rankings
- Tags → SakuraMedia Backend: loads tags
- Subscriptions → SakuraMedia Backend: submits subscriptions
- Subscriptions → Download Provider: finds resources
- Download Provider → Storage Provider: writes downloads
- Storage Provider → Media Import: provides media
- Media Import → SakuraMedia Backend: imports metadata
- Media Management → SakuraMedia Backend: manages library
- Media Management → Storage Provider: migrates media
- Image Search → SakuraMedia Backend: searches images
- Movie Catalog → SakuraMedia Backend: loads catalog
- Video Library → SakuraMedia Backend: loads media
- Playback → SakuraMedia Backend: requests streams
- Playback → External Player: launches playback
- Playlists → SakuraMedia Backend: saves lists
- Moments → SakuraMedia Backend: saves moments
- Clips → SakuraMedia Backend: saves clips
- Collections → SakuraMedia Backend: loads collections
- Clip Collections → SakuraMedia Backend: loads collections
- Tasks and Notices → SakuraMedia Backend: loads task status
- SakuraMedia Backend → Notification Channel: dispatches notices
- Plugin Management → SakuraMedia Backend: configures extensions