# xp-technologies-dev/p-stream architecture

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

- Interactive diagram: https://gitdiagram.com/xp-technologies-dev/p-stream
- Repository: https://github.com/xp-technologies-dev/p-stream

## Overview

Z-Stream is a streaming-media web app. Its main user journey is to find media, inspect metadata, choose a playback source, and watch while tracking progress and history. The repository also includes account/passkey flows, preferences, and integrations with Trakt and Simkl. The supplied excerpts show selected routing, authentication, metadata, and state-store relationships; several larger features are represented by their exact tree paths, but their internal wiring is not established here.

Main entry points: [`src/components/player/Player.tsx`](https://github.com/xp-technologies-dev/p-stream/blob/production/src/components/player/Player.tsx) (Player), [`src/hooks/auth/useAuth.ts`](https://github.com/xp-technologies-dev/p-stream/blob/production/src/hooks/auth/useAuth.ts) (Authentication), [`src/pages/discover`](https://github.com/xp-technologies-dev/p-stream/tree/production/src/pages/discover) (Discover), [`src/backend/metadata/tmdb.ts`](https://github.com/xp-technologies-dev/p-stream/blob/production/src/backend/metadata/tmdb.ts) (Media Metadata)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Application"]
  node_app["App and Routes<br/>[App.tsx]"]
end

subgraph group_catalog["Discovery and Metadata"]
  node_discover["Discover"]
  node_catalog_lists["Curated Lists<br/>[AllMovieLists.tsx]"]
  node_metadata["Media Metadata<br/>[tmdb.ts]"]
end

subgraph group_playback["Playback"]
  node_player_view["Player Page<br/>[PlayerView.tsx]"]
  node_player["Player<br/>[Player.tsx]"]
  node_sources["Source Selection"]
  node_player_state["Player State<br/>[store.ts]"]
end

subgraph group_account["Accounts and State"]
  node_progress[("Progress State<br/>[index.ts]")]
  node_history[("Watch History<br/>[index.ts]")]
  node_auth_flow["Authentication<br/>[useAuth.ts]"]
  node_auth_api["Account API"]
  node_auth_state[("Auth State<br/>[index.ts]")]
  node_preferences[("Preferences<br/>[index.tsx]")]
end

subgraph group_integrations["External Integrations"]
  node_trakt_api["Trakt Catalog API<br/>[traktApi.ts]"]
  node_trakt_sync["Trakt Integration<br/>[trakt.ts]"]
  node_simkl_sync["Simkl Integration<br/>[simkl.ts]"]
end

node_user(("Viewer"))

node_user -.->|"uses"| node_app
node_app -->|"quick-searches"| node_metadata
node_user -.->|"browses"| node_discover
node_catalog_lists -->|"loads lists"| node_trakt_api
node_catalog_lists -->|"loads details"| node_metadata
node_discover -->|"fetches media"| node_metadata
node_discover -->|"fetches catalog"| node_trakt_api
node_user -.->|"starts playback"| node_player_view
node_player_view -.->|"renders"| node_player
node_player -.->|"updates state"| node_player_state
node_player -.->|"selects source"| node_sources
node_player -.->|"saves progress"| node_progress
node_progress -->|"records completion"| node_history
node_user -.->|"signs in"| node_auth_flow
node_auth_flow -->|"calls account APIs"| node_auth_api
node_auth_flow -.->|"updates session"| node_auth_state
node_auth_flow -.->|"syncs settings"| node_preferences
node_user -.->|"configures"| node_preferences
node_user -.->|"connects account"| node_trakt_sync
node_user -.->|"connects account"| node_simkl_sync

click node_app "https://github.com/xp-technologies-dev/p-stream/blob/production/src/setup/App.tsx"
click node_discover "https://github.com/xp-technologies-dev/p-stream/tree/production/src/pages/discover"
click node_catalog_lists "https://github.com/xp-technologies-dev/p-stream/blob/production/src/pages/discover/AllMovieLists.tsx"
click node_metadata "https://github.com/xp-technologies-dev/p-stream/blob/production/src/backend/metadata/tmdb.ts"
click node_trakt_api "https://github.com/xp-technologies-dev/p-stream/blob/production/src/backend/metadata/traktApi.ts"
click node_player_view "https://github.com/xp-technologies-dev/p-stream/blob/production/src/pages/PlayerView.tsx"
click node_player "https://github.com/xp-technologies-dev/p-stream/blob/production/src/components/player/Player.tsx"
click node_sources "https://github.com/xp-technologies-dev/p-stream/tree/production/src/backend/providers"
click node_player_state "https://github.com/xp-technologies-dev/p-stream/blob/production/src/stores/player/store.ts"
click node_progress "https://github.com/xp-technologies-dev/p-stream/blob/production/src/stores/progress/index.ts"
click node_history "https://github.com/xp-technologies-dev/p-stream/blob/production/src/stores/watchHistory/index.ts"
click node_auth_flow "https://github.com/xp-technologies-dev/p-stream/blob/production/src/hooks/auth/useAuth.ts"
click node_auth_api "https://github.com/xp-technologies-dev/p-stream/tree/production/src/backend/accounts"
click node_auth_state "https://github.com/xp-technologies-dev/p-stream/blob/production/src/stores/auth/index.ts"
click node_preferences "https://github.com/xp-technologies-dev/p-stream/blob/production/src/stores/preferences/index.tsx"
click node_trakt_sync "https://github.com/xp-technologies-dev/p-stream/blob/production/src/utils/services/trakt.ts"
click node_simkl_sync "https://github.com/xp-technologies-dev/p-stream/blob/production/src/utils/services/simkl.ts"

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_user toneBlue
class node_discover,node_catalog_lists,node_metadata toneAmber
class node_player_view,node_player,node_sources,node_player_state toneMint
class node_progress,node_history,node_auth_flow,node_auth_api,node_auth_state,node_preferences toneRose
class node_trakt_api,node_trakt_sync,node_simkl_sync toneIndigo
```

## Components

### Application

- [App and Routes](https://github.com/xp-technologies-dev/p-stream/blob/production/src/setup/App.tsx): `src/setup/App.tsx`

### Discovery and Metadata

- [Discover](https://github.com/xp-technologies-dev/p-stream/tree/production/src/pages/discover): `src/pages/discover`
- [Curated Lists](https://github.com/xp-technologies-dev/p-stream/blob/production/src/pages/discover/AllMovieLists.tsx): `src/pages/discover/AllMovieLists.tsx`
- [Media Metadata](https://github.com/xp-technologies-dev/p-stream/blob/production/src/backend/metadata/tmdb.ts): `src/backend/metadata/tmdb.ts`

### Playback

- [Player Page](https://github.com/xp-technologies-dev/p-stream/blob/production/src/pages/PlayerView.tsx): `src/pages/PlayerView.tsx`
- [Player](https://github.com/xp-technologies-dev/p-stream/blob/production/src/components/player/Player.tsx): `src/components/player/Player.tsx`
- [Source Selection](https://github.com/xp-technologies-dev/p-stream/tree/production/src/backend/providers): `src/backend/providers`
- [Player State](https://github.com/xp-technologies-dev/p-stream/blob/production/src/stores/player/store.ts): `src/stores/player/store.ts`

### Accounts and State

- [Progress State](https://github.com/xp-technologies-dev/p-stream/blob/production/src/stores/progress/index.ts): `src/stores/progress/index.ts`
- [Watch History](https://github.com/xp-technologies-dev/p-stream/blob/production/src/stores/watchHistory/index.ts): `src/stores/watchHistory/index.ts`
- [Authentication](https://github.com/xp-technologies-dev/p-stream/blob/production/src/hooks/auth/useAuth.ts): `src/hooks/auth/useAuth.ts`
- [Account API](https://github.com/xp-technologies-dev/p-stream/tree/production/src/backend/accounts): `src/backend/accounts`
- [Auth State](https://github.com/xp-technologies-dev/p-stream/blob/production/src/stores/auth/index.ts): `src/stores/auth/index.ts`
- [Preferences](https://github.com/xp-technologies-dev/p-stream/blob/production/src/stores/preferences/index.tsx): `src/stores/preferences/index.tsx`

### External Integrations

- [Trakt Catalog API](https://github.com/xp-technologies-dev/p-stream/blob/production/src/backend/metadata/traktApi.ts): `src/backend/metadata/traktApi.ts`
- [Trakt Integration](https://github.com/xp-technologies-dev/p-stream/blob/production/src/utils/services/trakt.ts): `src/utils/services/trakt.ts`
- [Simkl Integration](https://github.com/xp-technologies-dev/p-stream/blob/production/src/utils/services/simkl.ts): `src/utils/services/simkl.ts`

### Other components

- **Viewer**

## Connections

- Viewer → App and Routes: uses
- App and Routes → Media Metadata: quick-searches (evidence: `src/setup/App.tsx`)
- Viewer → Discover: browses
- Curated Lists → Trakt Catalog API: loads lists (evidence: `src/pages/discover/AllMovieLists.tsx`)
- Curated Lists → Media Metadata: loads details (evidence: `src/pages/discover/AllMovieLists.tsx`)
- Discover → Media Metadata: fetches media (evidence: `src/pages/discover/hooks/useDiscoverMedia.ts`)
- Discover → Trakt Catalog API: fetches catalog (evidence: `src/pages/discover/hooks/useDiscoverMedia.ts`)
- Viewer → Player Page: starts playback
- Player Page → Player: renders
- Player → Player State: updates state
- Player → Source Selection: selects source
- Player → Progress State: saves progress
- Progress State → Watch History: records completion (evidence: `src/stores/progress/index.ts`)
- Viewer → Authentication: signs in
- Authentication → Account API: calls account APIs (evidence: `src/hooks/auth/useAuth.ts`)
- Authentication → Auth State: updates session (evidence: `src/hooks/auth/useAuth.ts`)
- Authentication → Preferences: syncs settings (evidence: `src/hooks/auth/useAuth.ts`)
- Viewer → Preferences: configures
- Viewer → Trakt Integration: connects account
- Viewer → Simkl Integration: connects account