# welovemedia/ffmate architecture

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

- Interactive diagram: https://gitdiagram.com/welovemedia/ffmate
- Repository: https://github.com/welovemedia/ffmate

## Overview

##### Project Type and Purpose
- FFmate is a full-stack media processing service and CLI tool built in Go.
- It provides a REST API (using Gin), a built-in task queue, FFmpeg wrappers, a static Web UI, file-watcher automation, webhooks, and pre/post-processing script hooks.
- Use cases: programmatic transcoding, custom media pipelines, file-drop watchfolders, real-time dashboards, and event webhooks.

##### File Structure
Top-level:
- cmd/ and main.go – Cobra-based CLI entry points (server, init, reset, update, version).
- ui-build/ and swagger.json – pre-built static assets for the Web UI and API spec.
- internal/ – core application code, not for external import.
- internal/controller/ – HTTP handlers and API route definitions.
- internal/service/ – business logic services (Tasks, Presets, Watchfolders, Webhooks, Websocket).
- internal/queue/ – task queue manager and concurrency control.
- internal/ffmpeg/ – wrapper around ffmpeg executable, progress parsing, error handling.
- internal/database/ – GORM models and repository layer for persistence (SQLite).
- internal/dto/ – Data Transfer Objects for API requests and responses.
- internal/middleware & interceptor – Gin middleware and route interceptors (pagination, status, metrics).
- internal/metrics/ – Prometheus metrics exporter.
- sev/ – shared error handling, logging, telemetry, validation code.
- e2e/ – end-to-end tests including UI-based scenario tests.
- config, utils, docs, Dockerfiles, GitHub Actions, Homebrew formula – deployment and CI/CD.

##### Extract Architectural Insights from README
- REST API exposes /api/v1 endpoints for tasks, watchfolders, presets, webhooks, version.
- WebSockets on /ws for real-time logs and status.
- Queue enqueues jobs, controls concurrency, then invokes pre/post script engine and ffmpeg wrapper.
- Persistence via SQLite accessed through repository pattern.
- Static Web UI uses REST + WebSocket.
- Event webhooks: service posts HTTP callbacks to external endpoints.

##### Main Components and Interactions
a.  Main Components
1.  CLI Entry (Cobra)
2.  HTTP Server (Gin) with Controllers
3.  Service Layer (Tasks, Presets, Watchfolders, Webhooks, Websocket)
4.  Queue Manager
5.  Pre/Post-Processing Engine
6.  FFmpeg Wrapper
7.  External FFmpeg Binary
8.  Database (SQLite via GORM)
9.  Static Web UI
10.  External Webhook Endpoints
b.  Interactions and Data Flow
- CLI “server” command starts HTTP server.
- Clients (CLI, Web UI, external apps) → REST API endpoints → Controllers → Services.
- Task Service enqueues into Queue Manager → Queue dispatches to Pre/Post Engine → FFmpeg Wrapper → system call to external ffmpeg.
- Queue Manager persists task states in Database.
- Service layer emits events → Websocket service pushes real-time updates to Web UI.
- Webhook service sends HTTP callbacks to configured external URLs on task events.
- Watchfolder Service monitors filesystem → enqueues tasks automatically.
- Metrics module exposes Prometheus metrics at /metrics.
c.  Architectural Patterns and Principles
- Layered architecture: Transport (Gin controllers) → Application (service layer) → Domain (queue, ffmpeg, DB).
- Repository pattern for data access.
- Dependency inversion: controllers depend on service interfaces.
- Event-driven hooks and interceptors for cross-cutting concerns (logging, pagination, metrics).
- Modular design of pre/post processing for extensibility.
d.  Key Technologies and Frameworks
- Go + Cobra (CLI) + Gin (HTTP) + GORM (ORM) + Prometheus client + WebSocket.
- External: FFmpeg binary.
- Static Web UI (Vue/React) served from ui-build.
- Docker for containerized deployments.
- GitHub Actions, goreleaser, Homebrew for release automation.

##### Essential Architectural Elements
- How a task flows from submission → queue → ffmpeg → completion.
- Extensibility points: pre/post scripts, watchfolder triggers, webhook callbacks.
- Keep it detailed enough for a new engineer to locate code in internal/{controller,service,queue,ffmpeg,database}.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Server (FFmate)"
        direction TB
        Controllers["HTTP Controllers"]:::transport
        Services["Service Layer"]:::service
        Queue["Queue Manager"]:::processing
        PrePost["Pre/Post-Processing Engine"]:::processing
        FFWrap["FFmpeg Wrapper"]:::processing
        FFBin["External FFmpeg Binary"]:::external
        DB["SQLite Database"]:::database
        WS["WebSocket Service"]:::service
        WatchProc["Watchfolder Processor"]:::service
        Metrics["Metrics Module"]:::service
        Middleware["Middleware & Interceptors"]:::service
        DTO["Data Transfer Objects (DTOs)"]:::service
        Sev["Shared Sev Module"]:::service
    end

    CLI["CLI (Cobra)"]:::client
    WebUI["Static Web UI"]:::client
    ExternalApp["External App"]:::client
    WebhookExt["External Webhook Endpoints"]:::external
    e2e["End-to-End Tests"]:::test

    CLI -->|"start server"| Controllers
    WebUI -->|"HTTP REST"| Controllers
    WebUI -->|"WebSocket"| WS
    ExternalApp -->|"HTTP REST"| Controllers
    Controllers -->|"uses DTOs"| DTO
    Controllers -->|"validate & intercept"| Middleware
    Controllers -->|"invoke services"| Services
    Services -->|"enqueue task"| Queue
    Services -->|"emit events"| WS
    Services -->|"post callbacks"| WebhookExt
    Services -->|"access"| DB
    WatchProc -->|"enqueue task"| Queue
    Queue -->|"run scripts"| PrePost
    PrePost -->|"invoke wrapper"| FFWrap
    FFWrap -->|"system call"| FFBin
    Queue -->|"update state"| DB
    Metrics -->|"expose /metrics"| ExternalApp
    Sev -->|"logging/validation"| Controllers
    Sev -->|"metrics hooks"| Metrics

    click Controllers "https://github.com/welovemedia/ffmate/tree/main/internal/controller/"
    click Services "https://github.com/welovemedia/ffmate/tree/main/internal/service/"
    click Queue "https://github.com/welovemedia/ffmate/blob/main/internal/queue/process.go"
    click PrePost "https://github.com/welovemedia/ffmate/blob/main/internal/service/service.go"
    click FFWrap "https://github.com/welovemedia/ffmate/tree/main/internal/ffmpeg/"
    click DB "https://github.com/welovemedia/ffmate/tree/main/internal/database/"
    click WS "https://github.com/welovemedia/ffmate/blob/main/internal/service/websocket.go"
    click WatchProc "https://github.com/welovemedia/ffmate/blob/main/internal/watchfolder/process.go"
    click Metrics "https://github.com/welovemedia/ffmate/blob/main/internal/metrics/metrics.go"
    click Middleware "https://github.com/welovemedia/ffmate/tree/main/internal/middleware/"
    click DTO "https://github.com/welovemedia/ffmate/tree/main/internal/dto/"
    click Sev "https://github.com/welovemedia/ffmate/tree/main/sev/"
    click CLI "https://github.com/welovemedia/ffmate/blob/main/cmd/server.go"
    click WebUI "https://github.com/welovemedia/ffmate/blob/main/ui-build/index.html"
    click e2e "https://github.com/welovemedia/ffmate/blob/main/e2e/main.go"

    classDef client fill:#f9f,stroke:#333,stroke-width:1px;
    classDef transport fill:#ccf,stroke:#333,stroke-width:1px;
    classDef service fill:#cff,stroke:#333,stroke-width:1px;
    classDef processing fill:#fcf,stroke:#333,stroke-width:1px;
    classDef database fill:#ffc,stroke:#333,stroke-width:1px;
    classDef external fill:#fdd,stroke:#333,stroke-width:1px;
    classDef test fill:#dfd,stroke:#333,stroke-width:1px;
```
