# logicalpath/photomanage architecture

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

- Interactive diagram: https://gitdiagram.com/logicalpath/photomanage
- Repository: https://github.com/logicalpath/photomanage

## Overview

##### Main Components

a) File Processing Layer
- File processing scripts (shown in /scripts directory)
- Media file handling components (rename, move, thumbnail creation)

b) Data Processing Layer
- EXIF data extraction system
- UUID generation and mapping system
- Date conversion utilities
- GPS/location processing

c) Storage Layer
- SQLite Database (mediameta.db)
- File System Storage (for original files and thumbnails)
- B2 Cloud Storage integration

d) Web Interface Layer (Datasette)
- Media viewer components
- Clustering/mapping features
- Enrichment plugins
- API endpoints

##### Flow and Relationships

**Input Files → File Processing → Data Processing → Storage → Web Interface**

##### Specific Implementation Details

**File Processing:**
- Media file detection
- Thumbnail generation (224x224)
- UUID renaming
- File movement

**Data Processing:**
- EXIF extraction
- Date normalization
- GPS coordinate processing
- Language detection

**Storage:**
- SQLite with spatial extensions
- File system organization
- B2 backup integration

**Web Interface:**
- Datasette server
- Media plugins
- Mapping features
- Enrichment capabilities

##### Important Architectural Notes

Annotations for:
- Asynchronous processing capabilities
- File system to database relationships
- Plugin architecture for Datasette
- Security considerations for media access

##### Integration Points

External service connections:
- B2 Cloud Storage
- OpenCage Geocoding
- Spatial data processing
- Vector embeddings support

This architecture emphasizes the system's capability to handle large-scale media processing while maintaining organized storage and accessible viewing options.

## Diagram (Mermaid)

```mermaid
graph TB
    classDef processing fill:#2196F3,stroke:#1565C0,color:white
    classDef data fill:#4CAF50,stroke:#2E7D32,color:white
    classDef storage fill:#FFC107,stroke:#FFA000,color:black
    classDef web fill:#9C27B0,stroke:#7B1FA2,color:white
    classDef external fill:#F44336,stroke:#D32F2F,color:white

    subgraph Input
        IL[Apple Photos Library]
        ID[Regular Directories]
    end

    subgraph "File Processing"
        FP["File Processing Scripts"]:::processing
        TG["Thumbnail Generation"]:::processing
        PG["Preview Generation"]:::processing
        FM["File Movement"]:::processing
    end

    subgraph "Data Processing"
        EX["EXIF Extraction"]:::data
        DP["Date Processing"]:::data
        LD["Language Detection"]:::data
        EP["Error Processing"]:::data
    end

    subgraph "Storage"
        DB[(SQLite Database)]:::storage
        FS["File System"]:::storage
        B2["B2 Cloud Storage"]:::external
        TS["Thumbnail Storage"]:::storage
    end

    subgraph "Web Interface"
        DS["Datasette Server"]:::web
        MP["Media Plugins"]:::web
        MF["Mapping Features"]:::web
        EP2["Enrichment Plugins"]:::web
    end

    IL --> FP
    ID --> FP
    FP --> TG
    FP --> PG
    FP --> FM
    
    TG --> TS
    PG --> FS
    FM --> FS
    
    FP --> EX
    EX --> DP
    EX --> LD
    EX --> EP
    
    DP --> DB
    LD --> DB
    EP --> DB
    
    FS --> B2
    DB --> DS
    FS --> DS
    TS --> DS
    
    DS --> MP
    DS --> MF
    DS --> EP2

    click FP "https://github.com/logicalpath/photomanage/blob/main/scripts/find_media_folders.sh"
    click TG "https://github.com/logicalpath/photomanage/blob/main/src/thumbnail_creator.py"
    click PG "https://github.com/logicalpath/photomanage/blob/main/src/preview_creator.py"
    click FM "https://github.com/logicalpath/photomanage/blob/main/scripts/move_uuid_dest.sh"
    click EX "https://github.com/logicalpath/photomanage/blob/main/scripts/getExifData.sh"
    click DP "https://github.com/logicalpath/photomanage/blob/main/src/to_iso_date.py"
    click LD "https://github.com/logicalpath/photomanage/blob/main/src/isEnglish.py"
    click EP "https://github.com/logicalpath/photomanage/blob/main/src/error_processing.py"
    click DS "https://github.com/logicalpath/photomanage/blob/main/database/datasette.yaml"
    click TS "https://github.com/logicalpath/photomanage/tree/main/224x224/"
    click MF "https://github.com/logicalpath/photomanage/blob/main/scripts/loadmap.sh"

    %% Legend
    subgraph Legend
        L1["Processing Components"]:::processing
        L2["Data Processing"]:::data
        L3["Storage Systems"]:::storage
        L4["Web Interface"]:::web
        L5["External Services"]:::external
    end
```
