# oivindmi/photo_time_aligner architecture

> Architecture diagram of the GitHub repository oivindmi/photo_time_aligner, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/oivindmi/photo_time_aligner
- Repository: https://github.com/oivindmi/photo_time_aligner

## Overview

##### Project type and purpose
- This is a desktop, full-stack Python application (Windows GUI) whose goal is to batch-align timestamps on photos and videos from multiple cameras. It wraps calls to ExifTool and exposes a drag-and-drop UI.

##### File structure
- Top-level:
- main.py               — application entry point
- requirements.txt      — Python dependencies
- README.md, VIDEO_SUPPORT.md
- src/core/              — pure business logic
- config_manager.py    — load/save settings
- exif_handler.py      — shell out to ExifTool and parse metadata
- file_processor.py    — orchestrates per-file adjustments
- filename_pattern.py  — build output filenames
- supported_formats.py — white-list of media extensions
- time_calculator.py   — compute time offsets
- src/ui/                — GUI and threading
- main_window.py       — drag-and-drop interface, buttons, progress
- file_scanner_thread.py — background file scanning
- src/utils/             — cross-cutting utilities
- exceptions.py        — custom exception types
- tests/                 — unit and integration tests

##### README for additional insights
- Describes features (batch adjustment, master folder option)
- Uses ExifTool as an external dependency
- No external database—everything works on the local file system

a. UI Layer
- Main Window (single-threaded GUI)
- File Scanner Thread (spawns on file drops)
b. Core Layer
- File Processor (central orchestrator)
- Exif Handler (calls ExifTool CLI)
- Time Calculator (computes deltas)
- Filename Pattern Engine (generates new names)
- Config Manager (loads/saves user prefs)
- Supported Formats (validation)
c. Utils Layer
- Exception Handler
d. External Services & Data Stores
- ExifTool executable (external process)
- Local File System (read/write media files and folder structure)

##### Relationships and data flow
1. User drags files → Main Window
2. Main Window signals File Scanner Thread → produces list of file paths
3. File Scanner passes paths to File Processor
4. File Processor references Supported Formats → filters media
5. For each file:
- Exif Handler launches ExifTool → retrieves timestamp metadata
- Time Calculator computes adjustment relative to “master”
- File Processor writes changes (via ExifTool) or renames using Filename Pattern
6. Config Manager persists user settings (offsets, output folder)
7. UI updates progress/completion statuses

##### Architectural patterns and design principles
- Layered architecture separating UI, business logic, and utilities
- Single responsibility per module (e.g., time calc vs. filename building)
- Use of background thread to prevent UI blocking
- Externalizing metadata I/O to a trusted CLI (ExifTool)

##### Be detailed
- Critical data transformations (timestamp read → delta calc → write)
- Optional features (master folder organization) as side components
- Don’t omit small but important modules (supported_formats, exceptions)

## Diagram (Mermaid)

```mermaid
flowchart TB
  subgraph "UI Layer"
    direction TB
    ENTRY["Launcher (main.py)"]:::ui
    MW["Main Window"]:::ui
    FST["File Scanner Thread"]:::ui
  end

  subgraph "Core Layer"
    direction TB
    FP["File Processor"]:::core
    SF["Supported Formats"]:::core
    EH["Exif Handler"]:::core
    TC["Time Calculator"]:::core
    FPAT["Filename Pattern Engine"]:::core
    CM["Config Manager"]:::core
  end

  subgraph "Utils Layer"
    direction TB
    EXC["Exception Handler"]:::utils
  end

  subgraph "External/Infrastructure"
    direction TB
    ExifTool["ExifTool Executable"]:::infra
    FS["Local File System"]:::infra
  end

  ENTRY -->|"start UI"| MW
  MW -->|"drop files"| FST
  FST -->|"file list"| FP
  FP -->|"validate"| SF
  FP -->|"process each file"| EH
  EH -->|"raw metadata"| TC
  TC -->|"timestamp delta"| FP
  FP -->|"generate name"| FPAT
  FP -->|"persist settings"| CM
  CM -->|"save/load"| FS
  FP -->|"read/write media"| FS
  EH -->|"invoke CLI"| ExifTool
  ExifTool -->|"parsed data"| EH
  MW -->|"show errors"| EXC
  FP -->|"throw errors"| EXC

  click ENTRY "https://github.com/oivindmi/photo_time_aligner/blob/master/main.py"
  click MW "https://github.com/oivindmi/photo_time_aligner/blob/master/src/ui/main_window.py"
  click FST "https://github.com/oivindmi/photo_time_aligner/blob/master/src/ui/file_scanner_thread.py"
  click FP "https://github.com/oivindmi/photo_time_aligner/blob/master/src/core/file_processor.py"
  click EH "https://github.com/oivindmi/photo_time_aligner/blob/master/src/core/exif_handler.py"
  click TC "https://github.com/oivindmi/photo_time_aligner/blob/master/src/core/time_calculator.py"
  click FPAT "https://github.com/oivindmi/photo_time_aligner/blob/master/src/core/filename_pattern.py"
  click CM "https://github.com/oivindmi/photo_time_aligner/blob/master/src/core/config_manager.py"
  click SF "https://github.com/oivindmi/photo_time_aligner/blob/master/src/core/supported_formats.py"
  click EXC "https://github.com/oivindmi/photo_time_aligner/blob/master/src/utils/exceptions.py"

  classDef ui fill:#cce5ff,stroke:#333,stroke-width:1px
  classDef core fill:#d4edda,stroke:#333,stroke-width:1px
  classDef utils fill:#e2e3e5,stroke:#333,stroke-width:1px
  classDef infra fill:#fff3cd,stroke:#333,stroke-width:1px
```
