How veer0p/moon-frame works
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: WatchRoom.jsx Watch room · App.jsx React app · supabase.js Supabase client · index.ts LiveKit token
Components 19
Desktop shell
Electron runtime and native integration
- Electron main · Creates the desktop window and handles app lifecycle
electron/main.js - Preload bridge · Exposes controlled native APIs to the renderer
electron/preload.js
Renderer app
React UI and watch-room experience
- React app · Top-level renderer composition root
src/App.jsx - Auth flow · Login and signup entry points for session identity
src/pages/Login.jsx - Watch room · Orchestrates the shared viewing session
src/components/WatchRoom.jsx - Video player · Local media playback surface for sync control
src/components/VideoPlayer.jsx - Chat panel · Room messaging and message rendering
src/components/ChatPanel.jsx - Presence UI · Active users, reactions, and lightweight feedback
src/components/UserList.jsx - Session state · Shares authenticated user and app-level session state
src/context/AuthContext.jsx - Sync hooks · Room, video, keyboard, and inactivity coordination
src/hooks/useVideoSync.js - Realtime hooks · Chat, presence, reactions, notifications, and LiveKit integration
src/hooks/useChat.js - Room feedback · Sync indicators, notifications, toast, and last-watched recovery UI
src/components/SyncIndicator.jsx - LiveKit overlay · Visual and interaction layer for RTC session behavior
src/components/LiveKitOverlay.jsx
Cloud services
Supabase auth, realtime state, and token issuance
- Supabase client · Client entry point for auth, realtime data, and persistence
src/lib/supabase.js - Auth + presence · Persistent auth linkage and lightweight room/session metadata
supabase/migrations/20260129000000_auth_linkage.sql - Last watched · Stores the most recent video information for recovery
supabase/migrations/20260129000001_last_watched_video_info.sql - LiveKit token · Issues short-lived LiveKit access tokens
supabase/functions/livekit-token/index.ts
Ops tools
Build, deployment, and environment utilities
- Build config · Renderer build and dev-server configuration
vite.config.js - Deploy scripts · Deployment, VPS checks, SSH helper, and HTTPS setup
deploy.js
Connections 21
- 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