# hyperfield/ai-file-sorter architecture

> Architecture diagram of the GitHub repository hyperfield/ai-file-sorter, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hyperfield/ai-file-sorter
- Repository: https://github.com/hyperfield/ai-file-sorter

## Overview

AI File Sorter is a cross-platform desktop application that scans a chosen folder, analyzes files, proposes categories and supported rename suggestions, then lets the user review and apply changes. The README documents local and remote AI, image and document analysis, media-metadata naming, learned behavior, whitelists, and storage-provider support. The graph follows those product stages and includes persistence and plugin extension layers. Workflow links reflect the README’s stated behavior; sampled excerpts were partial, so uncertain internal call wiring is omitted.

Main entry points: [`app/lib/AnalysisCoordinator.cpp`](https://github.com/hyperfield/ai-file-sorter/blob/main/app/lib/AnalysisCoordinator.cpp) (Analysis coordinator), [`app/lib/CategorizationService.cpp`](https://github.com/hyperfield/ai-file-sorter/blob/main/app/lib/CategorizationService.cpp) (Categorization), [`app/lib/HeadlessReviewApplyService.cpp`](https://github.com/hyperfield/ai-file-sorter/blob/main/app/lib/HeadlessReviewApplyService.cpp) (Review apply), [`app/include/StorageProvider.hpp`](https://github.com/hyperfield/ai-file-sorter/blob/main/app/include/StorageProvider.hpp) (Storage providers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interaction["User interaction"]
  node_desktop["Desktop app<br/>[MainApp.cpp]"]
  node_headless["Headless command"]
  node_review["Review results"]
end

subgraph group_analysis["Analysis and suggestions"]
  node_analysis_run["Analysis coordinator"]
  node_scanner["File scanning<br/>[FileScanner.cpp]"]
  node_categorization["Categorization"]
  node_image_analysis["Image analysis"]
  node_document_analysis["Document analysis"]
  node_media_names["Media naming"]
end

subgraph group_apply["Review and storage"]
  node_apply["Review apply"]
  node_storage["Storage providers"]
end

subgraph group_models["AI and model runtime"]
  node_local_llm["Local LLM<br/>[LocalLLMClient.cpp]"]
  node_remote_llm["Remote clients<br/>[LLMClient.cpp]"]
  node_gemini["Gemini client<br/>[GeminiClient.cpp]"]
  node_visual_runtime["Visual runtime"]
end

subgraph group_extensions["State and extensions"]
  node_database[("Categorization cache")]
  node_learning[("Learned behavior")]
  node_whitelist[("Category whitelists<br/>[WhitelistStore.cpp]")]
  node_history[("Review history")]
  node_plugin_manager["Storage plugins"]
  node_onedrive["OneDrive provider"]
end

node_user(("User"))
node_model_source(("Model services"))
node_filesystem[("Files and folders")]

node_user -->|"selects folder"| node_desktop
node_user -->|"starts analysis"| node_headless
node_desktop -->|"starts analysis"| node_analysis_run
node_headless -->|"runs analysis"| node_analysis_run
node_analysis_run -->|"scans files"| node_scanner
node_scanner -->|"reads entries"| node_filesystem
node_analysis_run -->|"requests suggestions"| node_categorization
node_analysis_run -->|"analyzes images"| node_image_analysis
node_analysis_run -->|"analyzes documents"| node_document_analysis
node_analysis_run -->|"reads media metadata"| node_media_names
node_categorization -.->|"uses local model"| node_local_llm
node_categorization -.->|"uses remote model"| node_remote_llm
node_categorization -.->|"uses Gemini"| node_gemini
node_image_analysis -->|"uses visual runtime"| node_visual_runtime
node_analysis_run -->|"uses categorization cache"| node_database
node_analysis_run -->|"uses prior decisions"| node_learning
node_analysis_run -->|"uses category rules"| node_whitelist
node_analysis_run -->|"presents suggestions"| node_review
node_user -->|"reviews suggestions"| node_review
node_review -->|"confirms changes"| node_apply
node_apply -->|"moves and renames"| node_storage
node_storage -->|"mutates files"| node_filesystem
node_apply -->|"updates cache"| node_database
node_apply -->|"records changes"| node_history
node_plugin_manager -->|"loads provider"| node_onedrive
node_storage -->|"dispatches provider operations"| node_onedrive

click node_desktop "https://github.com/hyperfield/ai-file-sorter/blob/main/app/lib/MainApp.cpp"
click node_headless "https://github.com/hyperfield/ai-file-sorter/blob/main/app/lib/HeadlessAnalysisCommand.cpp"
click node_analysis_run "https://github.com/hyperfield/ai-file-sorter/blob/main/app/lib/AnalysisCoordinator.cpp"
click node_scanner "https://github.com/hyperfield/ai-file-sorter/blob/main/app/lib/FileScanner.cpp"
click node_categorization "https://github.com/hyperfield/ai-file-sorter/blob/main/app/lib/CategorizationService.cpp"
click node_image_analysis "https://github.com/hyperfield/ai-file-sorter/blob/main/app/lib/ImageAnalyzerFactory.cpp"
click node_document_analysis "https://github.com/hyperfield/ai-file-sorter/blob/main/app/lib/DocumentTextAnalyzer.cpp"
click node_media_names "https://github.com/hyperfield/ai-file-sorter/blob/main/app/lib/MediaRenameMetadataService.cpp"
click node_review "https://github.com/hyperfield/ai-file-sorter/blob/main/app/lib/ResultsCoordinator.cpp"
click node_apply "https://github.com/hyperfield/ai-file-sorter/blob/main/app/lib/HeadlessReviewApplyService.cpp"
click node_storage "https://github.com/hyperfield/ai-file-sorter/blob/main/app/include/StorageProvider.hpp"
click node_local_llm "https://github.com/hyperfield/ai-file-sorter/blob/main/app/lib/LocalLLMClient.cpp"
click node_remote_llm "https://github.com/hyperfield/ai-file-sorter/blob/main/app/lib/LLMClient.cpp"
click node_gemini "https://github.com/hyperfield/ai-file-sorter/blob/main/app/lib/GeminiClient.cpp"
click node_visual_runtime "https://github.com/hyperfield/ai-file-sorter/blob/main/app/lib/VisualLlmRuntime.cpp"
click node_database "https://github.com/hyperfield/ai-file-sorter/blob/main/app/lib/DatabaseManager.cpp"
click node_learning "https://github.com/hyperfield/ai-file-sorter/blob/main/app/lib/UserLearningStore.cpp"
click node_whitelist "https://github.com/hyperfield/ai-file-sorter/blob/main/app/lib/WhitelistStore.cpp"
click node_history "https://github.com/hyperfield/ai-file-sorter/blob/main/app/lib/ReviewHistoryStore.cpp"
click node_plugin_manager "https://github.com/hyperfield/ai-file-sorter/blob/main/app/lib/StoragePluginManager.cpp"
click node_onedrive "https://github.com/hyperfield/ai-file-sorter/blob/main/app/lib/OneDriveStorageProvider.cpp"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_desktop,node_headless,node_review,node_user toneBlue
class node_analysis_run,node_scanner,node_categorization,node_image_analysis,node_document_analysis,node_media_names,node_filesystem toneAmber
class node_apply,node_storage toneMint
class node_local_llm,node_remote_llm,node_gemini,node_visual_runtime toneRose
class node_database,node_learning,node_whitelist,node_history,node_plugin_manager,node_onedrive,node_model_source toneIndigo
```

## Components

### User interaction

- [Desktop app](https://github.com/hyperfield/ai-file-sorter/blob/main/app/lib/MainApp.cpp): `app/lib/MainApp.cpp`
- [Headless command](https://github.com/hyperfield/ai-file-sorter/blob/main/app/lib/HeadlessAnalysisCommand.cpp): `app/lib/HeadlessAnalysisCommand.cpp`
- [Review results](https://github.com/hyperfield/ai-file-sorter/blob/main/app/lib/ResultsCoordinator.cpp): `app/lib/ResultsCoordinator.cpp`

### Analysis and suggestions

- [Analysis coordinator](https://github.com/hyperfield/ai-file-sorter/blob/main/app/lib/AnalysisCoordinator.cpp): `app/lib/AnalysisCoordinator.cpp`
- [File scanning](https://github.com/hyperfield/ai-file-sorter/blob/main/app/lib/FileScanner.cpp): `app/lib/FileScanner.cpp`
- [Categorization](https://github.com/hyperfield/ai-file-sorter/blob/main/app/lib/CategorizationService.cpp): `app/lib/CategorizationService.cpp`
- [Image analysis](https://github.com/hyperfield/ai-file-sorter/blob/main/app/lib/ImageAnalyzerFactory.cpp): `app/lib/ImageAnalyzerFactory.cpp`
- [Document analysis](https://github.com/hyperfield/ai-file-sorter/blob/main/app/lib/DocumentTextAnalyzer.cpp): `app/lib/DocumentTextAnalyzer.cpp`
- [Media naming](https://github.com/hyperfield/ai-file-sorter/blob/main/app/lib/MediaRenameMetadataService.cpp): `app/lib/MediaRenameMetadataService.cpp`

### Review and storage

- [Review apply](https://github.com/hyperfield/ai-file-sorter/blob/main/app/lib/HeadlessReviewApplyService.cpp): `app/lib/HeadlessReviewApplyService.cpp`
- [Storage providers](https://github.com/hyperfield/ai-file-sorter/blob/main/app/include/StorageProvider.hpp): `app/include/StorageProvider.hpp`

### AI and model runtime

- [Local LLM](https://github.com/hyperfield/ai-file-sorter/blob/main/app/lib/LocalLLMClient.cpp): `app/lib/LocalLLMClient.cpp`
- [Remote clients](https://github.com/hyperfield/ai-file-sorter/blob/main/app/lib/LLMClient.cpp): `app/lib/LLMClient.cpp`
- [Gemini client](https://github.com/hyperfield/ai-file-sorter/blob/main/app/lib/GeminiClient.cpp): `app/lib/GeminiClient.cpp`
- [Visual runtime](https://github.com/hyperfield/ai-file-sorter/blob/main/app/lib/VisualLlmRuntime.cpp): `app/lib/VisualLlmRuntime.cpp`

### State and extensions

- [Categorization cache](https://github.com/hyperfield/ai-file-sorter/blob/main/app/lib/DatabaseManager.cpp): `app/lib/DatabaseManager.cpp`
- [Learned behavior](https://github.com/hyperfield/ai-file-sorter/blob/main/app/lib/UserLearningStore.cpp): `app/lib/UserLearningStore.cpp`
- [Category whitelists](https://github.com/hyperfield/ai-file-sorter/blob/main/app/lib/WhitelistStore.cpp): `app/lib/WhitelistStore.cpp`
- [Review history](https://github.com/hyperfield/ai-file-sorter/blob/main/app/lib/ReviewHistoryStore.cpp): `app/lib/ReviewHistoryStore.cpp`
- [Storage plugins](https://github.com/hyperfield/ai-file-sorter/blob/main/app/lib/StoragePluginManager.cpp): `app/lib/StoragePluginManager.cpp`
- [OneDrive provider](https://github.com/hyperfield/ai-file-sorter/blob/main/app/lib/OneDriveStorageProvider.cpp): `app/lib/OneDriveStorageProvider.cpp`

### Other components

- **User**
- **Model services**
- **Files and folders**

## Connections

- User → Desktop app: selects folder
- User → Headless command: starts analysis
- Desktop app → Analysis coordinator: starts analysis
- Headless command → Analysis coordinator: runs analysis
- Analysis coordinator → File scanning: scans files
- File scanning → Files and folders: reads entries
- Analysis coordinator → Categorization: requests suggestions
- Analysis coordinator → Image analysis: analyzes images
- Analysis coordinator → Document analysis: analyzes documents
- Analysis coordinator → Media naming: reads media metadata
- Categorization → Local LLM: uses local model
- Categorization → Remote clients: uses remote model
- Categorization → Gemini client: uses Gemini
- Image analysis → Visual runtime: uses visual runtime
- Analysis coordinator → Categorization cache: uses categorization cache
- Analysis coordinator → Learned behavior: uses prior decisions
- Analysis coordinator → Category whitelists: uses category rules
- Analysis coordinator → Review results: presents suggestions
- User → Review results: reviews suggestions
- Review results → Review apply: confirms changes
- Review apply → Storage providers: moves and renames
- Storage providers → Files and folders: mutates files
- Review apply → Categorization cache: updates cache
- Review apply → Review history: records changes
- Storage plugins → OneDrive provider: loads provider
- Storage providers → OneDrive provider: dispatches provider operations