CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Turbo Sorter Pro v12.5 - A Python-based image management and sorting system with two web interfaces:

Streamlit app (port 8501): 5-tab workflow for image discovery, collision resolution, archive management, categorization, and gallery staging
NiceGUI app (port 8080): Real-time image tagging interface with hotkey support and batch operations

Running the Applications

# Install dependencies
pip install -r requirements.txt

# Run Streamlit interface
streamlit run app.py --server.port=8501 --server.address=0.0.0.0

# Run NiceGUI gallery interface
python3 gallery_app.py

# Run both (Docker production mode)
./start.sh

Architecture

Core Components

engine.py - SorterEngine class with 40+ static methods for all business logic. Central SQLite-based state management at /app/sorter_database.db. Handles profile management, image operations, staging, batch processing, and undo history.
app.py - Streamlit entry point. Initializes database, manages session state, renders 5-tab interface.
gallery_app.py - NiceGUI entry point with AppState class. Provides async image serving via FastAPI, hotkey-based tagging, and batch copy/move operations.

Streamlit Tab Modules

Tab	Module	Purpose
1. Discovery	`tab_time_discovery.py`	Time-sync matcher for sibling folders
2. ID Review	`tab_id_review.py`	Collision detection and ID harmonization
3. Unused	`tab_unused_review.py`	Archive review and restoration
4. Category Sorter	`tab_category_sorter.py`	Bulk categorization and renaming
5. Gallery Staged	`tab_gallery_sorter.py`	Interactive tagging interface

Database Schema (SQLite)

Key tables:

profiles - Workspace configurations with tab path mappings
folder_ids - Persistent folder identifiers
staging_area - Pending file operations
processed_log - Action history for undo
folder_tags - Per-folder image tags with metadata
profile_categories - Profile-specific category lists

Key Patterns

Profile-based multi-tenancy: Each workspace has isolated path configurations
Soft deletes: Files moved to _DELETED folder for undo support
Parallel image loading: ThreadPoolExecutor in load_batch_parallel()
Session state: Streamlit st.session_state for tab indices and history
WebP compression: PIL-based with configurable quality slider

2.5 KiB Raw Blame History