# veer0p/moon-frame architecture

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

- Interactive diagram: https://gitdiagram.com/veer0p/moon-frame
- Repository: https://github.com/veer0p/moon-frame

## Overview

1. **Top-level architecture**
   - This is a **desktop Electron app** with a **React renderer**. Electron provides the native shell; React/Vite powers the UI inside the window.
   - The architecture is split between:
     - **Electron main process** (`electron/main.js`) for window lifecycle and native OS integration.
     - **Preload bridge** (`electron/preload.js`) for controlled IPC exposure to the renderer.
     - **React app** (`src/`) for all user-facing screens and session logic.

2. **Primary user experience flow**
   - The app is built around a **watch room** workflow:
     - login/signup,
     - create or join a room,
     - select a local video file,
     - sync playback with other participants,
     - chat and react during the session.
   - The main UI entry points are `LandingScreen`, `Login`, `Signup`, and `WatchRoom`.

3. **Renderer/UI composition**
   - `src/App.jsx` is the top-level React composition root.
   - UI is decomposed into focused components:
     - `VideoPlayer` for playback,
     - `ChatPanel` / `ChatMessage` for messaging,
     - `UserList` for room presence,
     - `EmojiTray` and `Toast` for lightweight interaction and feedback,
     - `SyncIndicator` / `SyncNotification` / `LastWatched` for room state and recovery.
   - Styling is component-scoped through CSS files next to each component.

4. **Playback and sync subsystem**
   - The core domain is **shared video playback synchronization**.
   - `useVideoSync`, `useRoom`, `useKeyboardShortcuts`, and `useInactivityTimer` likely coordinate:
     - play/pause propagation,
     - seek synchronization,
     - buffering/fallback recovery,
     - local control shortcuts,
     - user idle handling.
   - `VideoPlayer` is the execution surface for this subsystem; `WatchRoom` likely orchestrates it.

5. **Real-time collaboration layer**
   - Supabase is the main backend for collaborative state.
   - The app has dedicated hooks for distinct realtime concerns:
     - `useChat` for messages,
     - `usePresence` for active users,
     - `useEmojiReactions` for reaction events,
     - `useNotifications` for user-facing alerts,
     - `useLiveKit` for RTC-related overlay/session behavior.
   - This suggests a **event-driven room model** where ephemeral session data is exchanged in real time rather than centrally rendered from a single server.

6. **Authentication and session identity**
   - `src/context/AuthContext.jsx`, plus `Login.jsx` and `Signup.jsx`, define the authentication boundary.
   - Supabase auth is the identity provider, and app-level auth state is propagated through React context.
   - The app likely uses auth identity to bind room presence, chat sender identity, and persisted per-user session state.

7. **Persistence model**
   - Persistent app data appears intentionally small and session-focused.
   - The Supabase migrations indicate two important persisted concepts:
     - **auth linkage** between app users and backend auth identities,
     - **last watched video info** for restoring or suggesting the last used media.
   - This keeps most watch-room behavior ephemeral while preserving only the minimum needed across sessions.

8. **LiveKit integration boundary**
   - The repo includes `LiveKitOverlay` and a Supabase Edge Function at `supabase/functions/livekit-token`.
   - That indicates a separate **token issuance boundary** for LiveKit access, with the desktop app consuming a short-lived token rather than embedding credentials.
   - `LiveKitOverlay` is likely a visual/interaction layer on top of the core watch-room experience, not the main sync mechanism.

9. **Local-vs-cloud responsibilities**
   - **Local desktop responsibilities**:
     - native file selection,
     - playback rendering,
     - keyboard shortcuts,
     - fullscreen/window behavior.
   - **Cloud responsibilities via Supabase**:
     - auth,
     - real-time collaboration state,
     - persistence of lightweight user/session metadata,
     - token generation for LiveKit.
   - This cleanly separates desktop-native media handling from networked room coordination.

10. **Operational and deployment tooling**
   - The repo contains deployment/support scripts such as `deploy.js`, `check-vps.js`, `ssh-cmd.js`, and `setup-https.js`.
   - These point to a deployment model that likely includes a hosted backend/VPS and HTTPS setup for secure connectivity.
   - `app_log.txt` and `app_log_prod.txt` suggest the app is already instrumented for runtime diagnostics.

11. **Build and runtime toolchain**
   - `vite.config.js` shows the React renderer is built with Vite.
   - `package.json` scripts likely orchestrate:
     - Vite dev server,
     - Electron runtime launch,
     - production packaging/build.
   - The README confirms the development flow is split: start Vite, then launch Electron with hot reload in the renderer.

12. **Boundary summary for an architecture diagram**
   - The cleanest diagram would show:
     - **Electron shell** wrapping the app,
     - **React UI layer** in the renderer,
     - **local media playback** as a client-side subsystem,
     - **Supabase** as the real-time auth/chat/presence/persistence backend,
     - **Supabase Edge Function** issuing LiveKit tokens,
     - optional **LiveKit overlay** as a separate RTC path,
     - **native desktop APIs** exposed through preload/IPC.

Main entry points: [`src/components/WatchRoom.jsx`](https://github.com/veer0p/moon-frame/blob/main/src/components/WatchRoom.jsx) (Watch room), [`src/App.jsx`](https://github.com/veer0p/moon-frame/blob/main/src/App.jsx) (React app), [`src/lib/supabase.js`](https://github.com/veer0p/moon-frame/blob/main/src/lib/supabase.js) (Supabase client), [`supabase/functions/livekit-token/index.ts`](https://github.com/veer0p/moon-frame/blob/main/supabase/functions/livekit-token/index.ts) (LiveKit token)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_g1["Desktop shell"]
  node_n1["Electron main<br/>main process<br/>[main.js]"]
  node_n2["Preload bridge<br/>IPC bridge<br/>[preload.js]"]
end

subgraph group_g2["Renderer app"]
  node_n3["React app<br/>ui root<br/>[App.jsx]"]
  node_n4["Auth flow<br/>auth screens<br/>[Login.jsx]"]
  node_n5["Watch room<br/>room coordinator<br/>[WatchRoom.jsx]"]
  node_n6["Video player<br/>playback surface<br/>[VideoPlayer.jsx]"]
  node_n7["Chat panel<br/>collab UI<br/>[ChatPanel.jsx]"]
  node_n8["Presence UI<br/>room roster<br/>[UserList.jsx]"]
  node_n9["Session state<br/>react context<br/>[AuthContext.jsx]"]
  node_n10["Sync hooks<br/>sync logic<br/>[useVideoSync.js]"]
  node_n11["Realtime hooks<br/>collab hooks<br/>[useChat.js]"]
  node_n12["Room feedback<br/>status overlays<br/>[SyncIndicator.jsx]"]
  node_n17["LiveKit overlay<br/>rtc overlay<br/>[LiveKitOverlay.jsx]"]
end

subgraph group_g3["Cloud services"]
  node_n13["Supabase client<br/>backend client<br/>[supabase.js]"]
  node_n14[("Auth + presence<br/>supabase data")]
  node_n15[("Last watched<br/>supabase data")]
  node_n16["LiveKit token<br/>edge function<br/>[index.ts]"]
end

subgraph group_g4["Ops tools"]
  node_n18["Build config<br/>vite config<br/>[vite.config.js]"]
  node_n19["Deploy scripts<br/>ops scripts<br/>[deploy.js]"]
end

node_n1 -->|"loads"| node_n2
node_n2 -->|"exposes"| node_n3
node_n3 -->|"routes to"| node_n4
node_n3 -->|"renders"| node_n5
node_n5 -->|"controls"| node_n6
node_n5 -->|"hosts"| node_n7
node_n5 -->|"shows"| node_n8
node_n3 -->|"shares"| node_n9
node_n10 -->|"syncs"| node_n6
node_n10 -->|"orchestrates"| node_n5
node_n11 -->|"uses"| node_n13
node_n9 -->|"authenticates"| node_n13
node_n13 -->|"persists"| node_n14
node_n13 -->|"persists"| node_n15
node_n11 -->|"requests token"| node_n16
node_n16 -->|"enables"| node_n17
node_n12 -->|"informs"| node_n5
node_n12 -->|"recovers"| node_n15
node_n18 -->|"builds"| node_n3
node_n19 -->|"supports"| node_n1
node_n19 -->|"supports"| node_n16

click node_n1 "https://github.com/veer0p/moon-frame/blob/main/electron/main.js"
click node_n2 "https://github.com/veer0p/moon-frame/blob/main/electron/preload.js"
click node_n3 "https://github.com/veer0p/moon-frame/blob/main/src/App.jsx"
click node_n4 "https://github.com/veer0p/moon-frame/blob/main/src/pages/Login.jsx"
click node_n5 "https://github.com/veer0p/moon-frame/blob/main/src/components/WatchRoom.jsx"
click node_n6 "https://github.com/veer0p/moon-frame/blob/main/src/components/VideoPlayer.jsx"
click node_n7 "https://github.com/veer0p/moon-frame/blob/main/src/components/ChatPanel.jsx"
click node_n8 "https://github.com/veer0p/moon-frame/blob/main/src/components/UserList.jsx"
click node_n9 "https://github.com/veer0p/moon-frame/blob/main/src/context/AuthContext.jsx"
click node_n10 "https://github.com/veer0p/moon-frame/blob/main/src/hooks/useVideoSync.js"
click node_n11 "https://github.com/veer0p/moon-frame/blob/main/src/hooks/useChat.js"
click node_n12 "https://github.com/veer0p/moon-frame/blob/main/src/components/SyncIndicator.jsx"
click node_n13 "https://github.com/veer0p/moon-frame/blob/main/src/lib/supabase.js"
click node_n14 "https://github.com/veer0p/moon-frame/blob/main/supabase/migrations/20260129000000_auth_linkage.sql"
click node_n15 "https://github.com/veer0p/moon-frame/blob/main/supabase/migrations/20260129000001_last_watched_video_info.sql"
click node_n16 "https://github.com/veer0p/moon-frame/blob/main/supabase/functions/livekit-token/index.ts"
click node_n17 "https://github.com/veer0p/moon-frame/blob/main/src/components/LiveKitOverlay.jsx"
click node_n18 "https://github.com/veer0p/moon-frame/blob/main/vite.config.js"
click node_n19 "https://github.com/veer0p/moon-frame/blob/main/deploy.js"

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_n1,node_n2 toneBlue
class node_n3,node_n4,node_n5,node_n6,node_n7,node_n8,node_n9,node_n10,node_n11,node_n12,node_n17 toneAmber
class node_n13,node_n14,node_n15,node_n16 toneMint
class node_n18,node_n19 toneRose
```

## Components

### Desktop shell

Electron runtime and native integration

- [Electron main](https://github.com/veer0p/moon-frame/blob/main/electron/main.js): main process · Creates the desktop window and handles app lifecycle · `electron/main.js`
- [Preload bridge](https://github.com/veer0p/moon-frame/blob/main/electron/preload.js): IPC bridge · Exposes controlled native APIs to the renderer · `electron/preload.js`

### Renderer app

React UI and watch-room experience

- [React app](https://github.com/veer0p/moon-frame/blob/main/src/App.jsx): ui root · Top-level renderer composition root · `src/App.jsx`
- [Auth flow](https://github.com/veer0p/moon-frame/blob/main/src/pages/Login.jsx): auth screens · Login and signup entry points for session identity · `src/pages/Login.jsx`
- [Watch room](https://github.com/veer0p/moon-frame/blob/main/src/components/WatchRoom.jsx): room coordinator · Orchestrates the shared viewing session · `src/components/WatchRoom.jsx`
- [Video player](https://github.com/veer0p/moon-frame/blob/main/src/components/VideoPlayer.jsx): playback surface · Local media playback surface for sync control · `src/components/VideoPlayer.jsx`
- [Chat panel](https://github.com/veer0p/moon-frame/blob/main/src/components/ChatPanel.jsx): collab UI · Room messaging and message rendering · `src/components/ChatPanel.jsx`
- [Presence UI](https://github.com/veer0p/moon-frame/blob/main/src/components/UserList.jsx): room roster · Active users, reactions, and lightweight feedback · `src/components/UserList.jsx`
- [Session state](https://github.com/veer0p/moon-frame/blob/main/src/context/AuthContext.jsx): react context · Shares authenticated user and app-level session state · `src/context/AuthContext.jsx`
- [Sync hooks](https://github.com/veer0p/moon-frame/blob/main/src/hooks/useVideoSync.js): sync logic · Room, video, keyboard, and inactivity coordination · `src/hooks/useVideoSync.js`
- [Realtime hooks](https://github.com/veer0p/moon-frame/blob/main/src/hooks/useChat.js): collab hooks · Chat, presence, reactions, notifications, and LiveKit integration · `src/hooks/useChat.js`
- [Room feedback](https://github.com/veer0p/moon-frame/blob/main/src/components/SyncIndicator.jsx): status overlays · Sync indicators, notifications, toast, and last-watched recovery UI · `src/components/SyncIndicator.jsx`
- [LiveKit overlay](https://github.com/veer0p/moon-frame/blob/main/src/components/LiveKitOverlay.jsx): rtc overlay · Visual and interaction layer for RTC session behavior · `src/components/LiveKitOverlay.jsx`

### Cloud services

Supabase auth, realtime state, and token issuance

- [Supabase client](https://github.com/veer0p/moon-frame/blob/main/src/lib/supabase.js): backend client · Client entry point for auth, realtime data, and persistence · `src/lib/supabase.js`
- [Auth + presence](https://github.com/veer0p/moon-frame/blob/main/supabase/migrations/20260129000000_auth_linkage.sql): supabase data · Persistent auth linkage and lightweight room/session metadata · `supabase/migrations/20260129000000_auth_linkage.sql`
- [Last watched](https://github.com/veer0p/moon-frame/blob/main/supabase/migrations/20260129000001_last_watched_video_info.sql): supabase data · Stores the most recent video information for recovery · `supabase/migrations/20260129000001_last_watched_video_info.sql`
- [LiveKit token](https://github.com/veer0p/moon-frame/blob/main/supabase/functions/livekit-token/index.ts): edge function · Issues short-lived LiveKit access tokens · `supabase/functions/livekit-token/index.ts`

### Ops tools

Build, deployment, and environment utilities

- [Build config](https://github.com/veer0p/moon-frame/blob/main/vite.config.js): vite config · Renderer build and dev-server configuration · `vite.config.js`
- [Deploy scripts](https://github.com/veer0p/moon-frame/blob/main/deploy.js): ops scripts · Deployment, VPS checks, SSH helper, and HTTPS setup · `deploy.js`

## Connections

- Electron main → Preload bridge: loads · Electron main starts the preload-enabled window
- Preload bridge → React app: exposes · Preload provides controlled APIs to the renderer
- React app → Auth flow: routes to · App enters authentication screens when no session exists
- React app → Watch room: renders · Watch-room experience is composed from the app root
- Watch room → Video player: controls · Room coordinator drives the player and playback state
- Watch room → Chat panel: hosts · Room UI includes chat
- Watch room → Presence UI: shows · Room UI surfaces active participants and reactions
- React app → Session state: shares · Authentication and session identity are propagated through context
- Sync hooks → Video player: syncs · Video sync hooks attach to playback events
- Sync hooks → Watch room: orchestrates · Room-level synchronization logic lives in hooks
- Realtime hooks → Supabase client: uses · Realtime hooks consume the Supabase client
- Session state → Supabase client: authenticates · Session identity is backed by Supabase auth
- Supabase client → Auth + presence: persists · Backend stores auth linkage and room metadata
- Supabase client → Last watched: persists · Backend stores last-watched video details
- Realtime hooks → LiveKit token: requests token · LiveKit integration obtains short-lived access tokens
- LiveKit token → LiveKit overlay: enables · Issued token allows the overlay to participate in RTC features
- Room feedback → Watch room: informs · Indicators and notifications reflect room state
- Room feedback → Last watched: recovers · Last-watched UI uses persisted media metadata
- Build config → React app: builds · Vite config powers the renderer app build and dev server
- Deploy scripts → Electron main: supports · Ops scripts support desktop deployment and runtime setup
- Deploy scripts → LiveKit token: supports · Deployment tooling aligns with backend token issuance
