# tangilab/lightroom-path-migrator architecture

> Architecture diagram of the GitHub repository tangilab/lightroom-path-migrator, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-08). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tangilab/lightroom-path-migrator
- Repository: https://github.com/tangilab/lightroom-path-migrator

## Overview

##### Project Type and Purpose
- This is a lightweight CLI-driven Python utility (“Lightroom Recover”) composed of two primary scripts:
- scan_photos.py – walks a configured directory of image files, reads metadata (path, filename, width, height), and writes out JSON/CSV/SQLite snapshots.
- update_lightroom_paths.py – reads that snapshot plus an existing Lightroom catalog, matches records, and updates the catalog’s root paths (dry-run or real).
- It is not a web app or microservice, but a command-line tool focused on offline file scanning and catalog mutation.

##### File‐Structure Analysis
Top‐level artifacts:
- .env.example / .env – environment variables for directory paths, filenames, and dry-run flag
- pyproject.toml / requirements.txt – build/typing/test configurations and Python dependencies
- scan_photos.py / update_lightroom_paths.py – two main modules, each tested in tests/
- resultats_scan/ – output directory for scan snapshots (JSON, CSV, SQLite)
- catalogue_lightroom/ – target Lightroom catalog files (not versioned)
- tests/ – pytest suite covering both scripts

No frontend or long-running service; it’s purely an offline batch‐processing tool.

##### Key Insights from README
- Uses environment variables for configuration (dotenv)
- Produces three output formats to suit different consumers (human-readable JSON/CSV, and SQLite DB for queries)
- Supports dry-run vs real update modes
- High test coverage, strict typing (mypy) and docstring standards (pydocstyle)

##### Main Components
a. Configuration Layer
- .env file (DRY_RUN_MODE, PHOTOS_DIRECTORY, SCAN_DB_FILENAME, CATALOG_FILENAME)
b. Scan Module
- Python process “scan_photos.py”
- Input: PHOTOS_DIRECTORY
- Output: resultats_scan/{.json, .csv, .db}
c. Storage Formats (Results)
- JSON snapshot
- CSV snapshot
- SQLite database
d. Update Module
- Python process “update_lightroom_paths.py”
- Inputs: scan DB (SQLite), Lightroom catalog files (from catalogue_lightroom/)
- Logic: match file records → update root paths in catalog
- Controlled by DRY_RUN_MODE flag
e. External Artifact
- Lightroom Catalog (file-based database)

##### Relationships & Data Flows
1. User invokes scan_photos.py
– Reads .env → scans PHOTOS_DIRECTORY → writes out three formats into resultats_scan/
2. User invokes update_lightroom_paths.py
– Reads .env → loads scan DB (SQLite) and reads Lightroom catalog
– Matches records → writes updates back to catalog (or simulates if dry‐run)

##### Architectural Patterns & Principles
- Separation of Concerns: scanning vs updating are totally separate processes
- Configuration‐driven: everything derived from .env
- Multiple persistence formats for flexibility (human vs machine query)
- Emphasis on safety: dry-run mode, backups, clear disclaimers

##### Relevant Technologies
- Python 3.x
- SQLite (via sqlite3 or an ORM)
- JSON & CSV stdlib
- python-dotenv for config
- pytest, mypy, pydocstyle for quality gates

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Configuration Layer"
        ENV[".env (DRY_RUN_MODE, PHOTOS_DIRECTORY, SCAN_DB_FILENAME, CATALOG_FILENAME)"]:::config
        TOML["pyproject.toml"]:::config
        REQ["requirements.txt"]:::config
        README["README.md"]:::doc
        LICENSE["LICENSE"]:::doc
        GITIGNORE[".gitignore"]:::doc
    end

    subgraph "Python Scripts"
        SCAN["scan_photos.py"]:::process
        UPDATE["update_lightroom_paths.py"]:::process
    end

    subgraph "Local File System"
        PHOTOS["PHOTOS_DIRECTORY"]:::storage
        RESULTATS["resultats_scan/"]:::storage
        CATALOGDIR["catalogue_lightroom/"]:::storage
        CATALOG["Lightroom Catalog"]:::external
    end

    subgraph "Output Artifacts"
        JSON["JSON Snapshot"]:::storage
        CSV["CSV Snapshot"]:::storage
        DB["SQLite DB"]:::storage
    end

    subgraph "Test Suite"
        T1["tests/test_scan_photos.py"]:::test
        T2["tests/test_update_lightroom_paths.py"]:::test
    end

    ENV -->|reads config| SCAN
    TOML -->|build config| SCAN
    REQ -->|install deps| SCAN
    PHOTOS -->|image files| SCAN
    SCAN -->|writes| JSON
    SCAN -->|writes| CSV
    SCAN -->|writes| DB
    JSON -->|stored in| RESULTATS
    CSV -->|stored in| RESULTATS
    DB -->|stored in| RESULTATS

    ENV -->|reads config| UPDATE
    DB -->|input scan DB| UPDATE
    CATALOG -->|reads catalog| UPDATE
    CATALOGDIR -->|holds catalog files| UPDATE
    UPDATE -->|updates| CATALOG
    UPDATE -->|writes to| CATALOGDIR

    T1 -->|tests| SCAN
    T1 -->|loads config| ENV
    T2 -->|tests| UPDATE
    T2 -->|loads config| ENV

    %% Click Events
    click TOML "https://github.com/tangilab/lightroom-path-migrator/blob/main/pyproject.toml"
    click REQ "https://github.com/tangilab/lightroom-path-migrator/blob/main/requirements.txt"
    click SCAN "https://github.com/tangilab/lightroom-path-migrator/blob/main/scan_photos.py"
    click UPDATE "https://github.com/tangilab/lightroom-path-migrator/blob/main/update_lightroom_paths.py"
    click T1 "https://github.com/tangilab/lightroom-path-migrator/blob/main/tests/test_scan_photos.py"
    click T2 "https://github.com/tangilab/lightroom-path-migrator/blob/main/tests/test_update_lightroom_paths.py"
    click README "https://github.com/tangilab/lightroom-path-migrator/blob/main/README.md"
    click LICENSE "https://github.com/tangilab/lightroom-path-migrator/tree/main/LICENSE"
    click GITIGNORE "https://github.com/tangilab/lightroom-path-migrator/blob/main/.gitignore"

    %% Styles
    classDef process fill:#bbdefb,stroke:#0d47a1,color:#0d47a1;
    classDef storage fill:#c8e6c9,stroke:#1b5e20,color:#1b5e20;
    classDef external fill:#eeeeee,stroke:#616161,color:#424242;
    classDef config fill:#fff9c4,stroke:#f57f17,color:#f57f17;
    classDef test fill:#b3e5fc,stroke:#0277bd,color:#0277bd;
    classDef doc fill:#f5f5f5,stroke:#9e9e9e,color:#616161;
```
