# cardinal117/mistake-watch architecture

> Architecture diagram of the GitHub repository cardinal117/mistake-watch, 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/cardinal117/mistake-watch
- Repository: https://github.com/cardinal117/mistake-watch

## Overview

Mistake Watch is a private, guest-first watch/listen-together application. Users enter or create persistent, shared, themed, or temporary rooms, then browse media, build a queue, and participate in synchronized playback; signed-in users can manage saved rooms and private listening preferences. Watch and Listen are presentation modes over shared room state. Separate capabilities include first-party media uploads and catalogue playback, personalized discovery, and optional local rhythm analysis. The README documents the product boundaries; sampled code confirms selected API and client flows, so uncertain service wiring is omitted.

Main entry points: [`components/room/listen/listen-mode-layout.tsx`](https://github.com/cardinal117/mistake-watch/blob/main/components/room/listen/listen-mode-layout.tsx) (Listen mode), [`lib/media`](https://github.com/cardinal117/mistake-watch/tree/main/lib/media) (Media catalogue and sessions), [`lib/supabase`](https://github.com/cardinal117/mistake-watch/tree/main/lib/supabase) (Durable product data), [`components/room/room-experience.tsx`](https://github.com/cardinal117/mistake-watch/blob/main/components/room/room-experience.tsx) (Room experience)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_rooms["Rooms and identity"]
  node_dashboard["Room dashboard<br/>[page.tsx]"]
  node_room_entry["Room entry<br/>[page.tsx]"]
  node_room_lifecycle["Room lifecycle"]
  node_identity["Guest and account identity"]
end

subgraph group_experience["Room experience"]
  node_room_experience["Room experience"]
  node_watch["Watch mode"]
  node_listen["Listen mode"]
  node_queue["Queue and ordering<br/>[model.ts]"]
  node_player["Playback and synchronization<br/>[sync.ts]"]
end

subgraph group_media["Media workflows"]
  node_youtube["YouTube search and playback"]
  node_add_media["Add media and playlists"]
  node_uploads["Owner upload workflow"]
  node_media_catalogue["Media catalogue and sessions"]
end

subgraph group_discovery["Discovery and learning"]
  node_recommendations["Personalized discovery"]
  node_preferences["Listening preferences<br/>[route.ts]"]
  node_companion["Local rhythm companion"]
end

subgraph group_platform["Live and durable services"]
  node_spacetime[("Live room authority")]
  node_supabase[("Durable product data")]
end

node_user(("Room participant"))
node_youtube_service["YouTube service"]
node_r2[("Object storage")]
node_cloudconvert["CloudConvert"]
node_google["Google identity provider"]

node_user -->|"opens"| node_dashboard
node_user -->|"joins"| node_room_entry
node_dashboard -->|"creates or lists"| node_room_lifecycle
node_room_entry -->|"enters"| node_room_experience
node_room_lifecycle -->|"persists rooms"| node_supabase
node_identity -->|"uses accounts"| node_supabase
node_identity -->|"authenticates with"| node_google
node_room_experience -->|"presents Watch"| node_watch
node_room_experience -->|"presents Listen"| node_listen
node_watch -->|"manages queue"| node_queue
node_listen -->|"manages queue"| node_queue
node_watch -->|"controls playback"| node_player
node_listen -->|"controls playback"| node_player
node_room_experience -->|"syncs room state"| node_spacetime
node_player -->|"synchronizes playback"| node_spacetime
node_add_media -->|"previews playlists"| node_youtube
node_add_media -->|"matches assets"| node_media_catalogue
node_youtube -->|"searches and fetches"| node_youtube_service
node_uploads -->|"creates and resumes uploads"| node_media_catalogue
node_media_catalogue -->|"stores metadata"| node_supabase
node_media_catalogue -->|"stores media objects"| node_r2
node_media_catalogue -.->|"processes by approval"| node_cloudconvert
node_recommendations -->|"reads and records"| node_supabase
node_preferences -->|"authorizes preference operations"| node_recommendations
node_preferences -->|"reads and updates settings"| node_supabase
node_listen -->|"shows room picks"| node_recommendations
node_companion -.->|"provides local rhythm"| node_listen

click node_dashboard "https://github.com/cardinal117/mistake-watch/blob/main/app/page.tsx"
click node_room_entry "https://github.com/cardinal117/mistake-watch/blob/main/app/rooms/%5BroomId%5D/page.tsx"
click node_room_lifecycle "https://github.com/cardinal117/mistake-watch/tree/main/lib/rooms"
click node_identity "https://github.com/cardinal117/mistake-watch/tree/main/lib/identity"
click node_room_experience "https://github.com/cardinal117/mistake-watch/blob/main/components/room/room-experience.tsx"
click node_watch "https://github.com/cardinal117/mistake-watch/blob/main/components/room/watch/watch-mode-layout.tsx"
click node_listen "https://github.com/cardinal117/mistake-watch/blob/main/components/room/listen/listen-mode-layout.tsx"
click node_queue "https://github.com/cardinal117/mistake-watch/blob/main/lib/queue/model.ts"
click node_player "https://github.com/cardinal117/mistake-watch/blob/main/lib/player/sync.ts"
click node_youtube "https://github.com/cardinal117/mistake-watch/tree/main/lib/youtube"
click node_add_media "https://github.com/cardinal117/mistake-watch/blob/main/components/room/shared/add-media/use-add-media-controller.ts"
click node_uploads "https://github.com/cardinal117/mistake-watch/blob/main/components/room/watch/uploads/use-owner-upload-manager.ts"
click node_media_catalogue "https://github.com/cardinal117/mistake-watch/tree/main/lib/media"
click node_recommendations "https://github.com/cardinal117/mistake-watch/tree/main/lib/recommendations"
click node_preferences "https://github.com/cardinal117/mistake-watch/blob/main/app/api/recommendations/preferences/route.ts"
click node_companion "https://github.com/cardinal117/mistake-watch/tree/main/extensions/watch-audio-companion"
click node_spacetime "https://github.com/cardinal117/mistake-watch/tree/main/spacetime/src"
click node_supabase "https://github.com/cardinal117/mistake-watch/tree/main/lib/supabase"

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_dashboard,node_room_entry,node_room_lifecycle,node_identity toneBlue
class node_room_experience,node_watch,node_listen,node_queue,node_player,node_r2 toneAmber
class node_youtube,node_add_media,node_uploads,node_media_catalogue toneMint
class node_recommendations,node_preferences,node_companion toneRose
class node_spacetime,node_supabase,node_user,node_youtube_service,node_cloudconvert,node_google toneIndigo
```

## Components

### Rooms and identity

- [Room dashboard](https://github.com/cardinal117/mistake-watch/blob/main/app/page.tsx): `app/page.tsx`
- [Room entry](https://github.com/cardinal117/mistake-watch/blob/main/app/rooms/%5BroomId%5D/page.tsx): `app/rooms/[roomId]/page.tsx`
- [Room lifecycle](https://github.com/cardinal117/mistake-watch/tree/main/lib/rooms): `lib/rooms`
- [Guest and account identity](https://github.com/cardinal117/mistake-watch/tree/main/lib/identity): `lib/identity`

### Room experience

- [Room experience](https://github.com/cardinal117/mistake-watch/blob/main/components/room/room-experience.tsx): `components/room/room-experience.tsx`
- [Watch mode](https://github.com/cardinal117/mistake-watch/blob/main/components/room/watch/watch-mode-layout.tsx): `components/room/watch/watch-mode-layout.tsx`
- [Listen mode](https://github.com/cardinal117/mistake-watch/blob/main/components/room/listen/listen-mode-layout.tsx): `components/room/listen/listen-mode-layout.tsx`
- [Queue and ordering](https://github.com/cardinal117/mistake-watch/blob/main/lib/queue/model.ts): `lib/queue/model.ts`
- [Playback and synchronization](https://github.com/cardinal117/mistake-watch/blob/main/lib/player/sync.ts): `lib/player/sync.ts`

### Media workflows

- [YouTube search and playback](https://github.com/cardinal117/mistake-watch/tree/main/lib/youtube): `lib/youtube`
- [Add media and playlists](https://github.com/cardinal117/mistake-watch/blob/main/components/room/shared/add-media/use-add-media-controller.ts): `components/room/shared/add-media/use-add-media-controller.ts`
- [Owner upload workflow](https://github.com/cardinal117/mistake-watch/blob/main/components/room/watch/uploads/use-owner-upload-manager.ts): `components/room/watch/uploads/use-owner-upload-manager.ts`
- [Media catalogue and sessions](https://github.com/cardinal117/mistake-watch/tree/main/lib/media): `lib/media`

### Discovery and learning

- [Personalized discovery](https://github.com/cardinal117/mistake-watch/tree/main/lib/recommendations): `lib/recommendations`
- [Listening preferences](https://github.com/cardinal117/mistake-watch/blob/main/app/api/recommendations/preferences/route.ts): `app/api/recommendations/preferences/route.ts`
- [Local rhythm companion](https://github.com/cardinal117/mistake-watch/tree/main/extensions/watch-audio-companion): `extensions/watch-audio-companion`

### Live and durable services

- [Live room authority](https://github.com/cardinal117/mistake-watch/tree/main/spacetime/src): `spacetime/src`
- [Durable product data](https://github.com/cardinal117/mistake-watch/tree/main/lib/supabase): `lib/supabase`

### Other components

- **Room participant**
- **YouTube service**
- **Object storage**
- **CloudConvert**
- **Google identity provider**

## Connections

- Room participant → Room dashboard: opens
- Room participant → Room entry: joins
- Room dashboard → Room lifecycle: creates or lists
- Room entry → Room experience: enters
- Room lifecycle → Durable product data: persists rooms
- Guest and account identity → Durable product data: uses accounts
- Guest and account identity → Google identity provider: authenticates with
- Room experience → Watch mode: presents Watch
- Room experience → Listen mode: presents Listen
- Watch mode → Queue and ordering: manages queue
- Listen mode → Queue and ordering: manages queue
- Watch mode → Playback and synchronization: controls playback
- Listen mode → Playback and synchronization: controls playback
- Room experience → Live room authority: syncs room state
- Playback and synchronization → Live room authority: synchronizes playback
- Add media and playlists → YouTube search and playback: previews playlists
- Add media and playlists → Media catalogue and sessions: matches assets
- YouTube search and playback → YouTube service: searches and fetches
- Owner upload workflow → Media catalogue and sessions: creates and resumes uploads
- Media catalogue and sessions → Durable product data: stores metadata
- Media catalogue and sessions → Object storage: stores media objects
- Media catalogue and sessions → CloudConvert: processes by approval
- Personalized discovery → Durable product data: reads and records
- Listening preferences → Personalized discovery: authorizes preference operations
- Listening preferences → Durable product data: reads and updates settings
- Listen mode → Personalized discovery: shows room picks
- Local rhythm companion → Listen mode: provides local rhythm