# vivekkushwahaofficial/framehost architecture

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

- Interactive diagram: https://gitdiagram.com/vivekkushwahaofficial/framehost
- Repository: https://github.com/vivekkushwahaofficial/framehost

## Overview

FrameHost is a multi-device YouTube playback platform. A host creates a room; controllers and followers join with device tokens. The frontend manages room membership and permissions, while authenticated devices send playback commands over STOMP/WebSocket; the backend authorizes commands, updates room playback state, and broadcasts updates for clients to apply to YouTube players. Analytics and usage statistics form a separate capability. Relationships below are limited to README statements and source-index references or excerpts; several listed subsystems were not sampled directly.

Main entry points: [`backend/src/main/java/com/framehost/room/service/RoomService.java`](https://github.com/vivekkushwahaofficial/framehost/blob/main/backend/src/main/java/com/framehost/room/service/RoomService.java) (Room lifecycle), [`frontend/src/App.tsx`](https://github.com/vivekkushwahaofficial/framehost/blob/main/frontend/src/App.tsx) (App orchestration), [`backend/src/main/java/com/framehost/playback/controller/PlaybackCommandController.java`](https://github.com/vivekkushwahaofficial/framehost/blob/main/backend/src/main/java/com/framehost/playback/controller/PlaybackCommandController.java) (Playback command route), [`backend/src/main/java/com/framehost/room/repository/InMemoryRoomRepository.java`](https://github.com/vivekkushwahaofficial/framehost/blob/main/backend/src/main/java/com/framehost/room/repository/InMemoryRoomRepository.java) (In-memory room store)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend experience"]
  node_app["App orchestration<br/>[App.tsx]"]
  node_room_ui["Room session UI<br/>[RoomSession.tsx]"]
  node_room_api["Room API client<br/>[roomApi.ts]"]
  node_sync_hook["Playback sync hook<br/>[usePlaybackSync.ts]"]
  node_stomp["STOMP client<br/>[stompClient.ts]"]
  node_youtube_ui["YouTube player UI<br/>[YouTubePlayer.tsx]"]
  node_youtube_hook["YouTube player hook"]
  node_youtube_api["YouTube API loader<br/>[youtubeApi.ts]"]
end

subgraph group_rooms["Rooms and identity"]
  node_room_controller["Room endpoints"]
  node_room_service["Room lifecycle<br/>[RoomService.java]"]
  node_room_store[("In-memory room store")]
  node_room_model["Room and membership state<br/>[Room.java]"]
  node_device_auth["Device authentication"]
  node_device_tokens["Device token service"]
  node_ws_auth["WebSocket authentication"]
end

subgraph group_playback["Playback sync"]
  node_command_controller["Playback command route"]
  node_command_service["Command authorization and state"]
  node_permission_controller["Permission endpoint"]
  node_permission_service["Permission management"]
end

subgraph group_analytics["Analytics"]
  node_analytics_tracker["Anonymous analytics tracker"]
  node_analytics_api["Analytics API client<br/>[analyticsApi.ts]"]
  node_analytics_controller["Analytics endpoints"]
  node_analytics_service["Analytics service"]
  node_analytics_store[("Analytics repositories")]
  node_stats_page["Usage statistics page<br/>[StatsPage.tsx]"]
end

node_participants(("Host and devices"))

node_participants -->|"use rooms"| node_app
node_app -->|"requests room actions"| node_room_api
node_app -->|"renders session"| node_room_ui
node_app -->|"starts sync"| node_sync_hook
node_room_api -->|"calls backend"| node_room_controller
node_room_controller -->|"delegates room operations"| node_room_service
node_room_service -->|"reads and writes rooms"| node_room_store
node_room_store -->|"stores rooms"| node_room_model
node_room_service -->|"authenticates devices"| node_device_auth
node_room_service -->|"issues credentials"| node_device_tokens
node_device_auth -->|"hashes tokens"| node_device_tokens
node_sync_hook -->|"uses client"| node_stomp
node_sync_hook -.->|"synchronizes player"| node_youtube_ui
node_youtube_ui -->|"uses player logic"| node_youtube_hook
node_youtube_hook -->|"loads API"| node_youtube_api
node_stomp -->|"sends playback commands"| node_command_controller
node_command_controller -->|"executes command"| node_command_service
node_command_controller -->|"looks up room"| node_room_store
node_command_controller -->|"broadcasts state"| node_participants
node_participants -->|"connects authenticated"| node_ws_auth
node_room_ui -.->|"manages permissions"| node_permission_controller
node_permission_controller -->|"delegates permissions"| node_permission_service
node_permission_service -->|"loads room"| node_room_store
node_permission_service -->|"authenticates host"| node_device_auth
node_analytics_tracker -.->|"records activity"| node_analytics_api
node_analytics_api -.->|"requests statistics"| node_analytics_controller
node_analytics_controller -.->|"delegates analytics"| node_analytics_service
node_analytics_service -.->|"persists events"| node_analytics_store
node_stats_page -->|"loads statistics"| node_analytics_api
node_room_service -->|"records room creation"| node_analytics_service

click node_app "https://github.com/vivekkushwahaofficial/framehost/blob/main/frontend/src/App.tsx"
click node_room_ui "https://github.com/vivekkushwahaofficial/framehost/blob/main/frontend/src/components/room/RoomSession.tsx"
click node_room_api "https://github.com/vivekkushwahaofficial/framehost/blob/main/frontend/src/services/api/roomApi.ts"
click node_sync_hook "https://github.com/vivekkushwahaofficial/framehost/blob/main/frontend/src/hooks/usePlaybackSync.ts"
click node_stomp "https://github.com/vivekkushwahaofficial/framehost/blob/main/frontend/src/services/websocket/stompClient.ts"
click node_youtube_ui "https://github.com/vivekkushwahaofficial/framehost/blob/main/frontend/src/components/player/YouTubePlayer.tsx"
click node_youtube_hook "https://github.com/vivekkushwahaofficial/framehost/blob/main/frontend/src/hooks/useYouTubePlayer.ts"
click node_youtube_api "https://github.com/vivekkushwahaofficial/framehost/blob/main/frontend/src/services/youtube/youtubeApi.ts"
click node_room_controller "https://github.com/vivekkushwahaofficial/framehost/blob/main/backend/src/main/java/com/framehost/room/controller/RoomController.java"
click node_room_service "https://github.com/vivekkushwahaofficial/framehost/blob/main/backend/src/main/java/com/framehost/room/service/RoomService.java"
click node_room_store "https://github.com/vivekkushwahaofficial/framehost/blob/main/backend/src/main/java/com/framehost/room/repository/InMemoryRoomRepository.java"
click node_room_model "https://github.com/vivekkushwahaofficial/framehost/blob/main/backend/src/main/java/com/framehost/room/model/Room.java"
click node_device_auth "https://github.com/vivekkushwahaofficial/framehost/blob/main/backend/src/main/java/com/framehost/device/service/DeviceAuthenticationService.java"
click node_device_tokens "https://github.com/vivekkushwahaofficial/framehost/blob/main/backend/src/main/java/com/framehost/device/service/DeviceTokenService.java"
click node_ws_auth "https://github.com/vivekkushwahaofficial/framehost/blob/main/backend/src/main/java/com/framehost/websocket/WebSocketAuthenticationInterceptor.java"
click node_command_controller "https://github.com/vivekkushwahaofficial/framehost/blob/main/backend/src/main/java/com/framehost/playback/controller/PlaybackCommandController.java"
click node_command_service "https://github.com/vivekkushwahaofficial/framehost/blob/main/backend/src/main/java/com/framehost/playback/service/PlaybackCommandService.java"
click node_permission_controller "https://github.com/vivekkushwahaofficial/framehost/blob/main/backend/src/main/java/com/framehost/playback/controller/PlaybackPermissionController.java"
click node_permission_service "https://github.com/vivekkushwahaofficial/framehost/blob/main/backend/src/main/java/com/framehost/playback/service/PlaybackPermissionService.java"
click node_analytics_tracker "https://github.com/vivekkushwahaofficial/framehost/blob/main/frontend/src/components/analytics/AnalyticsTracker.tsx"
click node_analytics_api "https://github.com/vivekkushwahaofficial/framehost/blob/main/frontend/src/services/api/analyticsApi.ts"
click node_analytics_controller "https://github.com/vivekkushwahaofficial/framehost/blob/main/backend/src/main/java/com/framehost/analytics/controller/AnalyticsController.java"
click node_analytics_service "https://github.com/vivekkushwahaofficial/framehost/blob/main/backend/src/main/java/com/framehost/analytics/service/AnalyticsService.java"
click node_analytics_store "https://github.com/vivekkushwahaofficial/framehost/blob/main/backend/src/main/java/com/framehost/analytics/repository/AnalyticsEventRepository.java"
click node_stats_page "https://github.com/vivekkushwahaofficial/framehost/blob/main/frontend/src/pages/StatsPage.tsx"

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_room_ui,node_room_api,node_sync_hook,node_stomp,node_youtube_ui,node_youtube_hook,node_youtube_api toneBlue
class node_room_controller,node_room_service,node_room_store,node_room_model,node_device_auth,node_device_tokens,node_ws_auth toneAmber
class node_command_controller,node_command_service,node_permission_controller,node_permission_service toneMint
class node_analytics_tracker,node_analytics_api,node_analytics_controller,node_analytics_service,node_analytics_store,node_stats_page toneRose
class node_participants toneIndigo
```

## Components

### Frontend experience

- [App orchestration](https://github.com/vivekkushwahaofficial/framehost/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Room session UI](https://github.com/vivekkushwahaofficial/framehost/blob/main/frontend/src/components/room/RoomSession.tsx): `frontend/src/components/room/RoomSession.tsx`
- [Room API client](https://github.com/vivekkushwahaofficial/framehost/blob/main/frontend/src/services/api/roomApi.ts): `frontend/src/services/api/roomApi.ts`
- [Playback sync hook](https://github.com/vivekkushwahaofficial/framehost/blob/main/frontend/src/hooks/usePlaybackSync.ts): `frontend/src/hooks/usePlaybackSync.ts`
- [STOMP client](https://github.com/vivekkushwahaofficial/framehost/blob/main/frontend/src/services/websocket/stompClient.ts): `frontend/src/services/websocket/stompClient.ts`
- [YouTube player UI](https://github.com/vivekkushwahaofficial/framehost/blob/main/frontend/src/components/player/YouTubePlayer.tsx): `frontend/src/components/player/YouTubePlayer.tsx`
- [YouTube player hook](https://github.com/vivekkushwahaofficial/framehost/blob/main/frontend/src/hooks/useYouTubePlayer.ts): `frontend/src/hooks/useYouTubePlayer.ts`
- [YouTube API loader](https://github.com/vivekkushwahaofficial/framehost/blob/main/frontend/src/services/youtube/youtubeApi.ts): `frontend/src/services/youtube/youtubeApi.ts`

### Rooms and identity

- [Room endpoints](https://github.com/vivekkushwahaofficial/framehost/blob/main/backend/src/main/java/com/framehost/room/controller/RoomController.java): `backend/src/main/java/com/framehost/room/controller/RoomController.java`
- [Room lifecycle](https://github.com/vivekkushwahaofficial/framehost/blob/main/backend/src/main/java/com/framehost/room/service/RoomService.java): `backend/src/main/java/com/framehost/room/service/RoomService.java`
- [In-memory room store](https://github.com/vivekkushwahaofficial/framehost/blob/main/backend/src/main/java/com/framehost/room/repository/InMemoryRoomRepository.java): `backend/src/main/java/com/framehost/room/repository/InMemoryRoomRepository.java`
- [Room and membership state](https://github.com/vivekkushwahaofficial/framehost/blob/main/backend/src/main/java/com/framehost/room/model/Room.java): `backend/src/main/java/com/framehost/room/model/Room.java`
- [Device authentication](https://github.com/vivekkushwahaofficial/framehost/blob/main/backend/src/main/java/com/framehost/device/service/DeviceAuthenticationService.java): `backend/src/main/java/com/framehost/device/service/DeviceAuthenticationService.java`
- [Device token service](https://github.com/vivekkushwahaofficial/framehost/blob/main/backend/src/main/java/com/framehost/device/service/DeviceTokenService.java): `backend/src/main/java/com/framehost/device/service/DeviceTokenService.java`
- [WebSocket authentication](https://github.com/vivekkushwahaofficial/framehost/blob/main/backend/src/main/java/com/framehost/websocket/WebSocketAuthenticationInterceptor.java): `backend/src/main/java/com/framehost/websocket/WebSocketAuthenticationInterceptor.java`

### Playback sync

- [Playback command route](https://github.com/vivekkushwahaofficial/framehost/blob/main/backend/src/main/java/com/framehost/playback/controller/PlaybackCommandController.java): `backend/src/main/java/com/framehost/playback/controller/PlaybackCommandController.java`
- [Command authorization and state](https://github.com/vivekkushwahaofficial/framehost/blob/main/backend/src/main/java/com/framehost/playback/service/PlaybackCommandService.java): `backend/src/main/java/com/framehost/playback/service/PlaybackCommandService.java`
- [Permission endpoint](https://github.com/vivekkushwahaofficial/framehost/blob/main/backend/src/main/java/com/framehost/playback/controller/PlaybackPermissionController.java): `backend/src/main/java/com/framehost/playback/controller/PlaybackPermissionController.java`
- [Permission management](https://github.com/vivekkushwahaofficial/framehost/blob/main/backend/src/main/java/com/framehost/playback/service/PlaybackPermissionService.java): `backend/src/main/java/com/framehost/playback/service/PlaybackPermissionService.java`

### Analytics

- [Anonymous analytics tracker](https://github.com/vivekkushwahaofficial/framehost/blob/main/frontend/src/components/analytics/AnalyticsTracker.tsx): `frontend/src/components/analytics/AnalyticsTracker.tsx`
- [Analytics API client](https://github.com/vivekkushwahaofficial/framehost/blob/main/frontend/src/services/api/analyticsApi.ts): `frontend/src/services/api/analyticsApi.ts`
- [Analytics endpoints](https://github.com/vivekkushwahaofficial/framehost/blob/main/backend/src/main/java/com/framehost/analytics/controller/AnalyticsController.java): `backend/src/main/java/com/framehost/analytics/controller/AnalyticsController.java`
- [Analytics service](https://github.com/vivekkushwahaofficial/framehost/blob/main/backend/src/main/java/com/framehost/analytics/service/AnalyticsService.java): `backend/src/main/java/com/framehost/analytics/service/AnalyticsService.java`
- [Analytics repositories](https://github.com/vivekkushwahaofficial/framehost/blob/main/backend/src/main/java/com/framehost/analytics/repository/AnalyticsEventRepository.java): `backend/src/main/java/com/framehost/analytics/repository/AnalyticsEventRepository.java`
- [Usage statistics page](https://github.com/vivekkushwahaofficial/framehost/blob/main/frontend/src/pages/StatsPage.tsx): `frontend/src/pages/StatsPage.tsx`

### Other components

- **Host and devices**

## Connections

- Host and devices → App orchestration: use rooms (evidence: `README.md`)
- App orchestration → Room API client: requests room actions (evidence: `frontend/src/App.tsx`)
- App orchestration → Room session UI: renders session (evidence: `frontend/src/App.tsx`)
- App orchestration → Playback sync hook: starts sync (evidence: `frontend/src/App.tsx`)
- Room API client → Room endpoints: calls backend (evidence: `README.md`)
- Room endpoints → Room lifecycle: delegates room operations (evidence: `backend/src/main/java/com/framehost/room/controller/RoomController.java`)
- Room lifecycle → In-memory room store: reads and writes rooms (evidence: `backend/src/main/java/com/framehost/room/service/RoomService.java`)
- In-memory room store → Room and membership state: stores rooms (evidence: `backend/src/main/java/com/framehost/room/repository/InMemoryRoomRepository.java`)
- Room lifecycle → Device authentication: authenticates devices (evidence: `backend/src/main/java/com/framehost/room/service/RoomService.java`)
- Room lifecycle → Device token service: issues credentials (evidence: `backend/src/main/java/com/framehost/room/service/RoomService.java`)
- Device authentication → Device token service: hashes tokens (evidence: `backend/src/main/java/com/framehost/device/service/DeviceAuthenticationService.java`)
- Playback sync hook → STOMP client: uses client (evidence: `frontend/src/hooks/usePlaybackSync.ts`)
- Playback sync hook → YouTube player UI: synchronizes player
- YouTube player UI → YouTube player hook: uses player logic (evidence: `frontend/src/components/player/YouTubePlayer.tsx`)
- YouTube player hook → YouTube API loader: loads API (evidence: `frontend/src/hooks/useYouTubePlayer.ts`)
- STOMP client → Playback command route: sends playback commands (evidence: `README.md`)
- Playback command route → Command authorization and state: executes command (evidence: `backend/src/main/java/com/framehost/playback/controller/PlaybackCommandController.java`)
- Playback command route → In-memory room store: looks up room (evidence: `backend/src/main/java/com/framehost/playback/controller/PlaybackCommandController.java`)
- Playback command route → Host and devices: broadcasts state (evidence: `README.md`)
- Host and devices → WebSocket authentication: connects authenticated (evidence: `README.md`)
- Room session UI → Permission endpoint: manages permissions
- Permission endpoint → Permission management: delegates permissions (evidence: `backend/src/main/java/com/framehost/playback/controller/PlaybackPermissionController.java`)
- Permission management → In-memory room store: loads room (evidence: `backend/src/main/java/com/framehost/playback/service/PlaybackPermissionService.java`)
- Permission management → Device authentication: authenticates host (evidence: `backend/src/main/java/com/framehost/playback/service/PlaybackPermissionService.java`)
- Anonymous analytics tracker → Analytics API client: records activity
- Analytics API client → Analytics endpoints: requests statistics
- Analytics endpoints → Analytics service: delegates analytics
- Analytics service → Analytics repositories: persists events (evidence: `backend/src/main/java/com/framehost/analytics/service/AnalyticsService.java`)
- Usage statistics page → Analytics API client: loads statistics (evidence: `frontend/src/pages/StatsPage.tsx`)
- Room lifecycle → Analytics service: records room creation (evidence: `backend/src/main/java/com/framehost/room/service/RoomService.java`)