How ilevytate/stratosort works
Project Type & Purpose
• Electron desktop application (Node.js + Chromium)
• React-based renderer for the UI
• Local-first AI document and image organizer using Ollama models
• Key features: document/image analysis, smart folder matching, batch moves with undo/redo, settings/configuration
High-Level Architecture
• Two primary processes:
• Main process (backend) – orchestrates services, file system access, LLM calls, state management
• Renderer process (frontend) – React app providing UI, user interactions, progress/status displays
• Preload script – secure bridge exposing selected IPC APIs from the main process to the renderer
• External dependency: local Ollama server running user-configured AI models
• Persistent storage – JSON files in user data (analysis-history.json), settings persisted via SettingsService
Main Components
A. Renderer Process (UI Layer)
• src/renderer: React components (AppShell, DiscoverPhase, OrganizePhase, SetupPhase, etc.)
• Contexts & hooks to manage notifications, phases, keyboard shortcuts, drag/drop
• Tailwind CSS for styling
• Exposes high-level UI actions (e.g., “Analyze documents,” “Organize files,” “Undo/Redo”)
B. Preload Script
• src/preload/preload.js
• Exposes window.api with strongly typed IPC methods (analysis, files, settings, undoRedo, etc.)
• Ensures renderer cannot invoke arbitrary Node APIs
C. Main Process (Core & Services)
1. Core
• createWindow.js: spawns renderer windows
• customFolders.js, systemAnalytics.js: system-level utilities
2. IPC Handlers (src/main/ipc)
• analysis.js, files.js, settings.js, undoRedo.js, etc.
• IPC channel names to service calls, wrap with error logging
3. Services (src/main/services)
• AnalysisHistoryService: persists/replays analysis history
• EmbeddingIndexService: manages embedding indexes for fast lookup
• FolderMatchingService: matches files to smart folder rules
• OrganizeResumeService: coordinates batch file moves
• UndoRedoService: tracks operations for safe rollback
• SettingsService, PerformanceService, ModelManager/Verifier, ProcessingStateService, SmartFoldersLLMService
4. Analysis Modules (src/main/analysis)
• documentExtractors.js, ollamaDocumentAnalysis.js, ollamaImageAnalysis.js
• utils and fallback handlers for OCR, text extraction, audio analysis
5. LLM Integration Helpers
• llmService.js, ollamaUtils.js: HTTP client to local Ollama server, model selection, request/response handling
D. File System & Persistence (src/shared, atomicFileOperations.js)
• Cross-platform file moves, safe temp operations
• JSON read/write for settings and history
E. External AI Service
• Local Ollama server (HTTP API) hosting text/vision/embedding models
• User configures host and model names via Settings UI or setup script
Component Interactions & Data Flow
1. User clicks “Analyze” in UI → renderer calls window.api.analysis.start
2. Preload forwards to main IPC handler → AnalysisHistoryService records start event
3. Main process invokes Analysis modules → calls ollamaService to analyze files
4. Analysis results returned → indexed by EmbeddingIndexService → persisted by history service
5. UI polls or listens on IPC events → displays progress/results
6. User triggers “Organize” → OrganizeResumeService performs atomicFileOperations
7. UndoRedoService logs each file move → persisted in history JSON
8. Renderer “Undo” requests → main reverts via UndoRedoService
Architectural Patterns & Principles
• Clear separation of concerns: UI vs. backend logic vs. AI integration
• Layered design: IPC layer mediates between renderer and services
• Event sourcing/history: undo/redo built on persisted operation logs
• Plugin-style analysis: modules under src/main/analysis can be extended
• Safe file operations: atomic moves, conflict resolution