Add comprehensive Mermaid.js diagrams to all documentation files

- Main README: System overview and project structure diagrams
- data/README.md: Database ER diagram showing table relationships
- apps/service/README.md: Service architecture with controllers and services
- apps/web/README.md: Web application component structure
- apps/cli/README.md: CLI command hierarchy and structure
- docs/DEVELOPMENT_NOTES.md: Development workflow diagram

README.md

@@ -2,6 +2,52 @@
 
 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
+
+```mermaid
+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
 
 ```bash
@@ -39,3 +85,44 @@ For detailed information, see:
 ├── docs/             # Documentation
 └── scripts/          # Build scripts
 ```
+
+```mermaid
+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
+```

apps/cli/README.md

@@ -2,6 +2,54 @@
 
 A Node.js CLI for interacting with the Watch Finished system. Provides commands for managing files, settings, tasks, and maintenance from the terminal.
 
+## CLI Command Structure
+
+```mermaid
+graph TD
+    CLI[watch-finished-cli] --> INTER[Interactive Mode<br/>Default]
+    CLI --> DIRECT[Direct Commands]
+
+    INTER --> MENU[Menu-Driven Interface<br/>Guided prompts]
+    DIRECT --> HELP[--help<br/>Command reference]
+
+    DIRECT --> FILES[File Commands]
+    DIRECT --> TASKS[Task Commands]
+    DIRECT --> CONFIG[Config Commands]
+    DIRECT --> WATCHER[Watcher Commands]
+    DIRECT --> MAINT[Maintenance Commands]
+
+    FILES --> FLIST[files:list<br/>List dataset files]
+    FILES --> FGET[file:get<br/>Get file details]
+    FILES --> FSET[file:set<br/>Create/update file]
+    FILES --> FREMOVE[file:remove<br/>Delete file]
+    FILES --> FDELETED[files:deleted-older-than<br/>Find old deleted files]
+
+    TASKS --> TLIST[task:list<br/>List all tasks]
+    TASKS --> TGET[task:get<br/>Get task details]
+    TASKS --> TREMOVE[task:remove<br/>Delete task]
+    TASKS --> TSETTINGS[task:queue-settings<br/>Update queue config]
+
+    CONFIG --> CLIST[config:list<br/>List all settings]
+    CONFIG --> CGET[config:get<br/>Get setting value]
+    CONFIG --> CSET[config:set<br/>Update setting]
+
+    WATCHER --> WSTATUS[watcher:status<br/>Get watcher status]
+    WATCHER --> WSTART[watcher:start<br/>Start file watching]
+    WATCHER --> WSTOP[watcher:stop<br/>Stop file watching]
+
+    MAINT --> MCLEANUP[maintenance:cleanup<br/>Clean up files]
+    MAINT --> MPURGE[maintenance:purge<br/>Purge old data]
+    MAINT --> MPRUNE[maintenance:prune<br/>Remove orphaned files]
+
+    style INTER fill:#e3f2fd
+    style DIRECT fill:#f3e5f5
+    style FILES fill:#e8f5e8
+    style TASKS fill:#fff3e0
+    style CONFIG fill:#fce4ec
+    style WATCHER fill:#f1f8e9
+    style MAINT fill:#e0f2f1
+```
+
 ## Usage
 
 ```sh

apps/service/README.md

@@ -2,6 +2,60 @@
 
 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
+
+```mermaid
+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

apps/web/README.md

@@ -2,6 +2,69 @@
 
 A modern Next.js web application providing a complete UI for managing the Watch Finished video processing system.
 
+## Application Structure
+
+```mermaid
+graph TB
+    subgraph "Pages (App Router)"
+        DASH[Dashboard<br/>page.tsx]
+        FILES[Files<br/>files/page.tsx]
+        TASKS[Tasks<br/>tasks/page.tsx]
+        SETTINGS[Settings<br/>settings/page.tsx]
+    end
+
+    subgraph "Components"
+        NAV[Navigation<br/>components/Nav.tsx]
+        WSOCK[WebSocketProvider<br/>providers/WebSocketProvider.tsx]
+        QUERY[QueryProvider<br/>providers/QueryProvider.tsx]
+    end
+
+    subgraph "File Management"
+        FLIST[FileList<br/>components/files/FileList.tsx]
+        FFORM[FileForm<br/>components/files/FileForm.tsx]
+        FMAINT[MaintenanceTools<br/>components/files/MaintenanceTools.tsx]
+    end
+
+    subgraph "Task Management"
+        TLIST[TaskList<br/>components/tasks/TaskList.tsx]
+        TPROGRESS[TaskProgress<br/>components/tasks/TaskProgress.tsx]
+    end
+
+    subgraph "Settings"
+        DSET[DatasetSettings<br/>components/settings/DatasetSettings.tsx]
+        SYSSET[SystemSettings<br/>components/settings/SystemSettings.tsx]
+    end
+
+    subgraph "API Integration"
+        API[API Client<br/>lib/api.ts]
+        WS[WebSocket Client<br/>lib/websocket.ts]
+    end
+
+    DASH --> NAV
+    FILES --> FLIST
+    FILES --> FFORM
+    FILES --> FMAINT
+    TASKS --> TLIST
+    TASKS --> TPROGRESS
+    SETTINGS --> DSET
+    SETTINGS --> SYSSET
+
+    FLIST --> API
+    FFORM --> API
+    FMAINT --> API
+    TLIST --> API
+    TPROGRESS --> WS
+    DSET --> API
+    SYSSET --> API
+
+    WSOCK --> WS
+    QUERY --> API
+
+    style DASH fill:#e3f2fd
+    style API fill:#e8f5e8
+    style WSOCK fill:#f3e5f5
+```
+
 ## Features
 
 - **Dashboard**: Real-time watcher status, task monitoring, and system statistics

data/README.md

@@ -2,6 +2,49 @@
 
 This directory contains the SQLite databases used by the Watch Finished system.
 
+## Database Schema Overview
+
+```mermaid
+erDiagram
+    FILES ||--o{ TASKS : "processed-by"
+    SETTINGS ||--o{ DATASETS : "configures"
+
+    FILES {
+        string dataset PK
+        string input PK
+        string output
+        string status
+        string date
+    }
+
+    TASKS {
+        integer id PK
+        string dataset
+        string input
+        string output
+        string preset
+        string status
+        integer progress
+        string created_at
+        string updated_at
+    }
+
+    SETTINGS {
+        string key PK
+        string value
+    }
+
+    DATASETS {
+        string name PK
+        boolean enabled
+        string destination
+        string exts
+        string ext
+        string preset
+        string clean
+    }
+```
+
 ## Files
 
 - `database.db` - Main application database containing:

docs/DEVELOPMENT_NOTES.md

@@ -1,5 +1,47 @@
 # Project Development Notes
 
+## Development Workflow
+
+```mermaid
+graph TD
+    A[Start Development] --> B[Install Dependencies]
+    B --> C{pnpm install}
+
+    C --> D[Choose Development Mode]
+    D --> E[Full Stack<br/>pnpm run dev]
+    D --> F[Individual Services]
+    D --> G[Docker Setup]
+
+    E --> H[Web + Service<br/>Hot Reload Enabled]
+    F --> I[Web Only<br/>pnpm run web]
+    F --> J[Service Only<br/>pnpm run service]
+    F --> K[CLI Only<br/>pnpm run cli]
+
+    G --> L[docker-compose up]
+
+    H --> M[Make Changes]
+    I --> M
+    J --> M
+    K --> M
+    L --> M
+
+    M --> N{File Changed?}
+    N -->|Yes| O[Hot Reload<br/>Automatic]
+    N -->|No| P[Test Changes]
+
+    O --> P
+    P --> Q[Check Browser/CLI]
+    Q --> R{Working?}
+    R -->|Yes| M
+    R -->|No| S[Debug Issues]
+    S --> M
+
+    style A fill:#e3f2fd
+    style H fill:#e8f5e8
+    style O fill:#fff3e0
+    style S fill:#ffebee
+```
+
 ## Package Manager
 
 This project uses **pnpm** as the package manager. Always use `pnpm` commands instead of `npm` or `yarn`.