watch-finished-turbo

Watch Finished Turbo

A modern, full-stack video processing system built with Turborepo. Automatically monitors directories, processes videos with HandBrake, and provides a complete web interface for management.

System Overview

graph TB
    subgraph "User Interfaces"
        WEB[Web Dashboard<br/>Next.js + React]
        CLI[Command Line<br/>Node.js CLI]
    end

    subgraph "API Service"
        NEST[NestJS Server<br/>REST + WebSocket]
    end

    subgraph "Core Services"
        WATCH[File Watcher<br/>Chokidar]
        QUEUE[Task Queue<br/>Background Processing]
        HANDBRAKE[Video Encoder<br/>HandBrake CLI]
    end

    subgraph "Data Storage"
        DB[(SQLite Database<br/>Files & Tasks)]
    end

    subgraph "File System"
        INPUT[Input Directories<br/>Video Files]
        OUTPUT[Output Directories<br/>Processed Videos]
    end

    WEB --> NEST
    CLI --> NEST
    NEST --> WATCH
    NEST --> QUEUE
    QUEUE --> HANDBRAKE
    WATCH --> DB
    QUEUE --> DB
    HANDBRAKE --> DB
    WATCH --> INPUT
    HANDBRAKE --> OUTPUT

    style WEB fill:#e3f2fd
    style NEST fill:#f3e5f5
    style DB fill:#e8f5e8
    style INPUT fill:#fff3e0
    style OUTPUT fill:#e0f2f1

Quick Start

Option 1: Dev Container (Recommended)

For the most consistent development experience, use the included dev container:

1. Open in VS Code
2. When prompted, click "Reopen in Container"
3. Wait for the container to build and dependencies to install
4. Start developing!

See .devcontainer/README.md for detailed setup instructions.

Option 2: Local Development

If you prefer local development:

Prerequisites

Install pnpm (if not already installed):

# Using npm (recommended)
npm install -g pnpm

# Using Homebrew (macOS)
brew install pnpm

# Using other package managers
# See: https://pnpm.io/installation

Setup

# Install dependencies
pnpm install

# Start all services (web + API)
pnpm run dev

# Or start individually
pnpm run web      # Web interface on :3000
pnpm run service  # API server on :3001
pnpm run cli      # Interactive CLI

Docker Support

The project includes Docker support for containerized deployment and development.

Running with Docker Compose

# Build and run the application
docker-compose up --build

# Run in detached mode
docker-compose up -d

# View logs
docker-compose logs -f

# Stop the application
docker-compose down

Docker Image Features

The Docker image includes:

• Node.js 20 with pnpm package manager
• HandBrake CLI for video processing
• FFmpeg for media operations
• SQLite3 for database management
• CLI as Default Shell: The container starts with the interactive CLI by default

Using the CLI in Docker

# Interactive CLI (default)
docker-compose run --rm app

# Direct CLI commands
docker-compose run --rm app files:list --dataset movies
docker-compose run --rm app task:list

# Override to run development servers
docker-compose run --rm app pnpm dev

Data Persistence

Database files are persisted in the ./data directory and mounted into the container for data persistence across container restarts.

Project Structure

├── apps/
│   ├── web/          # Next.js web interface
│   ├── service/      # NestJS API server
│   └── cli/          # Command-line interface
├── packages/         # Shared configurations
├── data/             # SQLite database
├── docs/             # Documentation
└── scripts/          # Build scripts

graph TD
    ROOT[watch-finished-turbo/] --> APPS[apps/]
    ROOT --> PACKAGES[packages/]
    ROOT --> DATA[data/]
    ROOT --> DOCS[docs/]
    ROOT --> SCRIPTS[scripts/]
    ROOT --> CONFIG[Configuration Files<br/>package.json, turbo.json, etc.]

    APPS --> WEB[web/<br/>Next.js UI]
    APPS --> SERVICE[service/<br/>NestJS API]
    APPS --> CLI[cli/<br/>Node.js CLI]

    PACKAGES --> ESLINT[eslint-config/<br/>Shared linting]
    PACKAGES --> TSCONFIG[typescript-config/<br/>Shared TS config]
    PACKAGES --> UI[ui/<br/>Shared components]

    DATA --> DB[(database.db<br/>SQLite)]
    DATA --> BACKUP[database.db.bak]

    DOCS --> ARCH[architecture.md<br/>System design]
    DOCS --> DEV[DEVELOPMENT_NOTES.md<br/>Dev guide]
    DOCS --> CLI_DOCS[cli.md<br/>CLI reference]

    WEB --> W_SRC[src/app/<br/>Pages]
    WEB --> W_COMP[src/components/<br/>UI components]
    WEB --> W_LIB[src/lib/<br/>Utilities]

    SERVICE --> S_SRC[src/<br/>Controllers & Services]
    SERVICE --> S_TEST[test/<br/>Unit tests]

    CLI --> C_SRC[src/<br/>CLI commands]
    CLI --> C_BIN[bin/<br/>Entry point]

    style ROOT fill:#e3f2fd
    style APPS fill:#f3e5f5
    style PACKAGES fill:#e8f5e8
    style DATA fill:#fff3e0
    style DOCS fill:#fce4ec

Key Features

Automated Processing

• Intelligent File Watching: Automatically detects new video files in configured directories
• Queue Management: Priority-based task queue with configurable concurrency and retry logic
• HandBrake Integration: High-quality video encoding with real-time progress tracking
• Dataset Organization: Flexible configuration for different video categories (Movies, TV, Sports, etc.)

Modern Web Interface

• Real-time Updates: WebSocket-powered live progress and status updates
• Persistent Preferences: Filter selections and search terms saved via localStorage
• Responsive Design: Clean, modern UI with dark mode support
• Efficient Loading: Proper loading states prevent "flash of empty content"
• Advanced Filtering: Multi-select datasets, status filters, and search across all fields

Developer Experience

• Hot Reload: Instant feedback during development for both frontend and backend
• Type Safety: Full TypeScript support across all applications
• Monorepo Structure: Turborepo for efficient builds and shared packages
• Dev Container: Consistent development environment with Docker
• Comprehensive Docs: Detailed architecture diagrams and API documentation

Data Management

• Simplified Schema: Clean separation between file observations and task processing
• Automatic Migration: Database schema updates handled automatically
• Efficient Queries: Optimized SQLite operations with proper indexing
• Cache Management: React Query for intelligent data caching and updates