System Architecture
Freak-Flix utilizes a modern, distributed architecture designed for high performance and privacy. The system is divided into three primary layers: a Multi-Platform Frontend (Flutter), an Edge API Layer (Cloudflare Workers), and Serverless Utility Functions (Netlify).
🏛️ High-Level Component Overview
The architecture is designed to handle local media indexing and cloud-based streaming simultaneously while offloading heavy metadata processing to specialized external providers.
| Layer | Technology | Responsibility | | :--- | :--- | :--- | | Frontend | Flutter (Dart) | UI/UX, Video Playback (MediaKit), Local File Scanning. | | Edge Backend | Hono + Cloudflare D1 | User Authentication, Library State, Edge-side Microsoft Proxying. | | Serverless Layer | Netlify Functions | StashDB GraphQL Proxying, Netlify Identity Webhooks, Legacy Auth. | | Storage/Metadata | External APIs | TMDB, AniList, StashDB, OneDrive, local filesystem. |
💻 Frontend Architecture (Flutter)
The frontend is a cross-platform application that manages both UI rendering and hardware-accelerated media playback.
Platform Adapters
- Windows: Utilizes a Win32 runner with
mpv-1.dllintegration viamedia_kitfor high-bitrate local playback. - Android: Uses native platform views for mobile-optimized streaming.
- Web: Compiled to JavaScript/CanvasKit with Auth0 SPA integration for secure web access.
Key Client-Side Services
- Library Scanner: On Desktop/Mobile, the app performs recursive directory walks to identify media.
- Metadata Orchestrator: Aggregates data from multiple sources (TMDB for movies, AniList for anime) based on filename parsing.
⚡ Edge Backend (Cloudflare Workers & D1)
The core API resides at the edge to ensure low-latency authentication and library management. It uses the Hono framework and Cloudflare D1 for relational data storage.
Authentication API
The system uses JWT-based authentication for secure session management.
Endpoint: POST /auth/register
- Input:
{ "email": "user@example.com", "password": "securepassword" } - Action: Hashes password via
bcryptand stores user in D1.
Endpoint: POST /auth/login
- Input:
{ "email": "user@example.com", "password": "securepassword" } - Output:
{ "token": "JWT_STRING", "user": { ... } }
Library Management
Endpoint: POST /library/scan
- Authorization: Bearer Token required.
- Body:
{ "folderId": "ONEDRIVE_ID", "accessToken": "MS_GRAPH_TOKEN", "path": "/Movies", "provider": "onedrive" } - Action: Triggers a recursive scan of the provided cloud or local directory.
☁️ Serverless Utility Functions (Netlify)
Netlify Functions act as secure intermediaries for third-party services, handling CORS headers and API key masking.
1. StashDB Proxy (stash_proxy.js)
Since StashDB uses GraphQL and may have restrictive CORS policies, Freak-Flix routes requests through this proxy.
- Usage: The client sends standard GraphQL queries to the proxy.
- Header Requirement:
ApiKeymust be passed in the request header.
2. Microsoft Auth Proxy (ms_auth_proxy.js)
Used to facilitate the OAuth2 flow with OneDrive without exposing client secrets on the frontend.
- Path:
/api/ms_auth/{tenant}/oauth2/v2.0/token - Role: Forwards authentication requests to
login.microsoftonline.comwhile stripping problematic browser headers.
3. Identity Webhooks (identity-webhook.js)
Automates user provisioning when using Netlify Identity.
- Trigger: Fires on
signuporloginevents. - Action: Synchronizes the user profile into a PostgreSQL database for extended metadata storage.
🔄 Data Flow: Metadata Enrichment
- Identification: The app parses the filename (e.g.,
Big.Buck.Bunny.2008.mp4). - Request:
- If Movie/TV: Queries TMDB API directly from the client using the configured API Key.
- If Anime: Queries AniList via GraphQL.
- If Adult: Queries the
stash_proxy.jsendpoint to fetch StashDB tags and performers.
- UI Injection: Metadata is cached locally in an internal state manager (Provider/Riverpod) to provide the "Netflix-style" immersive interface.
🛡️ Privacy and Security
- Content Segregation: Adult content metadata is fetched via a dedicated proxy and can be toggled off at the UI level.
- Credential Safety: API keys for StashDB and TMDB are stored locally on the user's device or passed through encrypted environment variables in the proxy layer.
- Cloud Streaming: OneDrive tokens are never stored on the Freak-Flix backend; they are held in the client's secure storage and used only for direct MS Graph API calls.