# ngoquangphuc29306/webflim architecture

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

- Interactive diagram: https://gitdiagram.com/ngoquangphuc29306/webflim
- Repository: https://github.com/ngoquangphuc29306/webflim

## Overview

PHEVO is a movie-discovery and streaming product with a web experience and a separate Android TV client. The main web journey spans discovery/search, movie detail, and playback; account features preserve watchlist, history, progress, and player preferences, with local/cloud synchronization. The sampled API routes call the shared movie API, and the sync engine coordinates local state with cloud gateways. The tree also documents taxonomy, recommendations, and TV playback, but their internal wiring is not fully shown in the excerpts; those uncertain links are omitted.

Main entry points: [`lib/api/movies.ts`](https://github.com/ngoquangphuc29306/webflim/blob/main/lib/api/movies.ts) (Movie API), [`lib/sync/sync-engine.ts`](https://github.com/ngoquangphuc29306/webflim/blob/main/lib/sync/sync-engine.ts) (Cloud sync engine), [`android-tv/app/src/main/java/com/phevo/tv/MainActivity.kt`](https://github.com/ngoquangphuc29306/webflim/blob/main/android-tv/app/src/main/java/com/phevo/tv/MainActivity.kt) (TV app), [`android-tv/app/src/main/java/com/phevo/tv/data/repository/VsmovMovieRepository.kt`](https://github.com/ngoquangphuc29306/webflim/blob/main/android-tv/app/src/main/java/com/phevo/tv/data/repository/VsmovMovieRepository.kt) (TV movie repository)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web experience"]
  node_web_home["Home and discovery<br/>[page.tsx]"]
  node_web_explore["Explore and taxonomy<br/>[page.tsx]"]
  node_web_search["Search<br/>[page.tsx]"]
  node_web_detail["Movie detail<br/>[page.tsx]"]
  node_web_player["Movie playback<br/>[page.tsx]"]
  node_web_watchlist["Watchlist<br/>[page.tsx]"]
  node_web_history["Viewing history<br/>[page.tsx]"]
end

subgraph group_catalog["Catalog services"]
  node_movie_api["Movie API<br/>[movies.ts]"]
  node_suggestions_route["Search suggestions<br/>[route.ts]"]
  node_movie_route["Movie detail API<br/>[route.ts]"]
  node_taxonomy_routes["Taxonomy APIs<br/>[route.ts]"]
  node_provider["Movie provider<br/>[movie-provider.ts]"]
  node_tmdb["TMDB integration<br/>[client.ts]"]
end

subgraph group_user_state["User state"]
  node_local_state[("Local persistence<br/>[storage.ts]")]
  node_history_store["History persistence<br/>[history.service.ts]"]
  node_watchlist_store["Watchlist persistence"]
  node_progress_store["Playback progress"]
  node_preferences_store["Player preferences"]
  node_sync_engine["Cloud sync engine<br/>[sync-engine.ts]"]
  node_cloud_gateways["Cloud data gateways"]
end

subgraph group_tv["Android TV"]
  node_tv_client["TV app<br/>[MainActivity.kt]"]
  node_tv_catalog["TV movie repository"]
  node_tv_player["TV playback controller"]
end

node_viewer(("Viewer"))
node_vsmov_service{{"VSMov service"}}

node_viewer -->|"opens"| node_web_home
node_viewer -->|"browses"| node_web_explore
node_viewer -->|"searches"| node_web_search
node_viewer -->|"views"| node_web_detail
node_viewer -->|"watches"| node_web_player
node_viewer -->|"manages"| node_web_watchlist
node_viewer -->|"reviews"| node_web_history
node_suggestions_route -->|"searches"| node_movie_api
node_movie_route -->|"fetches details"| node_movie_api
node_taxonomy_routes -->|"fetches taxonomy"| node_movie_api
node_movie_api --> node_provider
node_movie_api -.-> node_tmdb
node_sync_engine -->|"reads and writes"| node_local_state
node_sync_engine -->|"syncs with"| node_cloud_gateways
node_tv_client --> node_tv_catalog
node_tv_client --> node_tv_player
node_tv_catalog --> node_vsmov_service

click node_web_home "https://github.com/ngoquangphuc29306/webflim/blob/main/app/page.tsx"
click node_web_explore "https://github.com/ngoquangphuc29306/webflim/blob/main/app/kham-pha/page.tsx"
click node_web_search "https://github.com/ngoquangphuc29306/webflim/blob/main/app/tim-kiem/page.tsx"
click node_web_detail "https://github.com/ngoquangphuc29306/webflim/blob/main/app/phim/%5Bslug%5D/page.tsx"
click node_web_player "https://github.com/ngoquangphuc29306/webflim/blob/main/app/xem-phim/%5Bslug%5D/page.tsx"
click node_web_watchlist "https://github.com/ngoquangphuc29306/webflim/blob/main/app/yeu-thich/page.tsx"
click node_web_history "https://github.com/ngoquangphuc29306/webflim/blob/main/app/lich-su/page.tsx"
click node_movie_api "https://github.com/ngoquangphuc29306/webflim/blob/main/lib/api/movies.ts"
click node_suggestions_route "https://github.com/ngoquangphuc29306/webflim/blob/main/app/api/search/suggestions/route.ts"
click node_movie_route "https://github.com/ngoquangphuc29306/webflim/blob/main/app/api/movies/%5Bslug%5D/route.ts"
click node_taxonomy_routes "https://github.com/ngoquangphuc29306/webflim/blob/main/app/api/taxonomy/countries/route.ts"
click node_provider "https://github.com/ngoquangphuc29306/webflim/blob/main/lib/api/providers/movie-provider.ts"
click node_tmdb "https://github.com/ngoquangphuc29306/webflim/blob/main/lib/tmdb/client.ts"
click node_local_state "https://github.com/ngoquangphuc29306/webflim/blob/main/lib/persistence/storage.ts"
click node_history_store "https://github.com/ngoquangphuc29306/webflim/blob/main/lib/persistence/history/history.service.ts"
click node_watchlist_store "https://github.com/ngoquangphuc29306/webflim/blob/main/lib/persistence/watchlist/watchlist.service.ts"
click node_progress_store "https://github.com/ngoquangphuc29306/webflim/blob/main/lib/persistence/progress/progress.service.ts"
click node_preferences_store "https://github.com/ngoquangphuc29306/webflim/blob/main/lib/persistence/player-preferences/preferences.service.ts"
click node_sync_engine "https://github.com/ngoquangphuc29306/webflim/blob/main/lib/sync/sync-engine.ts"
click node_cloud_gateways "https://github.com/ngoquangphuc29306/webflim/blob/main/lib/cloud/watchlist-gateway.ts"
click node_tv_client "https://github.com/ngoquangphuc29306/webflim/blob/main/android-tv/app/src/main/java/com/phevo/tv/MainActivity.kt"
click node_tv_catalog "https://github.com/ngoquangphuc29306/webflim/blob/main/android-tv/app/src/main/java/com/phevo/tv/data/repository/VsmovMovieRepository.kt"
click node_tv_player "https://github.com/ngoquangphuc29306/webflim/blob/main/android-tv/app/src/main/java/com/phevo/tv/ui/player/Media3PlaybackController.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_web_home,node_web_explore,node_web_search,node_web_detail,node_web_player,node_web_watchlist,node_web_history,node_viewer toneBlue
class node_movie_api,node_suggestions_route,node_movie_route,node_taxonomy_routes,node_provider,node_tmdb toneAmber
class node_local_state,node_history_store,node_watchlist_store,node_progress_store,node_preferences_store,node_sync_engine,node_cloud_gateways toneMint
class node_tv_client,node_tv_catalog,node_tv_player toneRose
class node_vsmov_service toneIndigo
```

## Components

### Web experience

- [Home and discovery](https://github.com/ngoquangphuc29306/webflim/blob/main/app/page.tsx): `app/page.tsx`
- [Explore and taxonomy](https://github.com/ngoquangphuc29306/webflim/blob/main/app/kham-pha/page.tsx): `app/kham-pha/page.tsx`
- [Search](https://github.com/ngoquangphuc29306/webflim/blob/main/app/tim-kiem/page.tsx): `app/tim-kiem/page.tsx`
- [Movie detail](https://github.com/ngoquangphuc29306/webflim/blob/main/app/phim/%5Bslug%5D/page.tsx): `app/phim/[slug]/page.tsx`
- [Movie playback](https://github.com/ngoquangphuc29306/webflim/blob/main/app/xem-phim/%5Bslug%5D/page.tsx): `app/xem-phim/[slug]/page.tsx`
- [Watchlist](https://github.com/ngoquangphuc29306/webflim/blob/main/app/yeu-thich/page.tsx): `app/yeu-thich/page.tsx`
- [Viewing history](https://github.com/ngoquangphuc29306/webflim/blob/main/app/lich-su/page.tsx): `app/lich-su/page.tsx`

### Catalog services

- [Movie API](https://github.com/ngoquangphuc29306/webflim/blob/main/lib/api/movies.ts): `lib/api/movies.ts`
- [Search suggestions](https://github.com/ngoquangphuc29306/webflim/blob/main/app/api/search/suggestions/route.ts): `app/api/search/suggestions/route.ts`
- [Movie detail API](https://github.com/ngoquangphuc29306/webflim/blob/main/app/api/movies/%5Bslug%5D/route.ts): `app/api/movies/[slug]/route.ts`
- [Taxonomy APIs](https://github.com/ngoquangphuc29306/webflim/blob/main/app/api/taxonomy/countries/route.ts): `app/api/taxonomy/countries/route.ts`
- [Movie provider](https://github.com/ngoquangphuc29306/webflim/blob/main/lib/api/providers/movie-provider.ts): `lib/api/providers/movie-provider.ts`
- [TMDB integration](https://github.com/ngoquangphuc29306/webflim/blob/main/lib/tmdb/client.ts): `lib/tmdb/client.ts`

### User state

- [Local persistence](https://github.com/ngoquangphuc29306/webflim/blob/main/lib/persistence/storage.ts): `lib/persistence/storage.ts`
- [History persistence](https://github.com/ngoquangphuc29306/webflim/blob/main/lib/persistence/history/history.service.ts): `lib/persistence/history/history.service.ts`
- [Watchlist persistence](https://github.com/ngoquangphuc29306/webflim/blob/main/lib/persistence/watchlist/watchlist.service.ts): `lib/persistence/watchlist/watchlist.service.ts`
- [Playback progress](https://github.com/ngoquangphuc29306/webflim/blob/main/lib/persistence/progress/progress.service.ts): `lib/persistence/progress/progress.service.ts`
- [Player preferences](https://github.com/ngoquangphuc29306/webflim/blob/main/lib/persistence/player-preferences/preferences.service.ts): `lib/persistence/player-preferences/preferences.service.ts`
- [Cloud sync engine](https://github.com/ngoquangphuc29306/webflim/blob/main/lib/sync/sync-engine.ts): `lib/sync/sync-engine.ts`
- [Cloud data gateways](https://github.com/ngoquangphuc29306/webflim/blob/main/lib/cloud/watchlist-gateway.ts): `lib/cloud/watchlist-gateway.ts`

### Android TV

- [TV app](https://github.com/ngoquangphuc29306/webflim/blob/main/android-tv/app/src/main/java/com/phevo/tv/MainActivity.kt): `android-tv/app/src/main/java/com/phevo/tv/MainActivity.kt`
- [TV movie repository](https://github.com/ngoquangphuc29306/webflim/blob/main/android-tv/app/src/main/java/com/phevo/tv/data/repository/VsmovMovieRepository.kt): `android-tv/app/src/main/java/com/phevo/tv/data/repository/VsmovMovieRepository.kt`
- [TV playback controller](https://github.com/ngoquangphuc29306/webflim/blob/main/android-tv/app/src/main/java/com/phevo/tv/ui/player/Media3PlaybackController.kt): `android-tv/app/src/main/java/com/phevo/tv/ui/player/Media3PlaybackController.kt`

### Other components

- **Viewer**
- **VSMov service**

## Connections

- Viewer → Home and discovery: opens
- Viewer → Explore and taxonomy: browses
- Viewer → Search: searches
- Viewer → Movie detail: views
- Viewer → Movie playback: watches
- Viewer → Watchlist: manages
- Viewer → Viewing history: reviews
- Search suggestions → Movie API: searches
- Movie detail API → Movie API: fetches details
- Taxonomy APIs → Movie API: fetches taxonomy
- Movie API → Movie provider
- Movie API → TMDB integration
- Cloud sync engine → Local persistence: reads and writes
- Cloud sync engine → Cloud data gateways: syncs with
- TV app → TV movie repository
- TV app → TV playback controller
- TV movie repository → VSMov service