How selfref/memento works
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)