# rvcgeeks/filenamecluster architecture

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

- Interactive diagram: https://gitdiagram.com/rvcgeeks/filenamecluster
- Repository: https://github.com/rvcgeeks/filenamecluster

## Overview

File Name Cluster is a desktop app for turning timestamped files into event folders. The user chooses storage and optional input folders, previews events, adjusts options, then applies clustering or flattens folders; the app scans names and supported metadata, learns event boundaries, and plans file moves. The graph includes the documented timeline/calendar and clash-handling capabilities. Some links reflect README-described behavior because those implementations were not sampled; edges without direct source evidence are omitted.

Main entry points: [`filenamecluster/src/filenamecluster/core/operations/pipeline.py`](https://github.com/rvcgeeks/filenamecluster/blob/main/filenamecluster/src/filenamecluster/core/operations/pipeline.py) (Clustering pipeline), [`filenamecluster/src/filenamecluster/core/exif/read.py`](https://github.com/rvcgeeks/filenamecluster/blob/main/filenamecluster/src/filenamecluster/core/exif/read.py) (Container capture-time readers), [`filenamecluster/src/filenamecluster/__main__.py`](https://github.com/rvcgeeks/filenamecluster/blob/main/filenamecluster/src/filenamecluster/__main__.py) (Application startup), [`filenamecluster/src/filenamecluster/ui/controller/previewing.py`](https://github.com/rvcgeeks/filenamecluster/blob/main/filenamecluster/src/filenamecluster/ui/controller/previewing.py) (Preview coordination)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["Desktop interface"]
  node_launch["Application startup<br/>[__main__.py]"]
  node_ui["Window and views<br/>[view.py]"]
  node_controller["Action controller<br/>[controller.py]"]
  node_session["Session model<br/>[model.py]"]
  node_display["Preview presentation<br/>[display.py]"]
  node_preview_control["Preview coordination<br/>[previewing.py]"]
end

subgraph group_ingest["Timestamp extraction"]
  node_scan["Folder scan and timestamp parse<br/>[scan.py]"]
  node_patterns["Filename timestamp rules<br/>[patterns.py]"]
  node_metadata["Container capture-time readers<br/>[read.py]"]
  node_image_reader["Image metadata<br/>[image.py]"]
  node_tiff_reader["TIFF metadata<br/>[tiff.py]"]
  node_video_reader["Video metadata<br/>[video.py]"]
  node_pdf_reader["PDF dates<br/>[pdf.py]"]
end

subgraph group_events["Event clustering"]
  node_pipeline["Clustering pipeline<br/>[pipeline.py]"]
  node_cluster["Event grouping<br/>[cluster.py]"]
  node_fit["Gap-pattern fitting<br/>[fit.py]"]
  node_split["Boundary decision<br/>[split.py]"]
end

subgraph group_organizing["Folder organization"]
  node_preview["Preview and move planning<br/>[preview.py]"]
  node_model_file[("Saved options and learned model<br/>[model.py]")]
  node_organize["Apply and flatten operations<br/>[organize.py]"]
  node_placement["File placement<br/>[placement.py]"]
end

node_user(("User"))

node_user -->|"starts app"| node_launch
node_launch -->|"builds window"| node_ui
node_launch -->|"composes"| node_controller
node_launch -->|"composes"| node_session
node_controller -->|"delegates preview"| node_preview_control
node_preview_control -->|"runs scan"| node_pipeline
node_preview_control -->|"updates state"| node_session
node_ui -->|"sends actions"| node_controller
node_session -->|"projects preview"| node_display
node_pipeline -->|"scans files"| node_scan
node_scan -->|"parses names"| node_patterns
node_pipeline -->|"reads capture time"| node_metadata
node_metadata -->|"dispatches images"| node_image_reader
node_metadata -->|"dispatches TIFF"| node_tiff_reader
node_metadata -->|"dispatches video"| node_video_reader
node_metadata -->|"dispatches PDFs"| node_pdf_reader
node_pipeline -->|"groups timestamps"| node_cluster
node_cluster -->|"fits gaps"| node_fit
node_fit -->|"uses boundary"| node_split
node_pipeline -->|"loads and saves"| node_model_file
node_preview_control -->|"prepares preview"| node_preview
node_preview -->|"calculates events"| node_pipeline
node_preview -->|"reads options"| node_model_file
node_controller -.->|"applies or flattens"| node_organize
node_organize -.->|"moves files"| node_placement

click node_launch "https://github.com/rvcgeeks/filenamecluster/blob/main/filenamecluster/src/filenamecluster/__main__.py"
click node_ui "https://github.com/rvcgeeks/filenamecluster/blob/main/filenamecluster/src/filenamecluster/ui/view/view.py"
click node_controller "https://github.com/rvcgeeks/filenamecluster/blob/main/filenamecluster/src/filenamecluster/ui/controller/controller.py"
click node_session "https://github.com/rvcgeeks/filenamecluster/blob/main/filenamecluster/src/filenamecluster/ui/model/model.py"
click node_display "https://github.com/rvcgeeks/filenamecluster/blob/main/filenamecluster/src/filenamecluster/ui/model/display.py"
click node_preview_control "https://github.com/rvcgeeks/filenamecluster/blob/main/filenamecluster/src/filenamecluster/ui/controller/previewing.py"
click node_scan "https://github.com/rvcgeeks/filenamecluster/blob/main/filenamecluster/src/filenamecluster/core/parser/scan.py"
click node_patterns "https://github.com/rvcgeeks/filenamecluster/blob/main/filenamecluster/src/filenamecluster/core/parser/patterns.py"
click node_metadata "https://github.com/rvcgeeks/filenamecluster/blob/main/filenamecluster/src/filenamecluster/core/exif/read.py"
click node_image_reader "https://github.com/rvcgeeks/filenamecluster/blob/main/filenamecluster/src/filenamecluster/core/exif/image.py"
click node_tiff_reader "https://github.com/rvcgeeks/filenamecluster/blob/main/filenamecluster/src/filenamecluster/core/exif/tiff.py"
click node_video_reader "https://github.com/rvcgeeks/filenamecluster/blob/main/filenamecluster/src/filenamecluster/core/exif/video.py"
click node_pdf_reader "https://github.com/rvcgeeks/filenamecluster/blob/main/filenamecluster/src/filenamecluster/core/exif/pdf.py"
click node_pipeline "https://github.com/rvcgeeks/filenamecluster/blob/main/filenamecluster/src/filenamecluster/core/operations/pipeline.py"
click node_cluster "https://github.com/rvcgeeks/filenamecluster/blob/main/filenamecluster/src/filenamecluster/core/algorithm/cluster.py"
click node_fit "https://github.com/rvcgeeks/filenamecluster/blob/main/filenamecluster/src/filenamecluster/core/algorithm/fit.py"
click node_split "https://github.com/rvcgeeks/filenamecluster/blob/main/filenamecluster/src/filenamecluster/core/algorithm/split.py"
click node_preview "https://github.com/rvcgeeks/filenamecluster/blob/main/filenamecluster/src/filenamecluster/core/operations/preview.py"
click node_model_file "https://github.com/rvcgeeks/filenamecluster/blob/main/filenamecluster/src/filenamecluster/core/operations/model.py"
click node_organize "https://github.com/rvcgeeks/filenamecluster/blob/main/filenamecluster/src/filenamecluster/core/operations/organize.py"
click node_placement "https://github.com/rvcgeeks/filenamecluster/blob/main/filenamecluster/src/filenamecluster/core/operations/placement.py"

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_launch,node_ui,node_controller,node_session,node_display,node_preview_control,node_user toneBlue
class node_scan,node_patterns,node_metadata,node_image_reader,node_tiff_reader,node_video_reader,node_pdf_reader toneAmber
class node_pipeline,node_cluster,node_fit,node_split toneMint
class node_preview,node_model_file,node_organize,node_placement toneRose
```

## Components

### Desktop interface

- [Application startup](https://github.com/rvcgeeks/filenamecluster/blob/main/filenamecluster/src/filenamecluster/__main__.py): `filenamecluster/src/filenamecluster/__main__.py`
- [Window and views](https://github.com/rvcgeeks/filenamecluster/blob/main/filenamecluster/src/filenamecluster/ui/view/view.py): `filenamecluster/src/filenamecluster/ui/view/view.py`
- [Action controller](https://github.com/rvcgeeks/filenamecluster/blob/main/filenamecluster/src/filenamecluster/ui/controller/controller.py): `filenamecluster/src/filenamecluster/ui/controller/controller.py`
- [Session model](https://github.com/rvcgeeks/filenamecluster/blob/main/filenamecluster/src/filenamecluster/ui/model/model.py): `filenamecluster/src/filenamecluster/ui/model/model.py`
- [Preview presentation](https://github.com/rvcgeeks/filenamecluster/blob/main/filenamecluster/src/filenamecluster/ui/model/display.py): `filenamecluster/src/filenamecluster/ui/model/display.py`
- [Preview coordination](https://github.com/rvcgeeks/filenamecluster/blob/main/filenamecluster/src/filenamecluster/ui/controller/previewing.py): `filenamecluster/src/filenamecluster/ui/controller/previewing.py`

### Timestamp extraction

- [Folder scan and timestamp parse](https://github.com/rvcgeeks/filenamecluster/blob/main/filenamecluster/src/filenamecluster/core/parser/scan.py): `filenamecluster/src/filenamecluster/core/parser/scan.py`
- [Filename timestamp rules](https://github.com/rvcgeeks/filenamecluster/blob/main/filenamecluster/src/filenamecluster/core/parser/patterns.py): `filenamecluster/src/filenamecluster/core/parser/patterns.py`
- [Container capture-time readers](https://github.com/rvcgeeks/filenamecluster/blob/main/filenamecluster/src/filenamecluster/core/exif/read.py): `filenamecluster/src/filenamecluster/core/exif/read.py`
- [Image metadata](https://github.com/rvcgeeks/filenamecluster/blob/main/filenamecluster/src/filenamecluster/core/exif/image.py): `filenamecluster/src/filenamecluster/core/exif/image.py`
- [TIFF metadata](https://github.com/rvcgeeks/filenamecluster/blob/main/filenamecluster/src/filenamecluster/core/exif/tiff.py): `filenamecluster/src/filenamecluster/core/exif/tiff.py`
- [Video metadata](https://github.com/rvcgeeks/filenamecluster/blob/main/filenamecluster/src/filenamecluster/core/exif/video.py): `filenamecluster/src/filenamecluster/core/exif/video.py`
- [PDF dates](https://github.com/rvcgeeks/filenamecluster/blob/main/filenamecluster/src/filenamecluster/core/exif/pdf.py): `filenamecluster/src/filenamecluster/core/exif/pdf.py`

### Event clustering

- [Clustering pipeline](https://github.com/rvcgeeks/filenamecluster/blob/main/filenamecluster/src/filenamecluster/core/operations/pipeline.py): `filenamecluster/src/filenamecluster/core/operations/pipeline.py`
- [Event grouping](https://github.com/rvcgeeks/filenamecluster/blob/main/filenamecluster/src/filenamecluster/core/algorithm/cluster.py): `filenamecluster/src/filenamecluster/core/algorithm/cluster.py`
- [Gap-pattern fitting](https://github.com/rvcgeeks/filenamecluster/blob/main/filenamecluster/src/filenamecluster/core/algorithm/fit.py): `filenamecluster/src/filenamecluster/core/algorithm/fit.py`
- [Boundary decision](https://github.com/rvcgeeks/filenamecluster/blob/main/filenamecluster/src/filenamecluster/core/algorithm/split.py): `filenamecluster/src/filenamecluster/core/algorithm/split.py`

### Folder organization

- [Preview and move planning](https://github.com/rvcgeeks/filenamecluster/blob/main/filenamecluster/src/filenamecluster/core/operations/preview.py): `filenamecluster/src/filenamecluster/core/operations/preview.py`
- [Saved options and learned model](https://github.com/rvcgeeks/filenamecluster/blob/main/filenamecluster/src/filenamecluster/core/operations/model.py): `filenamecluster/src/filenamecluster/core/operations/model.py`
- [Apply and flatten operations](https://github.com/rvcgeeks/filenamecluster/blob/main/filenamecluster/src/filenamecluster/core/operations/organize.py): `filenamecluster/src/filenamecluster/core/operations/organize.py`
- [File placement](https://github.com/rvcgeeks/filenamecluster/blob/main/filenamecluster/src/filenamecluster/core/operations/placement.py): `filenamecluster/src/filenamecluster/core/operations/placement.py`

### Other components

- **User**

## Connections

- User → Application startup: starts app (evidence: `README.md`)
- Application startup → Window and views: builds window
- Application startup → Action controller: composes
- Application startup → Session model: composes
- Action controller → Preview coordination: delegates preview (evidence: `filenamecluster/src/filenamecluster/ui/controller/controller.py`)
- Preview coordination → Clustering pipeline: runs scan (evidence: `filenamecluster/src/filenamecluster/ui/controller/previewing.py`)
- Preview coordination → Session model: updates state (evidence: `filenamecluster/src/filenamecluster/ui/controller/previewing.py`)
- Window and views → Action controller: sends actions
- Session model → Preview presentation: projects preview (evidence: `filenamecluster/src/filenamecluster/ui/model/model.py`)
- Clustering pipeline → Folder scan and timestamp parse: scans files (evidence: `filenamecluster/src/filenamecluster/core/operations/pipeline.py`)
- Folder scan and timestamp parse → Filename timestamp rules: parses names (evidence: `filenamecluster/src/filenamecluster/core/parser/scan.py`)
- Clustering pipeline → Container capture-time readers: reads capture time (evidence: `filenamecluster/src/filenamecluster/core/operations/pipeline.py`)
- Container capture-time readers → Image metadata: dispatches images (evidence: `filenamecluster/src/filenamecluster/core/exif/read.py`)
- Container capture-time readers → TIFF metadata: dispatches TIFF (evidence: `filenamecluster/src/filenamecluster/core/exif/read.py`)
- Container capture-time readers → Video metadata: dispatches video (evidence: `filenamecluster/src/filenamecluster/core/exif/read.py`)
- Container capture-time readers → PDF dates: dispatches PDFs (evidence: `filenamecluster/src/filenamecluster/core/exif/read.py`)
- Clustering pipeline → Event grouping: groups timestamps (evidence: `filenamecluster/src/filenamecluster/core/operations/pipeline.py`)
- Event grouping → Gap-pattern fitting: fits gaps (evidence: `filenamecluster/src/filenamecluster/core/algorithm/cluster.py`)
- Gap-pattern fitting → Boundary decision: uses boundary (evidence: `filenamecluster/src/filenamecluster/core/algorithm/fit.py`)
- Clustering pipeline → Saved options and learned model: loads and saves (evidence: `filenamecluster/src/filenamecluster/core/operations/pipeline.py`)
- Preview coordination → Preview and move planning: prepares preview (evidence: `filenamecluster/src/filenamecluster/core/operations/preview.py`)
- Preview and move planning → Clustering pipeline: calculates events (evidence: `filenamecluster/src/filenamecluster/core/operations/preview.py`)
- Preview and move planning → Saved options and learned model: reads options (evidence: `filenamecluster/src/filenamecluster/core/operations/preview.py`)
- Action controller → Apply and flatten operations: applies or flattens (evidence: `README.md`)
- Apply and flatten operations → File placement: moves files (evidence: `README.md`)
