# movixcorp/movixopensource architecture

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

- Interactive diagram: https://gitdiagram.com/movixcorp/movixopensource
- Repository: https://github.com/movixcorp/movixopensource

## Overview

1. **Repository shape: a multi-client media platform**
   Movix is a monorepo where one product is split across several runtime boundaries: a web frontend, a primary Node backend, a real-time WatchParty service, Python proxy services, a mobile app, browser tooling, and a Rust/WASM sync engine. The architecture is not “frontend + API” only; some features intentionally span 3–4 components.

2. **Main user-facing client: `src/`**
   The primary app is a React + TypeScript frontend built with Vite. It owns navigation, account/profile UI, media browsing, watch pages, VIP flows, watchparty screens, admin screens, and most presentation logic. It talks to the backend through `src/services/api.ts` and feature-specific service modules, and it relies heavily on local state plus browser storage for preferences and session-adjacent state.

3. **Primary backend: `API/Mainapi/`**
   This is the authoritative backend for the product. It is a Node.js service with many Express route modules grouped by domain: auth, profiles, sync, search, downloads, VIP, comments, likes, shared lists, admin, OAuth apps, TMDB, live TV, and multiple provider-specific route files. It is the place where persistent application data, moderation/admin workflows, and cross-device synchronization are handled.

4. **Persistence layer: MySQL + Redis**
   `API/Mainapi/` uses MySQL as the durable system of record for user/account data, lists, comments, feedback, VIP-related tables, sessions, OAuth apps, bans, moderation, and tracking tables introduced via SQL scripts in `exportscripts/` and `wrapped_tables.sql`. Redis is used for fast state: rate limiting, locks, cache, and coordination utilities. The frontend also keeps a meaningful amount of state in `localStorage`, so the system is a mix of server persistence and client-side preferences.

5. **Auth, identity, and sync**
   Authentication and account linking are handled in the backend and consumed by the React app through `AuthContext`, profile pages, and auth-related services. The repo also contains sync-related utilities and route groups, which suggests the app keeps user settings, profiles, and watch-related metadata synchronized across devices rather than treating the browser as the sole source of truth.

6. **Watch playback and source/extraction pipeline**
   Playback is split across frontend player components, backend provider routes, and supporting utilities. The frontend contains several player implementations and helper logic for source selection, extraction, DNS/proxy handling, and safe playback. Backend routes such as download, proxy, search, TMDB, live TV, and provider-specific modules help resolve media sources and enrich playback data before it reaches the player UI.

7. **Proxy and embed infrastructure**
   `API/proxiesembed/` is a separate Python service used for high-churn proxying, embeds, DRM-related interactions, and service-specific extraction logic. It contains a large catalog of site adapters, so it acts as a specialized media gateway rather than a general-purpose API. This is a distinct boundary from `API/Mainapi/` because it likely has different performance, network, and scraping requirements.

8. **WatchParty real-time subsystem**
   WatchParty is its own backend service at `API/watchpartyAPI/`, backed by Socket.IO-style real-time coordination on a dedicated port. The frontend watchparty pages, `useWatchParty` hook, sync utilities, worker, and WASM module all feed into this service. The key data flow is: UI event → sync logic / worker / WASM → WatchParty API → other participants’ clients.

9. **Rust/WASM sync engine**
   `wasm/watchparty-sync/` is the performance-sensitive synchronization core compiled to WebAssembly and published under `public/wasm/watchparty-sync/`. It is used by the frontend watchparty flow to keep timing/state reconciliation fast and deterministic in the browser, with a worker offloading the coordination work from the main UI thread.

10. **Browser extension and userscript**
   `extension/` and `userscript/` are separate client-side surfaces that integrate with the same media ecosystem. They contain injection/content scripts, background logic, and extraction helpers, which means some playback or page-control behavior can happen inside the streaming site context rather than only inside the Movix web app.

11. **Mobile app boundary**
   `app/` is a React Native client with Android and iOS scaffolding. It reuses the same product concepts—browser, DNS handling, updates, casting, and bridge/injection logic—but as a native shell. It is architecturally separate from the web app, yet it still depends on the same backend URLs and app-level services for updates, address resolution, and media-related flows.

12. **Edge/serverless and proxy deployment layers**
   The repo includes Cloudflare Workers (`cloudflareproxy/`, `RivestreamCloudflareProxy/`) and serverless functions under `functions/`. These are thin edge boundaries used for proxying, CORS/redirect behavior, previews, or route-specific hosting concerns. They sit in front of or alongside the main backend rather than replacing it.

13. **Support services and integrations**
   The platform integrates with several external services that materially affect architecture: TMDB for metadata, Discord and Google auth flows, Turnstile for anti-abuse, and various media/provider endpoints. The frontend and backend each have dedicated helpers/config for these integrations, so the system is “integration-heavy” rather than self-contained.

14. **Static/public artifact layer**
   `public/` holds important runtime assets, not just images: avatars, tutorial content, WASM artifacts, service-worker assets, and route/public metadata. This makes deployment a mixed static + dynamic model: the frontend serves static bundles and media assets while backend services handle stateful and network-heavy operations.

15. **Practical diagram boundary**
   If you draw the architecture, the clearest split is:
   - **Clients:** React web app, mobile app, browser extension, userscript
   - **Core backend:** Main API
   - **Specialized services:** WatchParty API, proxy/embed Python service, bypass403 microservice, Cloudflare workers
   - **Storage:** MySQL, Redis, browser local storage
   - **External services:** TMDB, Discord, Google, Turnstile, provider/media sites
   The main cross-cutting flow is: client UI requests media/account state from the main API, fetches or resolves playback sources through proxy/extraction layers, and uses the WatchParty stack only for synchronized group viewing.

Main entry points: [`API/Mainapi`](https://github.com/movixcorp/movixopensource/tree/main/API/Mainapi) (Main API), [`src`](https://github.com/movixcorp/movixopensource/tree/main/src) (Web app), [`API/watchpartyAPI`](https://github.com/movixcorp/movixopensource/tree/main/API/watchpartyAPI) (WatchParty API), [`wasm/watchparty-sync`](https://github.com/movixcorp/movixopensource/tree/main/wasm/watchparty-sync) (Sync engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["Clients"]
  node_web_app["Web app<br/>React/Vite client"]
  node_mobile_app["Mobile app<br/>React Native client"]
  node_extension["Browser ext"]
  node_userscript["Userscript"]
end

subgraph group_backend["Core backend"]
  node_main_api["Main API<br/>Node/Express API"]
  node_main_routes["API domains<br/>route modules"]
  node_main_utils["API utils<br/>backend utilities"]
end

subgraph group_realtime["Realtime sync"]
  node_watchparty_api["WatchParty API<br/>Socket.IO service"]
  node_sync_engine{{"Sync engine<br/>Rust/WASM module"}}
  node_sync_worker["Sync worker<br/>web worker"]
end

subgraph group_edge["Edge layers"]
  node_proxy_embed["Proxy embed<br/>Python proxy service"]
  node_bypass403["Bypass 403<br/>Python microservice<br/>[bypass403.py]"]
  node_cf_proxy["Cloudflare proxy<br/>worker boundary<br/>[worker.js]"]
  node_rivestream_proxy["Rivestream proxy<br/>worker boundary<br/>[worker.js]"]
  node_functions["Serverless funcs<br/>edge routes"]
end

subgraph group_storage["Storage"]
  node_mysql[("MySQL<br/>durable store")]
  node_redis[("Redis<br/>fast state<br/>[redis.js]")]
  node_browser_state[("Browser state<br/>local storage")]
end

subgraph group_integrations["Integrations"]
  node_tmdb(("TMDB<br/>metadata service"))
  node_identity_providers(("Identity providers<br/>OAuth providers"))
  node_turnstile(("Turnstile<br/>anti-abuse"))
  node_media_sites(("Media sites<br/>provider endpoints"))
end

node_web_app -->|"API calls"| node_main_api
node_web_app -->|"party events"| node_watchparty_api
node_web_app -->|"WASM sync"| node_sync_engine
node_web_app -->|"prefs"| node_browser_state
node_mobile_app -->|"backend"| node_main_api
node_extension -->|"extraction"| node_proxy_embed
node_userscript -->|"page control"| node_media_sites
node_main_api -->|"persistent data"| node_mysql
node_main_api -->|"cache/locks"| node_redis
node_main_api -->|"mounts"| node_main_routes
node_main_api -->|"helpers"| node_main_utils
node_main_api -->|"metadata"| node_tmdb
node_main_api -->|"oauth"| node_identity_providers
node_main_api -->|"abuse checks"| node_turnstile
node_main_api -->|"provider routes"| node_media_sites
node_watchparty_api -->|"protocol"| node_sync_engine
node_sync_worker -->|"executes"| node_sync_engine
node_sync_worker -->|"socket sync"| node_watchparty_api
node_proxy_embed -->|"adapts"| node_media_sites
node_bypass403 -->|"access bypass"| node_media_sites
node_cf_proxy -->|"edge proxy"| node_media_sites
node_rivestream_proxy -->|"edge front"| node_main_api
node_functions -->|"dynamic routes"| node_main_api

click node_web_app "https://github.com/movixcorp/movixopensource/tree/main/src"
click node_mobile_app "https://github.com/movixcorp/movixopensource/tree/main/app"
click node_extension "https://github.com/movixcorp/movixopensource/tree/main/extension"
click node_userscript "https://github.com/movixcorp/movixopensource/tree/main/userscript"
click node_main_api "https://github.com/movixcorp/movixopensource/tree/main/API/Mainapi"
click node_main_routes "https://github.com/movixcorp/movixopensource/tree/main/API/Mainapi/routes"
click node_main_utils "https://github.com/movixcorp/movixopensource/tree/main/API/Mainapi/utils"
click node_redis "https://github.com/movixcorp/movixopensource/blob/main/API/Mainapi/config/redis.js"
click node_watchparty_api "https://github.com/movixcorp/movixopensource/tree/main/API/watchpartyAPI"
click node_sync_engine "https://github.com/movixcorp/movixopensource/tree/main/wasm/watchparty-sync"
click node_sync_worker "https://github.com/movixcorp/movixopensource/blob/main/src/workers/watchpartySync.worker.ts"
click node_proxy_embed "https://github.com/movixcorp/movixopensource/tree/main/API/proxiesembed"
click node_bypass403 "https://github.com/movixcorp/movixopensource/blob/main/API/miscs/bypass403.py"
click node_cf_proxy "https://github.com/movixcorp/movixopensource/blob/main/cloudflareproxy/worker.js"
click node_rivestream_proxy "https://github.com/movixcorp/movixopensource/blob/main/RivestreamCloudflareProxy/worker.js"
click node_functions "https://github.com/movixcorp/movixopensource/tree/main/functions"

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_web_app,node_mobile_app,node_extension,node_userscript toneBlue
class node_main_api,node_main_routes,node_main_utils toneAmber
class node_watchparty_api,node_sync_engine,node_sync_worker toneMint
class node_proxy_embed,node_bypass403,node_cf_proxy,node_rivestream_proxy,node_functions toneRose
class node_mysql,node_redis,node_browser_state toneIndigo
class node_tmdb,node_identity_providers,node_turnstile,node_media_sites toneTeal
```

## Components

### Clients

User-facing applications and browser surfaces

- [Web app](https://github.com/movixcorp/movixopensource/tree/main/src): React/Vite client · Main React frontend for browsing, profiles, playback, VIP, admin, and watchparty flows · `src`
- [Mobile app](https://github.com/movixcorp/movixopensource/tree/main/app): React Native client · Native shell with browser, DNS, casting, updates, and injected web flows · `app`
- [Browser ext](https://github.com/movixcorp/movixopensource/tree/main/extension): browser extension · Chrome and Firefox extension for in-page media interaction and extraction · `extension`
- [Userscript](https://github.com/movixcorp/movixopensource/tree/main/userscript): userscript · Lightweight browser-side integration for media-site behavior · `userscript`

### Core backend

Primary application API and persistence logic

- [Main API](https://github.com/movixcorp/movixopensource/tree/main/API/Mainapi): Node/Express API · Authoritative backend for auth, profiles, sync, search, downloads, VIP, moderation, and provider routes · `API/Mainapi`
- [API domains](https://github.com/movixcorp/movixopensource/tree/main/API/Mainapi/routes): route modules · Domain route surface for auth, profiles, sync, search, download, VIP, comments, admin, and provider adapters · `API/Mainapi/routes`
- [API utils](https://github.com/movixcorp/movixopensource/tree/main/API/Mainapi/utils): backend utilities · Cache, proxy, OAuth, Redis locking, rate limit, TMDB cache, sync policy, and donor/payment helpers · `API/Mainapi/utils`

### Realtime sync

WatchParty coordination and browser sync engine

- [WatchParty API](https://github.com/movixcorp/movixopensource/tree/main/API/watchpartyAPI): Socket.IO service · Dedicated real-time service for synchronized viewing sessions · `API/watchpartyAPI`
- [Sync engine](https://github.com/movixcorp/movixopensource/tree/main/wasm/watchparty-sync): Rust/WASM module · WebAssembly synchronization core used by the browser watchparty flow · `wasm/watchparty-sync`
- [Sync worker](https://github.com/movixcorp/movixopensource/blob/main/src/workers/watchpartySync.worker.ts): web worker · Browser worker that offloads watchparty coordination from the UI thread · `src/workers/watchpartySync.worker.ts`

### Edge layers

Proxy and serverless boundaries

- [Proxy embed](https://github.com/movixcorp/movixopensource/tree/main/API/proxiesembed): Python proxy service · Media gateway for embeds, DRM-related flows, and site-specific extraction adapters · `API/proxiesembed`
- [Bypass 403](https://github.com/movixcorp/movixopensource/blob/main/API/miscs/bypass403.py): Python microservice · Auxiliary proxy service for access-bypass behavior · `API/miscs/bypass403.py`
- [Cloudflare proxy](https://github.com/movixcorp/movixopensource/blob/main/cloudflareproxy/worker.js): worker boundary · Edge proxy worker for routing, CORS, redirects, or preview behavior · `cloudflareproxy/worker.js`
- [Rivestream proxy](https://github.com/movixcorp/movixopensource/blob/main/RivestreamCloudflareProxy/worker.js): worker boundary · Cloudflare worker for Rivestream proxying and edge request handling · `RivestreamCloudflareProxy/worker.js`
- [Serverless funcs](https://github.com/movixcorp/movixopensource/tree/main/functions): edge routes · Netlify-style serverless routes for movie, TV, middleware, and social preview behavior · `functions`

### Storage

Durable and fast state layers

- **MySQL**: durable store · System of record for accounts, lists, comments, VIP, sessions, moderation, and tracking tables
- [Redis](https://github.com/movixcorp/movixopensource/blob/main/API/Mainapi/config/redis.js): fast state · Cache, locks, and rate-limiting store for backend coordination · `API/Mainapi/config/redis.js`
- **Browser state**: local storage · Client-side preferences and session-adjacent state kept in the browser

### Integrations

External identity, metadata, anti-abuse, and media providers

- **TMDB**: metadata service · External metadata source used for titles, artwork, and enrichment
- **Identity providers**: OAuth providers · Discord and Google authentication integrations
- **Turnstile**: anti-abuse · Anti-bot and abuse mitigation used around account and public flows
- **Media sites**: provider endpoints · Upstream streaming and provider sites resolved through proxy and extraction layers

## Connections

- Web app → Main API: API calls · Primary client-server interaction for account, content, VIP, admin, and sync data
- Web app → WatchParty API: party events · Joins and coordinates synchronized viewing sessions
- Web app → Sync engine: WASM sync · Runs deterministic watchparty timing reconciliation in-browser
- Web app → Browser state: prefs · Stores local preferences and session-adjacent state in the browser
- Mobile app → Main API: backend · Uses the same product backend for auth, content, and updates
- Browser ext → Proxy embed: extraction · In-page extraction and playback assistance against media sites
- Userscript → Media sites: page control · Integrates directly with streaming-site pages
- Main API → MySQL: persistent data · Reads and writes authoritative application records
- Main API → Redis: cache/locks · Uses Redis for fast coordination and rate limiting
- Main API → API domains: mounts · Composes domain route modules into the public API surface
- Main API → API utils: helpers · Shares cross-cutting backend helpers and policies
- Main API → TMDB: metadata · Fetches or caches title metadata and artwork
- Main API → Identity providers: oauth · Supports Discord and Google account linking and login flows
- Main API → Turnstile: abuse checks · Applies anti-abuse verification on public actions
- Main API → Media sites: provider routes · Resolves media sources and provider-specific workflows
- WatchParty API → Sync engine: protocol · Relies on the browser sync core for shared session reconciliation
- Sync worker → Sync engine: executes · Runs the WASM sync engine off the main thread
- Sync worker → WatchParty API: socket sync · Relays session state updates to the real-time service
- Proxy embed → Media sites: adapts · Uses site adapters for scraping, embeds, and playback gateways
- Bypass 403 → Media sites: access bypass · Acts as a specialized edge around restricted upstream sites
- Cloudflare proxy → Media sites: edge proxy · Proxies or reshapes requests at the network edge
- Rivestream proxy → Main API: edge front · Sits alongside the main backend as a specialized proxy boundary
- Serverless funcs → Main API: dynamic routes · Serves lightweight dynamic pages and middleware around the core backend