# stippiedot/videocull architecture

> Architecture diagram of the GitHub repository stippiedot/videocull, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/stippiedot/videocull
- Repository: https://github.com/stippiedot/videocull

## Overview

VideoCull is a local Windows video-triage app: users load folders, inspect generated thumbnail strips in a grid or focused player, mark review decisions, compare duplicates, and confirm deletion. The graph captures the renderer-to-Electron workflow plus cache, media processing, and duplicate analysis; export and maintenance are retained as documented capabilities. Arrows use explicit README statements or shown references/calls; unsampled subsystems are linked only where documentation supports the relationship.

Main entry points: [`electron/main.js`](https://github.com/stippiedot/videocull/blob/main/electron/main.js) (Electron main process), [`src/App.tsx`](https://github.com/stippiedot/videocull/blob/main/src/App.tsx) (App shell), [`src/store.ts`](https://github.com/stippiedot/videocull/blob/main/src/store.ts) (Renderer state), [`src/components/SettingsModal.tsx`](https://github.com/stippiedot/videocull/blob/main/src/components/SettingsModal.tsx) (Settings and export)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_renderer["Review interface"]
  node_app["App shell<br/>[App.tsx]"]
  node_grid["Video grid<br/>[GridMode.tsx]"]
  node_review["Focused player<br/>[ReviewMode.tsx]"]
  node_sidebar["Search and filters<br/>[Sidebar.tsx]"]
  node_settings["Settings and export<br/>[SettingsModal.tsx]"]
  node_duplicate_view["Duplicate review"]
  node_commands["App commands<br/>[appCommands.ts]"]
end

subgraph group_main["Desktop orchestration"]
  node_electron["Electron main process<br/>[main.js]"]
end

subgraph group_media["Media analysis"]
  node_scanner["Folder scanner<br/>[scanner.js]"]
  node_processor["Thumbnail and metadata processor<br/>[processor.js]"]
end

subgraph group_state["Review state and cache"]
  node_store["Renderer state<br/>[store.ts]"]
  node_cache[("SQLite cache<br/>[cache.js]")]
  node_cache_migration["Cache migration<br/>[cache-migration.js]"]
end

subgraph group_duplicates["Duplicate comparison"]
  node_duplicates["Duplicate detection<br/>[duplicates.js]"]
  node_visual_worker["Visual comparison worker<br/>[visual-worker.js]"]
end

node_person(("Video reviewer"))
node_filesystem[("Video folders")]
node_recycle_bin["Windows Recycle Bin"]
node_external_player["External video player"]
node_report["HTML report"]

node_person -->|"reviews videos"| node_app
node_app -->|"renders"| node_grid
node_app -->|"renders"| node_review
node_app -->|"renders"| node_sidebar
node_app -->|"renders"| node_settings
node_app -->|"renders"| node_duplicate_view
node_grid -->|"reads and updates"| node_store
node_review -->|"reads and updates"| node_store
node_sidebar -->|"filters and updates"| node_store
node_settings -->|"updates settings"| node_store
node_duplicate_view -->|"reads duplicate state"| node_store
node_app -.->|"invokes desktop APIs"| node_electron
node_commands -->|"dispatches commands"| node_electron
node_electron -->|"scans directories"| node_scanner
node_scanner -.->|"reads video files"| node_filesystem
node_electron -->|"processes videos"| node_processor
node_processor -.->|"samples video frames"| node_filesystem
node_electron -->|"reads and writes state"| node_cache
node_electron -->|"runs migration"| node_cache_migration
node_cache -->|"persists review and media data"| node_filesystem
node_electron -->|"runs duplicate detection"| node_duplicates
node_duplicates -->|"delegates visual comparison"| node_visual_worker
node_duplicates -.->|"uses cached video data"| node_cache
node_settings -.->|"generates report"| node_report
node_electron -.->|"moves confirmed deletes"| node_recycle_bin
node_commands -->|"opens video"| node_external_player

click node_app "https://github.com/stippiedot/videocull/blob/main/src/App.tsx"
click node_grid "https://github.com/stippiedot/videocull/blob/main/src/components/GridMode.tsx"
click node_review "https://github.com/stippiedot/videocull/blob/main/src/components/ReviewMode.tsx"
click node_sidebar "https://github.com/stippiedot/videocull/blob/main/src/components/Sidebar.tsx"
click node_settings "https://github.com/stippiedot/videocull/blob/main/src/components/SettingsModal.tsx"
click node_duplicate_view "https://github.com/stippiedot/videocull/blob/main/src/components/DuplicateGroupsView.tsx"
click node_store "https://github.com/stippiedot/videocull/blob/main/src/store.ts"
click node_commands "https://github.com/stippiedot/videocull/blob/main/src/appCommands.ts"
click node_electron "https://github.com/stippiedot/videocull/blob/main/electron/main.js"
click node_scanner "https://github.com/stippiedot/videocull/blob/main/electron/scanner.js"
click node_processor "https://github.com/stippiedot/videocull/blob/main/electron/processor.js"
click node_duplicates "https://github.com/stippiedot/videocull/blob/main/electron/duplicates.js"
click node_visual_worker "https://github.com/stippiedot/videocull/blob/main/electron/visual-worker.js"
click node_cache "https://github.com/stippiedot/videocull/blob/main/electron/cache.js"
click node_cache_migration "https://github.com/stippiedot/videocull/blob/main/electron/cache-migration.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app,node_grid,node_review,node_sidebar,node_settings,node_duplicate_view,node_commands,node_person toneBlue
class node_electron,node_filesystem toneAmber
class node_scanner,node_processor toneMint
class node_store,node_cache,node_cache_migration toneRose
class node_duplicates,node_visual_worker,node_recycle_bin,node_external_player,node_report toneIndigo
```

## Components

### Review interface

- [App shell](https://github.com/stippiedot/videocull/blob/main/src/App.tsx): `src/App.tsx`
- [Video grid](https://github.com/stippiedot/videocull/blob/main/src/components/GridMode.tsx): `src/components/GridMode.tsx`
- [Focused player](https://github.com/stippiedot/videocull/blob/main/src/components/ReviewMode.tsx): `src/components/ReviewMode.tsx`
- [Search and filters](https://github.com/stippiedot/videocull/blob/main/src/components/Sidebar.tsx): `src/components/Sidebar.tsx`
- [Settings and export](https://github.com/stippiedot/videocull/blob/main/src/components/SettingsModal.tsx): `src/components/SettingsModal.tsx`
- [Duplicate review](https://github.com/stippiedot/videocull/blob/main/src/components/DuplicateGroupsView.tsx): `src/components/DuplicateGroupsView.tsx`
- [App commands](https://github.com/stippiedot/videocull/blob/main/src/appCommands.ts): `src/appCommands.ts`

### Desktop orchestration

- [Electron main process](https://github.com/stippiedot/videocull/blob/main/electron/main.js): `electron/main.js`

### Media analysis

- [Folder scanner](https://github.com/stippiedot/videocull/blob/main/electron/scanner.js): `electron/scanner.js`
- [Thumbnail and metadata processor](https://github.com/stippiedot/videocull/blob/main/electron/processor.js): `electron/processor.js`

### Review state and cache

- [Renderer state](https://github.com/stippiedot/videocull/blob/main/src/store.ts): `src/store.ts`
- [SQLite cache](https://github.com/stippiedot/videocull/blob/main/electron/cache.js): `electron/cache.js`
- [Cache migration](https://github.com/stippiedot/videocull/blob/main/electron/cache-migration.js): `electron/cache-migration.js`

### Duplicate comparison

- [Duplicate detection](https://github.com/stippiedot/videocull/blob/main/electron/duplicates.js): `electron/duplicates.js`
- [Visual comparison worker](https://github.com/stippiedot/videocull/blob/main/electron/visual-worker.js): `electron/visual-worker.js`

### Other components

- **Video reviewer**
- **Video folders**
- **Windows Recycle Bin**
- **External video player**
- **HTML report**

## Connections

- Video reviewer → App shell: reviews videos (evidence: `README.md`)
- App shell → Video grid: renders (evidence: `src/App.tsx`)
- App shell → Focused player: renders (evidence: `src/App.tsx`)
- App shell → Search and filters: renders (evidence: `src/App.tsx`)
- App shell → Settings and export: renders (evidence: `src/App.tsx`)
- App shell → Duplicate review: renders (evidence: `src/App.tsx`)
- Video grid → Renderer state: reads and updates (evidence: `src/components/GridMode.tsx`)
- Focused player → Renderer state: reads and updates (evidence: `src/components/ReviewMode.tsx`)
- Search and filters → Renderer state: filters and updates (evidence: `src/components/Sidebar.tsx`)
- Settings and export → Renderer state: updates settings (evidence: `src/components/SettingsModal.tsx`)
- Duplicate review → Renderer state: reads duplicate state (evidence: `src/components/DuplicateGroupsView.tsx`)
- App shell → Electron main process: invokes desktop APIs
- App commands → Electron main process: dispatches commands (evidence: `src/appCommands.ts`)
- Electron main process → Folder scanner: scans directories (evidence: `electron/main.js`)
- Folder scanner → Video folders: reads video files (evidence: `README.md`)
- Electron main process → Thumbnail and metadata processor: processes videos (evidence: `electron/main.js`)
- Thumbnail and metadata processor → Video folders: samples video frames (evidence: `README.md`)
- Electron main process → SQLite cache: reads and writes state (evidence: `electron/main.js`)
- Electron main process → Cache migration: runs migration (evidence: `electron/main.js`)
- SQLite cache → Video folders: persists review and media data (evidence: `README.md`)
- Electron main process → Duplicate detection: runs duplicate detection (evidence: `electron/main.js`)
- Duplicate detection → Visual comparison worker: delegates visual comparison (evidence: `electron/visual-worker.js`)
- Duplicate detection → SQLite cache: uses cached video data
- Settings and export → HTML report: generates report (evidence: `README.md`)
- Electron main process → Windows Recycle Bin: moves confirmed deletes (evidence: `README.md`)
- App commands → External video player: opens video (evidence: `src/appCommands.ts`)
