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.

💻 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.dll integration via media_kit for 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 bcrypt and 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: ApiKey must 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.com while stripping problematic browser headers.

3. Identity Webhooks (`identity-webhook.js`)

Automates user provisioning when using Netlify Identity.

Trigger: Fires on signup or login events.
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.js endpoint 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.