# ilevytate/stratosort architecture

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

- Interactive diagram: https://gitdiagram.com/ilevytate/stratosort
- Repository: https://github.com/ilevytate/stratosort

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Renderer Layer
    subgraph "Renderer (UI Layer)"
        direction TB
        Renderer["Renderer Process\n(React, Tailwind CSS)"]:::frontend
    end

    %% Preload Script
    subgraph "Preload Script"
        direction TB
        Preload["Preload Script\n(window.api IPC bridge)"]:::core
    end

    %% IPC Layer
    subgraph "IPC Handlers" 
        direction TB
        IPCIndex["IPC Index\n(register channels)"]:::core
        AnalysisIPC["analysis.js"]:::core
        HistoryIPC["analysisHistory.js"]:::core
        FilesIPC["files.js"]:::core
        SettingsIPC["settings.js"]:::core
        UndoRedoIPC["undoRedo.js"]:::core
        SmartFoldersIPC["smartFolders.js"]:::core
        OllamaIPC["ollama.js"]:::core
        SemanticIPC["semantic.js"]:::core
        SystemIPC["system.js"]:::core
        WindowIPC["window.js"]:::core
    end

    %% Core Utilities
    subgraph "Main Core Utilities"
        direction TB
        CreateWindow["createWindow.js"]:::core
        CustomFolders["customFolders.js"]:::core
        SystemAnalytics["systemAnalytics.js"]:::core
    end

    %% Services Layer
    subgraph "Services"
        direction TB
        AnalysisHistoryService["AnalysisHistoryService"]:::services
        EmbeddingIndexService["EmbeddingIndexService"]:::services
        FolderMatchingService["FolderMatchingService"]:::services
        OrganizeResumeService["OrganizeResumeService"]:::services
        UndoRedoService["UndoRedoService"]:::services
        SettingsService["SettingsService"]:::services
        PerformanceService["PerformanceService"]:::services
        ProcessingStateService["ProcessingStateService"]:::services
        ModelManager["ModelManager"]:::services
        ModelVerifier["ModelVerifier"]:::services
        SmartFoldersLLMService["SmartFoldersLLMService"]:::services
        ServiceIntegration["ServiceIntegration"]:::services
    end

    %% Analysis Modules
    subgraph "Analysis Modules"
        direction TB
        DocumentExtractors["documentExtractors.js"]:::services
        DocumentLLM["documentLlm.js"]:::services
        FallbackUtils["fallbackUtils.js"]:::services
        AudioAnalysis["ollamaAudioAnalysis.js"]:::services
        DocAnalysis["ollamaDocumentAnalysis.js"]:::services
        ImageAnalysis["ollamaImageAnalysis.js"]:::services
        AnalysisUtils["utils.js"]:::services
    end

    %% LLM Integration Helpers
    subgraph "LLM Integration Helpers"
        direction TB
        LlmService["llmService.js"]:::services
        OllamaUtils["ollamaUtils.js"]:::services
    end

    %% FileSystem & Persistence
    subgraph "File System & Persistence"
        direction TB
        AtomicOps["atomicFileOperations.js"]:::storage
        SharedConsts["constants.js"]:::storage
        SharedLogger["logger.js"]:::storage
    end

    %% External Service
    OllamaServer["Local Ollama Server\n(HTTP AI Models)"]:::external

    %% Entry Points
    subgraph "Entry Points"
        direction TB
        SimpleMain["simple-main.js"]:::core
        RendererIndex["index.js / index.html"]:::frontend
    end

    %% Folder Scanner
    FolderScanner["folderScanner.js"]:::core

    %% Connections
    Renderer -->|calls| Preload
    Preload -->|forwards IPC| IPCIndex
    IPCIndex --> AnalysisIPC
    IPCIndex --> HistoryIPC
    IPCIndex --> FilesIPC
    IPCIndex --> SettingsIPC
    IPCIndex --> UndoRedoIPC
    IPCIndex --> SmartFoldersIPC
    IPCIndex --> OllamaIPC
    IPCIndex --> SemanticIPC
    IPCIndex --> SystemIPC
    IPCIndex --> WindowIPC

    AnalysisIPC -->|uses| AnalysisHistoryService
    AnalysisIPC -->|calls| DocumentLLM
    AnalysisIPC -->|calls| DocAnalysis
    AnalysisIPC -->|calls| ImageAnalysis

    HistoryIPC --> AnalysisHistoryService
    FilesIPC --> OrganizeResumeService
    SettingsIPC --> SettingsService
    UndoRedoIPC --> UndoRedoService
    SmartFoldersIPC --> SmartFoldersLLMService

    OrganizeResumeService --> AtomicOps
    OrganizeResumeService --> UndoRedoService
    UndoRedoService --> AnalysisHistoryService

    AnalysisHistoryService --> SharedConsts
    AnalysisHistoryService --> SharedLogger

    AnalysisHistoryService --> EmbeddingIndexService
    EmbeddingIndexService --> SharedConsts

    FolderMatchingService --> ServiceIntegration
    ServiceIntegration --> LlmService

    SmartFoldersLLMService --> LlmService
    LlmService --> OllamaUtils
    LlmService --> OllamaServer
    DocumentLLM --> LlmService
    DocAnalysis --> OllamaServer
    ImageAnalysis --> OllamaServer
    AudioAnalysis --> OllamaServer

    SettingsService --> SharedConsts
    SettingsService --> SharedLogger

    %% Core utils usage
    AnalysisHistoryService --> CreateWindow
    OrganizeResumeService --> CustomFolders
    SystemAnalytics --> SharedLogger

    %% Entry points
    SimpleMain --> CreateWindow
    SimpleMain --> IPCIndex
    RendererIndex --> Renderer

    FolderScanner --> OrganizeResumeService

    %% IPC events to UI
    WindowIPC -->|events| Renderer

    %% Click events
    click Renderer "https://github.com/ilevytate/stratosort/tree/main/src/renderer"
    click Preload "https://github.com/ilevytate/stratosort/blob/main/src/preload/preload.js"
    click IPCIndex "https://github.com/ilevytate/stratosort/blob/main/src/main/ipc/index.js"
    click AnalysisIPC "https://github.com/ilevytate/stratosort/blob/main/src/main/ipc/analysis.js"
    click HistoryIPC "https://github.com/ilevytate/stratosort/blob/main/src/main/ipc/analysisHistory.js"
    click FilesIPC "https://github.com/ilevytate/stratosort/blob/main/src/main/ipc/files.js"
    click SettingsIPC "https://github.com/ilevytate/stratosort/blob/main/src/main/ipc/settings.js"
    click UndoRedoIPC "https://github.com/ilevytate/stratosort/blob/main/src/main/ipc/undoRedo.js"
    click SmartFoldersIPC "https://github.com/ilevytate/stratosort/blob/main/src/main/ipc/smartFolders.js"
    click OllamaIPC "https://github.com/ilevytate/stratosort/blob/main/src/main/ipc/ollama.js"
    click SemanticIPC "https://github.com/ilevytate/stratosort/blob/main/src/main/ipc/semantic.js"
    click SystemIPC "https://github.com/ilevytate/stratosort/blob/main/src/main/ipc/system.js"
    click WindowIPC "https://github.com/ilevytate/stratosort/blob/main/src/main/ipc/window.js"
    click CreateWindow "https://github.com/ilevytate/stratosort/blob/main/src/main/core/createWindow.js"
    click CustomFolders "https://github.com/ilevytate/stratosort/blob/main/src/main/core/customFolders.js"
    click SystemAnalytics "https://github.com/ilevytate/stratosort/blob/main/src/main/core/systemAnalytics.js"
    click AnalysisHistoryService "https://github.com/ilevytate/stratosort/blob/main/src/main/services/AnalysisHistoryService.js"
    click EmbeddingIndexService "https://github.com/ilevytate/stratosort/blob/main/src/main/services/EmbeddingIndexService.js"
    click FolderMatchingService "https://github.com/ilevytate/stratosort/blob/main/src/main/services/FolderMatchingService.js"
    click OrganizeResumeService "https://github.com/ilevytate/stratosort/blob/main/src/main/services/OrganizeResumeService.js"
    click UndoRedoService "https://github.com/ilevytate/stratosort/blob/main/src/main/services/UndoRedoService.js"
    click SettingsService "https://github.com/ilevytate/stratosort/blob/main/src/main/services/SettingsService.js"
    click PerformanceService "https://github.com/ilevytate/stratosort/blob/main/src/main/services/PerformanceService.js"
    click ProcessingStateService "https://github.com/ilevytate/stratosort/blob/main/src/main/services/ProcessingStateService.js"
    click ModelManager "https://github.com/ilevytate/stratosort/blob/main/src/main/services/ModelManager.js"
    click ModelVerifier "https://github.com/ilevytate/stratosort/blob/main/src/main/services/ModelVerifier.js"
    click SmartFoldersLLMService "https://github.com/ilevytate/stratosort/blob/main/src/main/services/SmartFoldersLLMService.js"
    click ServiceIntegration "https://github.com/ilevytate/stratosort/blob/main/src/main/services/ServiceIntegration.js"
    click DocumentExtractors "https://github.com/ilevytate/stratosort/blob/main/src/main/analysis/documentExtractors.js"
    click DocumentLLM "https://github.com/ilevytate/stratosort/blob/main/src/main/analysis/documentLlm.js"
    click FallbackUtils "https://github.com/ilevytate/stratosort/blob/main/src/main/analysis/fallbackUtils.js"
    click AudioAnalysis "https://github.com/ilevytate/stratosort/blob/main/src/main/analysis/ollamaAudioAnalysis.js"
    click DocAnalysis "https://github.com/ilevytate/stratosort/blob/main/src/main/analysis/ollamaDocumentAnalysis.js"
    click ImageAnalysis "https://github.com/ilevytate/stratosort/blob/main/src/main/analysis/ollamaImageAnalysis.js"
    click AnalysisUtils "https://github.com/ilevytate/stratosort/blob/main/src/main/analysis/utils.js"
    click LlmService "https://github.com/ilevytate/stratosort/blob/main/src/main/llmService.js"
    click OllamaUtils "https://github.com/ilevytate/stratosort/blob/main/src/main/ollamaUtils.js"
    click AtomicOps "https://github.com/ilevytate/stratosort/blob/main/src/shared/atomicFileOperations.js"
    click SharedConsts "https://github.com/ilevytate/stratosort/blob/main/src/shared/constants.js"
    click SharedLogger "https://github.com/ilevytate/stratosort/blob/main/src/shared/logger.js"
    click SimpleMain "https://github.com/ilevytate/stratosort/blob/main/src/main/simple-main.js"
    click RendererIndex "https://github.com/ilevytate/stratosort/blob/main/src/renderer/index.js"
    click FolderScanner "https://github.com/ilevytate/stratosort/blob/main/src/main/folderScanner.js"

    %% Styles
    classDef frontend fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef core fill:#90EE90,stroke:#333,stroke-width:1px
    classDef services fill:#FFA500,stroke:#333,stroke-width:1px
    classDef external fill:#D3D3D3,stroke:#333,stroke-width:1px
    classDef storage fill:#CD853F,stroke:#333,stroke-width:1px
```
