# selfref/memento architecture

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

- Interactive diagram: https://gitdiagram.com/selfref/memento
- Repository: https://github.com/selfref/memento

## Overview

##### Project type and purpose
- This is a standalone desktop application written in Python. It uses GTK 4 and libadwaita for its GUI, the blueprint-compiler to transform .blp files into UI definitions, and various Python libraries (Pillow, easyocr, etc.) for image processing and OCR. Its goal is to let users browse, preview, tag, search, and cache “memes” (image files) stored in a local folder.

##### File structure
- Top-level:
- assets/            – screenshots, demo media (not part of runtime architecture)
- requirements.txt   – lists Python dependencies
- src/               – application code
- src/:
- main.py            – application entrypoint and startup
- window.py          – orchestration of main window and dialogs
- ui/                – .blp blueprint files: main window, about dialog, settings dialog
- models.py          – domain models (e.g., Meme, Tag, CacheEntry)
- utils.py           – file‐system scanner, thumbnail/caching helper functions
- settings.py        – load/save user preferences
- No server or network sub-directories; it’s a monolithic desktop app.

##### README for additional insights
- Key features: recursive folder scan, cache generation, image preview, search by filename/tags, built-in (optional) OCR for extracting text.
- External dependencies: GTK 4, libadwaita, pillow, unidecode, easyocr.
- No database server—metadata likely held in local files or in-memory structures; cache persisted to disk.

a. Main components
1. UI Layer (blue):
– Blueprint Compiler → .blp UI definitions → GTK 4 Widgets
– MainWindow, PreviewPane, FileGrid, SearchBox, AboutDialog, SettingsDialog
2. Controller / Orchestrator (green):
– main.py: application initialization, dependency wiring
– window.py: routing UI events to services
3. Core Services (green):
– FileScannerService: recursive scan of meme folder
– CacheManager: generate & retrieve thumbnails
– SearchService: filter by filename and tag
– OCRService (optional): invoke easyocr and extract text
– SettingsService: read/write user preferences
4. Models / Data Structures (light green):
– Meme (path, thumbnail path, tags, metadata)
– Tag (text string, associated Meme references)
5. Data Layer (orange):
– Local File System:
- Meme folder (source images)
- Cache directory (thumbnails)
- Settings file (e.g., JSON)
6. External Libraries and Dependencies (gray):
– GTK 4 + libadwaita
– blueprint-compiler
– Pillow
– unidecode
– easyocr

b. Relationships and interactions
- On startup: main.py → SettingsService → load preferences
- UI event (e.g., “Browse folder”): MainWindow → FileScannerService → read file system → produce list of Meme models → UI renders FileGrid
- Selecting an image: UI calls CacheManager to fetch/generate thumbnail → displayed in PreviewPane
- User searches: SearchBox → SearchService filters Meme models → UI updates grid
- OCR tagging (if enabled): Controller triggers OCRService on selected Meme → tags added to Meme model → optional persistence
- Settings changes: SettingsDialog → SettingsService → write settings file

c. Architectural patterns
- Layered MVC/MVVM-style separation:
- View (GTK UI)
- Controller/Presenter (main.py, window.py)
- Model/Services (models.py, utils.py, settings.py)
- Service-oriented within a monolith: distinct services for scanning, caching, search, OCR
- Dependency injection at startup: services wired in main.py

d. Key technologies/frameworks
- Python 3
- GTK 4 + libadwaita (desktop GUI)
- blueprint-compiler (.blp → GTK UI)
- Pillow (image handling)
- unidecode (text normalization)
- easyocr (optional OCR)

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Application (Python)"
        subgraph "UI Layer"
            UIDir["src/ui/"]:::ui
            mainBLP["main.blp"]:::ui
            aboutBLP["about.blp"]:::ui
            settingsBLP["settings/"]:::ui
            MainWindow["MainWindow (GTK Widgets)"]:::ui
            FileGrid["FileGrid"]:::ui
            SearchBox["SearchBox"]:::ui
            PreviewPane["PreviewPane"]:::ui
            AboutDialog["AboutDialog"]:::ui
            SettingsDialogUI["SettingsDialog"]:::ui
        end
        subgraph "Controller"
            MainPy["main.py"]:::controller
            WindowPy["window.py"]:::controller
        end
        subgraph "Services"
            FileScanner["FileScannerService"]:::service
            CacheManager["CacheManager"]:::service
            SearchService["SearchService"]:::service
            OCRService["OCRService (optional)"]:::service
            SettingsService["SettingsService"]:::service
        end
        subgraph "Models"
            ModelsPy["models.py\n(Meme, Tag, CacheEntry)"]:::model
        end
    end

    subgraph "Data Layer"
        MemeFolder["Meme Folder"]:::data
        CacheFolder["Cache Folder"]:::data
        SettingsFile["Settings File"]:::data
    end

    subgraph "External Libraries"
        GTK["GTK4 + libadwaita"]:::external
        BlueprintComp["blueprint-compiler"]:::external
        Pillow["Pillow"]:::external
        Unidecode["unidecode"]:::external
        EasyOCR["easyocr"]:::external
    end

    %% UI Definitions structure
    UIDir --> mainBLP
    UIDir --> aboutBLP
    UIDir --> settingsBLP

    %% Startup flows
    MainPy --> SettingsService
    SettingsService --> SettingsFile
    MainPy --> BlueprintComp
    BlueprintComp --> UIDir

    %% UI rendering flows
    UIDir --> MainWindow
    MainWindow --> FileGrid
    MainWindow --> SearchBox
    MainWindow --> PreviewPane
    MainWindow --> AboutDialog
    MainWindow --> SettingsDialogUI

    %% Event routing
    MainWindow -. UI_event .-> WindowPy

    %% Controller to services
    WindowPy --> FileScanner
    WindowPy --> CacheManager
    WindowPy --> SearchService
    WindowPy --> OCRService
    WindowPy --> SettingsService

    %% Services to data / models / libs
    FileScanner --> MemeFolder
    FileScanner --> ModelsPy
    CacheManager --> CacheFolder
    SearchService --> ModelsPy
    OCRService --> EasyOCR
    OCRService --> ModelsPy

    %% Data back to UI
    FileScanner -->|memes list| FileGrid
    CacheManager -->|thumbnail| PreviewPane
    SearchService -->|filtered memes| FileGrid
    OCRService -->|tags| MainWindow

    %% Click Events
    click UIDir "https://github.com/selfref/memento/tree/master/src/ui/"
    click mainBLP "https://github.com/selfref/memento/blob/master/src/ui/main.blp"
    click aboutBLP "https://github.com/selfref/memento/blob/master/src/ui/about.blp"
    click settingsBLP "https://github.com/selfref/memento/tree/master/src/ui/settings/"
    click MainPy "https://github.com/selfref/memento/blob/master/src/main.py"
    click WindowPy "https://github.com/selfref/memento/blob/master/src/window.py"
    click ModelsPy "https://github.com/selfref/memento/blob/master/src/models.py"
    click FileScanner "https://github.com/selfref/memento/blob/master/src/utils.py"
    click CacheManager "https://github.com/selfref/memento/blob/master/src/utils.py"
    click SearchService "https://github.com/selfref/memento/blob/master/src/utils.py"
    click OCRService "https://github.com/selfref/memento/blob/master/src/utils.py"
    click SettingsService "https://github.com/selfref/memento/blob/master/src/settings.py"
    click requirements "https://github.com/selfref/memento/blob/master/requirements.txt"

    classDef ui fill:#ADD8E6,stroke:#000;
    classDef controller fill:#90EE90,stroke:#000;
    classDef service fill:#98FB98,stroke:#000;
    classDef model fill:#90EE90,stroke:#000;
    classDef data fill:#FFA500,stroke:#000;
    classDef external fill:#D3D3D3,stroke:#000;
```
