watch-finished-turbo/apps/service

Watch Finished API Service

A NestJS-based REST API service for the Watch Finished system. Provides endpoints for file management, task processing, configuration, and real-time WebSocket communication.

Service Architecture

graph TB
    subgraph "Controllers"
        FC[FilesController<br/>/files/*]
        TC[TasksController<br/>/tasks/*]
        CC[ConfigController<br/>/config/*]
        WC[WatcherController<br/>/watcher/*]
        MC[MaintenanceController<br/>/maintenance/*]
    end

    subgraph "Services"
        FS[FilesService<br/>CRUD operations]
        TS[TasksService<br/>Queue management]
        CS[ConfigService<br/>Settings]
        WS[WatcherService<br/>File monitoring]
        HS[HandbrakeService<br/>Video processing]
        DBS[DbService<br/>SQLite access]
        MS[MaintenanceService<br/>Cleanup]
    end

    subgraph "Gateway"
        EG[EventsGateway<br/>WebSocket events]
    end

    subgraph "Database"
        DB[(SQLite)]
    end

    FC --> FS
    TC --> TS
    CC --> CS
    WC --> WS
    MC --> MS

    FS --> DBS
    TS --> DBS
    CS --> DBS
    WS --> DBS
    MS --> DBS

    WS --> TS
    TS --> HS
    HS --> EG

    DBS --> DB
    EG --> EG

    style FC fill:#e3f2fd
    style EG fill:#f3e5f5
    style DB fill:#e8f5e8

Features

• File Management: CRUD operations for processed video files organized by datasets
• Task Processing: Queue-based video encoding with HandBrake integration
• Configuration: Centralized settings management with SQLite storage
• Watcher Service: File system monitoring for automatic processing
• WebSocket Events: Real-time updates for web clients
• Maintenance Tools: Cleanup, purge, and prune operations

Tech Stack

• Framework: NestJS with TypeScript
• Database: SQLite with better-sqlite3
• WebSocket: Socket.IO for real-time communication
• Video Processing: HandBrake CLI integration
• File Watching: chokidar for directory monitoring

API Endpoints

Files

• GET /files - List all datasets
• GET /files/:dataset/:file - Get specific file
• POST /files/:dataset/:file - Create/update file
• DELETE /files/:dataset/:file - Delete file
• POST /files/:dataset/:file/requeue - Requeue for processing

Tasks

• GET /tasks - List all tasks
• GET /tasks/:id - Get task details
• DELETE /tasks/:id - Delete task
• POST /tasks/queue/settings - Update queue settings

Configuration

• GET /config/settings - Get all settings
• POST /config/settings - Update settings
• GET /config/settings/:key - Get specific setting

Watcher

• GET /watcher/status - Get watcher status
• POST /watcher/start - Start file watcher
• POST /watcher/stop - Stop file watcher

Maintenance

• POST /maintenance/cleanup - Clean up processed files
• POST /maintenance/purge - Purge old files
• POST /maintenance/prune - Remove empty directories

HandBrake

• GET /handbrake/presets - Get available presets
• POST /handbrake/process - Process video with HandBrake

WebSocket Events

The service emits real-time events via Socket.IO:

• taskUpdate - Task progress and status changes
• fileUpdate - File additions, updates, deletions
• watcherUpdate - Watcher start/stop status
• maintenanceUpdate - Maintenance operation results

Database

Uses SQLite database stored at ../../../data/database.db relative to the service directory. Contains tables for:

• files - Processed video files
• tasks - Processing queue
• settings - Configuration values

Development

# Install dependencies
pnpm install

# Run in development mode with hot reload
pnpm run start:dev

# Build for production
pnpm run build
pnpm run start:prod

Environment Variables

• PORT - Server port (default: 3001)
• Database path is hardcoded relative to project root

import { io } from 'socket.io-client';

const socket = io('http://localhost:3000');

// Listen for events
socket.on('fileUpdate', (data) => {
  console.log('File update:', data);
});

socket.on('watcherUpdate', (data) => {
  console.log('Watcher update:', data);
});

Room Support

Clients can join/leave rooms for targeted messaging:

// Join a room
socket.emit('join', { room: 'dashboard' });

// Leave a room
socket.emit('leave', { room: 'dashboard' });

---

Nest framework TypeScript starter repository.

Project setup

$ pnpm install

Compile and run the project

# development
$ pnpm run start

# watch mode
$ pnpm run start:dev

# production mode
$ pnpm run start:prod

Run tests

# unit tests
$ pnpm run test

# e2e tests
$ pnpm run test:e2e

# test coverage
$ pnpm run test:cov

Deployment

When you're ready to deploy your NestJS application to production, there are some key steps you can take to ensure it runs as efficiently as possible. Check out the deployment documentation for more information.

If you are looking for a cloud-based platform to deploy your NestJS application, check out Mau, our official platform for deploying NestJS applications on AWS. Mau makes deployment straightforward and fast, requiring just a few simple steps:

$ pnpm install -g @nestjs/mau
$ mau deploy

With Mau, you can deploy your application in just a few clicks, allowing you to focus on building features rather than managing infrastructure.

Resources

Check out a few resources that may come in handy when working with NestJS:

• Visit the NestJS Documentation to learn more about the framework.
• For questions and support, please visit our Discord channel.
• To dive deeper and get more hands-on experience, check out our official video courses.
• Deploy your application to AWS with the help of NestJS Mau in just a few clicks.
• Visualize your application graph and interact with the NestJS application in real-time using NestJS Devtools.
• Need help with your project (part-time to full-time)? Check out our official enterprise support.
• To stay in the loop and get updates, follow us on X and LinkedIn.
• Looking for a job, or have a job to offer? Check out our official Jobs board.

Support

Nest is an MIT-licensed open source project. It can grow thanks to the sponsors and support by the amazing backers. If you'd like to join them, please read more here.

Stay in touch

• Author - Kamil Myśliwiec
• Website - https://nestjs.com
• Twitter - @nestframework

License

Nest is MIT licensed.

Watch Finished API Service

A modern NestJS API for managing files, settings, watcher, and tasks, all backed by a unified SQLite database.

API Overview

• Base URL: http://localhost:3000
• Authentication: None (local network only by default)

Main Endpoints

• GET /files — List available datasets
• POST /files/:dataset/:file — Create file record
• POST /files/:dataset/:file/update — Update file record
• GET /files/:dataset/:file — Get file record
• DELETE /files/:dataset/:file — Delete file record
• GET /files/:dataset/status/:status — List files by status
• GET /files/:dataset/deleted-older-than/:isoDate — List deleted files older than date
• POST /files/expire — Delete expired files

• POST /files/migrate — Migrate legacy JSON to SQLite

• GET /config/settings — Get all settings

• GET /config/settings?key=... — Get setting by key

• POST /config/settings — Update setting

• DELETE /config/settings/:key — Delete setting

• GET /watcher/status — Get watcher status

• POST /watcher/start — Start watcher

• POST /watcher/stop — Stop watcher

• GET /tasks — List tasks

• POST /tasks — Create task

• DELETE /tasks/:id — Delete task

• GET / — API root

• GET /ready — Readiness probe

• GET /health — Health check

Database Structure

• settings: All config and datasets (JSON)
• files: All file records
• task: Task queue and progress

API Flow (MermaidJS)

flowchart TD
    A[Client (Web/CLI)] -->|REST| B(API Service)
    B -->|SQL| C[(SQLite database)]
    B --> D[Watcher]
    B --> E[HandBrake]
    B --> F[Maintenance]

Example: File CRUD

POST /files/movies/myfile.mp4
{
  "output": "output.mp4",
  "status": "success",
  "date": "2025-12-30T12:00:00Z"
}

Error Handling

• All endpoints return JSON
• 4xx for client errors, 5xx for server errors

---

See ../docs/README.md for full project documentation.