How welovemedia/ffmate works
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}.