# mauryasagar/ai-file-organizer architecture

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

- Interactive diagram: https://gitdiagram.com/mauryasagar/ai-file-organizer
- Repository: https://github.com/mauryasagar/ai-file-organizer

## Overview

Organizr is a local-first file organizer: users choose a folder, scan eligible files, review content-based category suggestions, and explicitly apply moves; they can undo the last move. The main flow and safety/history behavior are visible in app.py and organizer.py; the README documents additional formats, editable categories, previews, and run history. Relationships shown below are supported by excerpts or README statements; no other source was inspected.

Main entry points: [`app.py`](https://github.com/mauryasagar/ai-file-organizer/blob/main/app.py) (Streamlit workflow), [`organizer.py`](https://github.com/mauryasagar/ai-file-organizer/blob/main/organizer.py) (Apply and undo moves), [`classifier.py`](https://github.com/mauryasagar/ai-file-organizer/blob/main/classifier.py) (Local classification), [`scanner.py`](https://github.com/mauryasagar/ai-file-organizer/blob/main/scanner.py) (Safe file scan)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["User interface"]
  node_app["Streamlit workflow<br/>[app.py]"]
  node_plan["Editable plan and preview<br/>[app.py]"]
  node_history["Run history<br/>[app.py]"]
end

subgraph group_analysis["File analysis"]
  node_categories["Category settings<br/>[categories.json]"]
  node_scanner["Safe file scan<br/>[scanner.py]"]
  node_extractor["Text extraction<br/>[extractor.py]"]
  node_classifier["Local classification<br/>[classifier.py]"]
end

subgraph group_actions["File operations"]
  node_organizer["Apply and undo moves<br/>[organizer.py]"]
  node_undo_log["Undo log<br/>[organizer.py]"]
end

node_user(("User"))
node_ollama{{"Ollama / Gemma"}}
node_filesystem[("Chosen folder")]

node_user -->|"selects folder"| node_app
node_app -->|"scans folder"| node_scanner
node_scanner -->|"lists files"| node_filesystem
node_app -->|"extracts text"| node_extractor
node_extractor -->|"reads content"| node_filesystem
node_app -->|"classifies files"| node_classifier
node_app -->|"loads categories"| node_categories
node_classifier -->|"requests category"| node_ollama
node_ollama -->|"returns reason"| node_classifier
node_app -->|"builds plan"| node_plan
node_user -->|"reviews and edits"| node_plan
node_user -->|"approves moves"| node_app
node_app -->|"applies plan"| node_organizer
node_organizer -->|"moves files"| node_filesystem
node_organizer -->|"writes moves"| node_undo_log
node_user -->|"requests undo"| node_app
node_app -->|"calls undo"| node_organizer
node_organizer -->|"reads moves"| node_undo_log
node_organizer -->|"restores files"| node_filesystem
node_app -->|"records run"| node_history

click node_app "https://github.com/mauryasagar/ai-file-organizer/blob/main/app.py"
click node_categories "https://github.com/mauryasagar/ai-file-organizer/blob/main/categories.json"
click node_scanner "https://github.com/mauryasagar/ai-file-organizer/blob/main/scanner.py"
click node_extractor "https://github.com/mauryasagar/ai-file-organizer/blob/main/extractor.py"
click node_classifier "https://github.com/mauryasagar/ai-file-organizer/blob/main/classifier.py"
click node_plan "https://github.com/mauryasagar/ai-file-organizer/blob/main/app.py"
click node_organizer "https://github.com/mauryasagar/ai-file-organizer/blob/main/organizer.py"
click node_undo_log "https://github.com/mauryasagar/ai-file-organizer/blob/main/organizer.py"
click node_history "https://github.com/mauryasagar/ai-file-organizer/blob/main/app.py"

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_app,node_plan,node_history,node_user toneBlue
class node_categories,node_scanner,node_extractor,node_classifier,node_filesystem toneAmber
class node_organizer,node_undo_log toneMint
class node_ollama toneIndigo
```

## Components

### User interface

- [Streamlit workflow](https://github.com/mauryasagar/ai-file-organizer/blob/main/app.py): `app.py`
- [Editable plan and preview](https://github.com/mauryasagar/ai-file-organizer/blob/main/app.py): `app.py`
- [Run history](https://github.com/mauryasagar/ai-file-organizer/blob/main/app.py): `app.py`

### File analysis

- [Category settings](https://github.com/mauryasagar/ai-file-organizer/blob/main/categories.json): `categories.json`
- [Safe file scan](https://github.com/mauryasagar/ai-file-organizer/blob/main/scanner.py): `scanner.py`
- [Text extraction](https://github.com/mauryasagar/ai-file-organizer/blob/main/extractor.py): `extractor.py`
- [Local classification](https://github.com/mauryasagar/ai-file-organizer/blob/main/classifier.py): `classifier.py`

### File operations

- [Apply and undo moves](https://github.com/mauryasagar/ai-file-organizer/blob/main/organizer.py): `organizer.py`
- [Undo log](https://github.com/mauryasagar/ai-file-organizer/blob/main/organizer.py): `organizer.py`

### Other components

- **User**
- **Ollama / Gemma**
- **Chosen folder**

## Connections

- User → Streamlit workflow: selects folder (evidence: `README.md`)
- Streamlit workflow → Safe file scan: scans folder (evidence: `app.py`)
- Safe file scan → Chosen folder: lists files (evidence: `README.md`)
- Streamlit workflow → Text extraction: extracts text (evidence: `app.py`)
- Text extraction → Chosen folder: reads content (evidence: `README.md`)
- Streamlit workflow → Local classification: classifies files (evidence: `app.py`)
- Streamlit workflow → Category settings: loads categories
- Local classification → Ollama / Gemma: requests category (evidence: `classifier.py`)
- Ollama / Gemma → Local classification: returns reason (evidence: `classifier.py`)
- Streamlit workflow → Editable plan and preview: builds plan (evidence: `app.py`)
- User → Editable plan and preview: reviews and edits (evidence: `README.md`)
- User → Streamlit workflow: approves moves (evidence: `README.md`)
- Streamlit workflow → Apply and undo moves: applies plan (evidence: `app.py`)
- Apply and undo moves → Chosen folder: moves files (evidence: `organizer.py`)
- Apply and undo moves → Undo log: writes moves (evidence: `organizer.py`)
- User → Streamlit workflow: requests undo (evidence: `app.py`)
- Streamlit workflow → Apply and undo moves: calls undo (evidence: `app.py`)
- Apply and undo moves → Undo log: reads moves (evidence: `organizer.py`)
- Apply and undo moves → Chosen folder: restores files (evidence: `organizer.py`)
- Streamlit workflow → Run history: records run (evidence: `app.py`)
