# ttqftech/ffbox architecture

> Architecture diagram of the GitHub repository ttqftech/ffbox, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ttqftech/ffbox
- Repository: https://github.com/ttqftech/ffbox

## Overview

##### Project type and purpose
- This is an Electron‐based full‑stack desktop application (“FFBox”) that provides a GUI shell over FFmpeg for local and remote media transcoding.
- It strictly separates frontend (renderer), backend (Node/Electron main), native OS helpers (C++ binary), and remote control (built‑in HTTP server).

##### File structure
- Top‐level config and scripts: custom Vite/Vue/Electron build and dev scripts (`config/*.ts/js`, `scripts/*.mjs`).
- Native helper: `src/WindowsHelper/FFBoxHelper` (C++ Visual Studio project producing `FFBoxHelper.exe`).
- Electron backend: `src/main` (main process code, OSBridge), `src/preload` (context‑bridge), `src/backend` (services, FFmpeg invocation, UI bridge, webui server).
- Shared code: `src/common` (types, constants, spawning utilities).
- Renderer: `src/renderer` (Vue 3 + TypeScript, UI components, nodeBridge/serviceBridge, public assets).
- Packaging config: `electron-builder.json5`, platform config in `config/pkg.*.config.json`, WindowsInstaller scripts.

##### Key README insights
- Versions 4.x: complete front/back separation, custom build scripts.
- Dev flow:
- `dev-frontend.mjs` → live‐reload renderer + watch preload/main
- `build-backend.mjs` → compiles & bundles backend
- `build-frontend.mjs` → builds main/preload/renderer
- VSCode tasks and npm scripts orchestrate these
- Package step triggers `electron-builder` to produce cross‑platform installers, using WindowsInstaller `.iss` scripts for Windows.

##### Final advice
- Be exhaustive: capture all significant modules and data flows.
- Both build/deploy flow (scripts → electron-builder → installers) and runtime flow.
- Keep labels clear and consistent with code folder names (e.g., FFBoxService, osBridge).

## Diagram (Mermaid)

```mermaid
flowchart TD
  subgraph "Renderer (Vue 3 App)"
    UI["Renderer UI"]:::renderer
  end

  subgraph "Preload (ContextBridge)"
    PreloadIndex["index.js"]:::electronCore
    PreloadLoading["loading.ts"]:::electronCore
    PreloadUtils["utils.ts"]:::electronCore
    PreloadTypes["index.d.ts"]:::electronCore
  end

  subgraph "Main (Electron Core)"
    MainIndex["index.ts"]:::electronCore
    OSBridgeMain["osBridge.ts"]:::electronCore
    MainUtils["utils.ts"]:::electronCore
    Mica["mica.ts"]:::electronCore
  end

  subgraph "Backend Services"
    FFBoxService["FFBoxService.ts"]:::backend
    FFmpegInvoke["FFmpegInvoke.ts"]:::backend
    BackendOSBridge["osBridge.ts"]:::backend
    UIBridge["uiBridge.ts"]:::backend
    WebUIServer["webuiServer.ts"]:::backend
  end

  subgraph "Common Library"
    Constants["constants.ts"]:::common
    Types["types.ts"]:::common
    Utils["utils.ts"]:::common
    SpawnInvoker["spawnInvoker.ts"]:::common
    CommonAll["src/common/*"]:::common
  end

  subgraph "Native / External"
    FFmpegCLI["FFmpeg CLI"]:::external
    FFBoxHelper["FFBoxHelper.exe"]:::external
  end

  subgraph "Build & Packaging"
    Config["Config Files"]:::build
    Scripts["Build/Dev Scripts"]:::build
    InstallerScripts["Windows Installer Scripts"]:::build
  end

  UI -->|"serviceBridge/nodeBridge"| PreloadIndex
  PreloadIndex -->|"contextBridge"| MainIndex
  MainIndex -->|"dispatch to"| FFBoxService
  MainIndex -->|"dispatch to"| WebUIServer
  FFBoxService -->|"uses"| FFmpegInvoke
  FFmpegInvoke -->|"child_process.spawn"| FFmpegCLI
  FFBoxService -->|"calls"| BackendOSBridge
  BackendOSBridge -->|"shell out"| FFBoxHelper
  MainIndex -->|"uses"| CommonAll
  PreloadIndex -->|"uses"| CommonAll
  FFBoxService -->|"shares code"| CommonAll
  Scripts -->|"invoke build"| Config
  Scripts -->|"invoke package"| InstallerScripts

  classDef renderer fill:#cce5ff,stroke:#002766,color:#002766;
  classDef electronCore fill:#d4edda,stroke:#155724,color:#155724;
  classDef backend fill:#fff3cd,stroke:#856404,color:#856404;
  classDef external fill:#f8d7da,stroke:#721c24,color:#721c24;
  classDef common fill:#e2e3e5,stroke:#6c757d,color:#6c757d;
  classDef build fill:#f0f0f0,stroke:#4a4a4a,color:#4a4a4a;

  click UI "https://github.com/ttqftech/ffbox/tree/4.0+/src/renderer"
  click PreloadIndex "https://github.com/ttqftech/ffbox/blob/4.0+/src/preload/index.js"
  click PreloadLoading "https://github.com/ttqftech/ffbox/blob/4.0+/src/preload/loading.ts"
  click PreloadUtils "https://github.com/ttqftech/ffbox/blob/4.0+/src/preload/utils.ts"
  click PreloadTypes "https://github.com/ttqftech/ffbox/blob/4.0+/src/preload/index.d.ts"
  click MainIndex "https://github.com/ttqftech/ffbox/blob/4.0+/src/main/index.ts"
  click OSBridgeMain "https://github.com/ttqftech/ffbox/blob/4.0+/src/main/osBridge.ts"
  click MainUtils "https://github.com/ttqftech/ffbox/blob/4.0+/src/main/utils.ts"
  click Mica "https://github.com/ttqftech/ffbox/blob/4.0+/src/main/mica.ts"
  click FFBoxService "https://github.com/ttqftech/ffbox/blob/4.0+/src/backend/FFBoxService.ts"
  click FFmpegInvoke "https://github.com/ttqftech/ffbox/blob/4.0+/src/backend/FFmpegInvoke.ts"
  click BackendOSBridge "https://github.com/ttqftech/ffbox/blob/4.0+/src/backend/osBridge.ts"
  click UIBridge "https://github.com/ttqftech/ffbox/blob/4.0+/src/backend/uiBridge.ts"
  click WebUIServer "https://github.com/ttqftech/ffbox/blob/4.0+/src/backend/webuiServer.ts"
  click Constants "https://github.com/ttqftech/ffbox/blob/4.0+/src/common/constants.ts"
  click Types "https://github.com/ttqftech/ffbox/blob/4.0+/src/common/types.ts"
  click Utils "https://github.com/ttqftech/ffbox/blob/4.0+/src/common/utils.ts"
  click SpawnInvoker "https://github.com/ttqftech/ffbox/blob/4.0+/src/common/spawnInvoker.ts"
  click CommonAll "https://github.com/ttqftech/ffbox/tree/4.0+/src/common/*"
  click FFBoxHelper "https://github.com/ttqftech/ffbox/tree/4.0+/src/WindowsHelper/FFBoxHelper"
  click Config "https://github.com/ttqftech/ffbox/blob/4.0+/config/vite.main.ts"
  click Scripts "https://github.com/ttqftech/ffbox/blob/4.0+/scripts/dev-frontend.mjs"
  click InstallerScripts "https://github.com/ttqftech/ffbox/blob/4.0+/WindowsInstaller/FFBox.iss"
```
