# thelastgimbus/googlephotostakeouthelper architecture

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

- Interactive diagram: https://gitdiagram.com/thelastgimbus/googlephotostakeouthelper
- Repository: https://github.com/thelastgimbus/googlephotostakeouthelper

## Overview

1. **What this repository is**
   - This is a **Dart command-line application** called `gpth` (Google Photos Takeout Helper).
   - Its job is to **ingest Google Photos Takeout exports**, recover usable timestamps from photos/videos, and **reorganize them into a cleaner output folder structure**.

2. **Top-level execution boundary**
   - The CLI entrypoint is `bin/gpth.dart`.
   - Everything under `lib/` is the application logic; there is no web server, database, or long-running service.
   - The program is designed to run locally on the user’s machine and manipulate the filesystem directly.

3. **Input domain: Google Takeout folder layout**
   - The repository assumes Google Takeout’s exported structure: many nested folders, media files, and sidecar `.json` metadata files.
   - The core architectural challenge is correlating each media file with the correct metadata and deciding where it belongs in the final export.

4. **Media model and discovery**
   - `lib/media.dart` likely defines the central representation for each discovered file: photo/video identity, path, metadata, and derived properties.
   - This layer is the bridge between raw filesystem scanning and the higher-level grouping/moving logic.
   - It separates “what files exist” from “how they should be organized.”

5. **Date extraction pipeline**
   - Date handling is split across `lib/date_extractor.dart` and the `lib/date_extractors/` submodules:
     - `exif_extractor.dart` reads embedded EXIF timestamps.
     - `json_extractor.dart` reads Google Takeout sidecar metadata.
     - `guess_extractor.dart` provides fallback inference when explicit metadata is missing.
   - The architecture favors a **chain of extractors**: try the most authoritative source first, then fall back to weaker signals.

6. **Normalization and decision logic**
   - `lib/date_extractor.dart` likely orchestrates the extractors and produces a single canonical date for each item.
   - `lib/utils.dart` supports the common parsing, path, and date utilities needed across the pipeline.
   - This layer is important because it isolates timestamp interpretation from folder restructuring.

7. **Classification and grouping**
   - `lib/folder_classify.dart` and `lib/grouping.dart` appear to determine how files are bucketed for output.
   - The README indicates support for “one big folder” or division by month/date, so grouping is a major architectural axis.
   - Album handling is also part of this classification phase, based on the README’s `--albums` support.

8. **Filesystem mutation layer**
   - `lib/moving.dart` is the subsystem that actually **copies or moves files** into the destination structure.
   - This is the destructive boundary of the app: once grouping is decided, this module performs the file operations.
   - The README notes that the tool moves files by default, so this layer is central to the user-facing behavior and failure recovery strategy.

9. **Interactive vs manual operation**
   - `lib/interactive.dart` encapsulates the prompt-driven workflow introduced in v3.2.0.
   - The tool can also run in manual/flag-driven mode, which matters for automation and headless environments like Synology.
   - So the CLI has two UX modes, but they share the same underlying discovery, extraction, grouping, and moving pipeline.

10. **Extra behaviors**
   - `lib/extras.dart` suggests optional features that are not part of the core reorganize-and-move flow.
   - In this kind of repository, extras usually contain opt-in helpers or special-case behaviors that should not complicate the main pipeline.

11. **Testing boundary**
   - `test/gpth_test.dart` indicates a small but explicit test suite around the CLI behavior and/or core logic.
   - Given the filesystem-heavy nature of the app, tests are likely focused on representative parsing/grouping cases rather than exhaustive integration with real Takeout archives.

12. **Tooling and release architecture**
   - The project uses Dart tooling (`pubspec.yaml`, `analysis_options.yaml`) and appears to support reproducible local dev via `.fvm/`.
   - GitHub Actions handle test runs and release builds, and `scripts/gen-pkgbuild.bash` shows packaging support for Arch/AUR distribution.
   - That means the repo is built as a **cross-platform distributable CLI binary**, not as a library or service.

13. **External dependencies and adjacent workflow**
   - The README recommends optional use of **ExifTool** after `gpth` finishes, to backfill EXIF timestamps on output files.
   - That is not part of the internal architecture, but it is an important post-processing boundary in the overall user workflow.

14. **End-to-end data flow**
   - The main flow is: **read Takeout folders → discover media and sidecars → extract/resolve timestamps → classify/group by chosen strategy → move/copy into output directories → optionally post-process with ExifTool**.
   - If you are drawing the architecture, the key internal subsystems to show are: CLI/interactive front end, media discovery, date extraction, grouping/classification, and filesystem mover.

Main entry points: [`bin/gpth.dart`](https://github.com/thelastgimbus/googlephotostakeouthelper/blob/master/bin/gpth.dart) (gpth CLI), [`lib/date_extractor.dart`](https://github.com/thelastgimbus/googlephotostakeouthelper/blob/master/lib/date_extractor.dart) (Date resolver), [`lib/grouping.dart`](https://github.com/thelastgimbus/googlephotostakeouthelper/blob/master/lib/grouping.dart) (Grouping), [`lib/moving.dart`](https://github.com/thelastgimbus/googlephotostakeouthelper/blob/master/lib/moving.dart) (File mover)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI"]
  node_bin_gpth["gpth CLI<br/>entrypoint<br/>[gpth.dart]"]
  node_interactive["Interactive mode<br/>ui<br/>[interactive.dart]"]
end

subgraph group_core["Core pipeline"]
  node_media["Media model<br/>domain<br/>[media.dart]"]
  node_date_extractor["Date resolver<br/>orchestrator"]
  node_exif_extractor["EXIF reader<br/>extractor"]
  node_json_extractor["Takeout JSON<br/>extractor"]
  node_guess_extractor["Fallback guess<br/>extractor"]
  node_folder_classify["Folder classify<br/>classifier"]
  node_grouping["Grouping<br/>aggregator<br/>[grouping.dart]"]
  node_moving["File mover<br/>filesystem<br/>[moving.dart]"]
  node_utils["Utilities<br/>helpers<br/>[utils.dart]"]
  node_extras["Extras<br/>extensions<br/>[extras.dart]"]
end

subgraph group_tooling["Tooling"]
  node_pubspec["Dart package<br/>build config<br/>[pubspec.yaml]"]
  node_analysis_options["Analyzer rules<br/>build config"]
  node_fvm_config["FVM config<br/>dev env<br/>[fvm_config.json]"]
  node_workflow_test["Test CI<br/>[dart-test.yaml]"]
  node_workflow_build["Nightly build<br/>ci<br/>[build-nightly.yml]"]
  node_workflow_release["Release CI<br/>[new-release.yml]"]
  node_pkgbuild["PKGBUILD script<br/>packaging<br/>[gen-pkgbuild.bash]"]
  node_changelog["Changelog script<br/>release<br/>[get_changelog.py]"]
end

subgraph group_tests["Tests"]
  node_test_main["CLI tests<br/>[gpth_test.dart]"]
end

node_bin_gpth -->|"launches"| node_interactive
node_bin_gpth -->|"discovers"| node_media
node_bin_gpth -->|"resolves dates"| node_date_extractor
node_bin_gpth -->|"routes"| node_folder_classify
node_bin_gpth -->|"executes"| node_moving
node_media -->|"metadata"| node_date_extractor
node_date_extractor -->|"tries"| node_exif_extractor
node_date_extractor -->|"tries"| node_json_extractor
node_date_extractor -->|"falls back"| node_guess_extractor
node_date_extractor -->|"uses"| node_utils
node_folder_classify -->|"buckets"| node_grouping
node_grouping -->|"plans"| node_moving
node_grouping -->|"augments"| node_extras
node_moving -->|"uses"| node_utils
node_interactive -->|"configures"| node_grouping
node_interactive -->|"confirms"| node_moving
node_pubspec -->|"packages"| node_bin_gpth
node_analysis_options -->|"checks"| node_test_main
node_fvm_config -->|"pins"| node_pubspec
node_workflow_test -->|"runs"| node_test_main
node_workflow_build -->|"builds"| node_pubspec
node_workflow_release -->|"packages"| node_pkgbuild
node_workflow_release -->|"publishes"| node_changelog
node_pkgbuild -->|"reads"| node_pubspec

click node_bin_gpth "https://github.com/thelastgimbus/googlephotostakeouthelper/blob/master/bin/gpth.dart"
click node_interactive "https://github.com/thelastgimbus/googlephotostakeouthelper/blob/master/lib/interactive.dart"
click node_media "https://github.com/thelastgimbus/googlephotostakeouthelper/blob/master/lib/media.dart"
click node_date_extractor "https://github.com/thelastgimbus/googlephotostakeouthelper/blob/master/lib/date_extractor.dart"
click node_exif_extractor "https://github.com/thelastgimbus/googlephotostakeouthelper/blob/master/lib/date_extractors/exif_extractor.dart"
click node_json_extractor "https://github.com/thelastgimbus/googlephotostakeouthelper/blob/master/lib/date_extractors/json_extractor.dart"
click node_guess_extractor "https://github.com/thelastgimbus/googlephotostakeouthelper/blob/master/lib/date_extractors/guess_extractor.dart"
click node_folder_classify "https://github.com/thelastgimbus/googlephotostakeouthelper/blob/master/lib/folder_classify.dart"
click node_grouping "https://github.com/thelastgimbus/googlephotostakeouthelper/blob/master/lib/grouping.dart"
click node_moving "https://github.com/thelastgimbus/googlephotostakeouthelper/blob/master/lib/moving.dart"
click node_utils "https://github.com/thelastgimbus/googlephotostakeouthelper/blob/master/lib/utils.dart"
click node_extras "https://github.com/thelastgimbus/googlephotostakeouthelper/blob/master/lib/extras.dart"
click node_pubspec "https://github.com/thelastgimbus/googlephotostakeouthelper/blob/master/pubspec.yaml"
click node_analysis_options "https://github.com/thelastgimbus/googlephotostakeouthelper/blob/master/analysis_options.yaml"
click node_fvm_config "https://github.com/thelastgimbus/googlephotostakeouthelper/blob/master/.fvm/fvm_config.json"
click node_workflow_test "https://github.com/thelastgimbus/googlephotostakeouthelper/blob/master/.github/workflows/dart-test.yaml"
click node_workflow_build "https://github.com/thelastgimbus/googlephotostakeouthelper/blob/master/.github/workflows/build-nightly.yml"
click node_workflow_release "https://github.com/thelastgimbus/googlephotostakeouthelper/blob/master/.github/workflows/new-release.yml"
click node_pkgbuild "https://github.com/thelastgimbus/googlephotostakeouthelper/blob/master/scripts/gen-pkgbuild.bash"
click node_changelog "https://github.com/thelastgimbus/googlephotostakeouthelper/blob/master/scripts/get_changelog.py"
click node_test_main "https://github.com/thelastgimbus/googlephotostakeouthelper/blob/master/test/gpth_test.dart"

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_bin_gpth,node_interactive toneBlue
class node_media,node_date_extractor,node_exif_extractor,node_json_extractor,node_guess_extractor,node_folder_classify,node_grouping,node_moving,node_utils,node_extras toneAmber
class node_pubspec,node_analysis_options,node_fvm_config,node_workflow_test,node_workflow_build,node_workflow_release,node_pkgbuild,node_changelog toneMint
class node_test_main toneRose
```

## Components

### CLI

Command-line entrypoint and user interaction

- [gpth CLI](https://github.com/thelastgimbus/googlephotostakeouthelper/blob/master/bin/gpth.dart): entrypoint · Main command-line entrypoint. · `bin/gpth.dart`
- [Interactive mode](https://github.com/thelastgimbus/googlephotostakeouthelper/blob/master/lib/interactive.dart): ui · Prompt-driven workflow for manual runs. · `lib/interactive.dart`

### Core pipeline

Discovery, timestamp resolution, grouping, and file relocation

- [Media model](https://github.com/thelastgimbus/googlephotostakeouthelper/blob/master/lib/media.dart): domain · Represents discovered photos/videos and their derived properties. · `lib/media.dart`
- [Date resolver](https://github.com/thelastgimbus/googlephotostakeouthelper/blob/master/lib/date_extractor.dart): orchestrator · Coordinates timestamp extraction and normalization. · `lib/date_extractor.dart`
- [EXIF reader](https://github.com/thelastgimbus/googlephotostakeouthelper/blob/master/lib/date_extractors/exif_extractor.dart): extractor · Reads embedded media timestamps. · `lib/date_extractors/exif_extractor.dart`
- [Takeout JSON](https://github.com/thelastgimbus/googlephotostakeouthelper/blob/master/lib/date_extractors/json_extractor.dart): extractor · Reads Google Takeout sidecar metadata. · `lib/date_extractors/json_extractor.dart`
- [Fallback guess](https://github.com/thelastgimbus/googlephotostakeouthelper/blob/master/lib/date_extractors/guess_extractor.dart): extractor · Infers a usable date when explicit metadata is missing. · `lib/date_extractors/guess_extractor.dart`
- [Folder classify](https://github.com/thelastgimbus/googlephotostakeouthelper/blob/master/lib/folder_classify.dart): classifier · Decides output bucket structure from dates and options. · `lib/folder_classify.dart`
- [Grouping](https://github.com/thelastgimbus/googlephotostakeouthelper/blob/master/lib/grouping.dart): aggregator · Builds groups such as by month, date, or album. · `lib/grouping.dart`
- [File mover](https://github.com/thelastgimbus/googlephotostakeouthelper/blob/master/lib/moving.dart): filesystem · Copies or moves files into the destination layout. · `lib/moving.dart`
- [Utilities](https://github.com/thelastgimbus/googlephotostakeouthelper/blob/master/lib/utils.dart): helpers · Shared parsing, path, and date utilities. · `lib/utils.dart`
- [Extras](https://github.com/thelastgimbus/googlephotostakeouthelper/blob/master/lib/extras.dart): extensions · Optional behaviors outside the main reorganize flow. · `lib/extras.dart`

### Tooling

Packaging, CI, and release automation

- [Dart package](https://github.com/thelastgimbus/googlephotostakeouthelper/blob/master/pubspec.yaml): build config · Package metadata and dependencies for the CLI app. · `pubspec.yaml`
- [Analyzer rules](https://github.com/thelastgimbus/googlephotostakeouthelper/blob/master/analysis_options.yaml): build config · Static analysis configuration. · `analysis_options.yaml`
- [FVM config](https://github.com/thelastgimbus/googlephotostakeouthelper/blob/master/.fvm/fvm_config.json): dev env · Pinned Flutter/Dart version management config. · `.fvm/fvm_config.json`
- [Test CI](https://github.com/thelastgimbus/googlephotostakeouthelper/blob/master/.github/workflows/dart-test.yaml): ci · GitHub Actions test workflow. · `.github/workflows/dart-test.yaml`
- [Nightly build](https://github.com/thelastgimbus/googlephotostakeouthelper/blob/master/.github/workflows/build-nightly.yml): ci · CI workflow for scheduled or nightly builds. · `.github/workflows/build-nightly.yml`
- [Release CI](https://github.com/thelastgimbus/googlephotostakeouthelper/blob/master/.github/workflows/new-release.yml): ci · GitHub Actions release workflow. · `.github/workflows/new-release.yml`
- [PKGBUILD script](https://github.com/thelastgimbus/googlephotostakeouthelper/blob/master/scripts/gen-pkgbuild.bash): packaging · Generates Arch/AUR packaging metadata. · `scripts/gen-pkgbuild.bash`
- [Changelog script](https://github.com/thelastgimbus/googlephotostakeouthelper/blob/master/scripts/get_changelog.py): release · Generates or updates release notes content. · `scripts/get_changelog.py`

### Tests

Repository test coverage

- [CLI tests](https://github.com/thelastgimbus/googlephotostakeouthelper/blob/master/test/gpth_test.dart): test · Repository test suite for CLI and core behavior. · `test/gpth_test.dart`

## Connections

- gpth CLI → Interactive mode: launches · CLI can enter prompt-driven workflow.
- gpth CLI → Media model: discovers · Entry point starts filesystem scanning and media discovery.
- gpth CLI → Date resolver: resolves dates · Entry point feeds discovered media into timestamp resolution.
- gpth CLI → Folder classify: routes · CLI hands resolved items to classification.
- gpth CLI → File mover: executes · CLI triggers the final filesystem mutation step.
- Media model → Date resolver: metadata · Media items carry paths and source details into date resolution.
- Date resolver → EXIF reader: tries · Authoritative embedded timestamps are checked first.
- Date resolver → Takeout JSON: tries · Sidecar Takeout metadata is consulted next.
- Date resolver → Fallback guess: falls back · Heuristic inference is used when explicit sources are missing.
- Date resolver → Utilities: uses · Shared parsing and normalization helpers support extraction.
- Folder classify → Grouping: buckets · Classification feeds the grouping strategy.
- Grouping → File mover: plans · Grouped output is handed to the mover for execution.
- Grouping → Extras: augments · Optional behaviors can affect grouping and output decisions.
- File mover → Utilities: uses · File operations rely on shared path/date helpers.
- Interactive mode → Grouping: configures · Interactive prompts select grouping and output mode.
- Interactive mode → File mover: confirms · Interactive flow reaches the same filesystem mutation boundary.
- Dart package → gpth CLI: packages · Package configuration builds the CLI entrypoint.
- Analyzer rules → CLI tests: checks · Analyzer settings shape development and test quality.
- FVM config → Dart package: pins · Version management stabilizes the Dart toolchain.
- Test CI → CLI tests: runs · CI validates the test suite.
- Nightly build → Dart package: builds · Nightly workflow produces distributable artifacts.
- Release CI → PKGBUILD script: packages · Release automation includes packaging steps.
- Release CI → Changelog script: publishes · Release workflow gathers changelog content.
- PKGBUILD script → Dart package: reads · Packaging script derives metadata from the package manifest.
