# debbuk/smart-file-organizer architecture

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

- Interactive diagram: https://gitdiagram.com/debbuk/smart-file-organizer
- Repository: https://github.com/debbuk/smart-file-organizer

## Overview

Smart File Organizer is a small CLI for sorting files into extension-based category folders. The user supplies a directory and options; the CLI calls the organizer to scan files, categorize them, and either preview or move them, then prints a report and optionally exports JSON. The README documents recursive scanning, hidden-file handling, ten categories, dry-run, and JSON reporting. The source excerpts show the CLI-to-organizer call and filesystem operations; reporting and export are implemented in the CLI.

Main entry points: [`smart_file_organizer/cli.py`](https://github.com/debbuk/smart-file-organizer/blob/main/smart_file_organizer/cli.py) (CLI entry point), [`smart_file_organizer/organizer.py`](https://github.com/debbuk/smart-file-organizer/blob/main/smart_file_organizer/organizer.py) (Scan and organize)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_command["CLI"]
  node_cli["CLI entry point<br/>[cli.py]"]
end

subgraph group_organization["Organization"]
  node_planner["Scan and organize<br/>[organizer.py]"]
  node_categorizer["Extension categories<br/>[organizer.py]"]
end

subgraph group_reporting["Reporting"]
  node_console_report["Console report<br/>[cli.py]"]
  node_json_export["JSON export<br/>[cli.py]"]
end

node_user(("User"))
node_filesystem["Local filesystem"]

node_user -->|"runs command"| node_cli
node_cli -->|"calls planner"| node_planner
node_planner -->|"scans and moves"| node_filesystem
node_planner -->|"classifies files"| node_categorizer
node_planner -->|"returns result"| node_cli
node_cli -->|"prints report"| node_console_report
node_cli -->|"exports report"| node_json_export
node_json_export -->|"writes JSON"| node_filesystem

click node_cli "https://github.com/debbuk/smart-file-organizer/blob/main/smart_file_organizer/cli.py"
click node_planner "https://github.com/debbuk/smart-file-organizer/blob/main/smart_file_organizer/organizer.py"
click node_categorizer "https://github.com/debbuk/smart-file-organizer/blob/main/smart_file_organizer/organizer.py"
click node_console_report "https://github.com/debbuk/smart-file-organizer/blob/main/smart_file_organizer/cli.py"
click node_json_export "https://github.com/debbuk/smart-file-organizer/blob/main/smart_file_organizer/cli.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_cli,node_user toneBlue
class node_planner,node_categorizer toneAmber
class node_console_report,node_json_export toneMint
class node_filesystem toneIndigo
```

## Components

### CLI

- [CLI entry point](https://github.com/debbuk/smart-file-organizer/blob/main/smart_file_organizer/cli.py): `smart_file_organizer/cli.py`

### Organization

- [Scan and organize](https://github.com/debbuk/smart-file-organizer/blob/main/smart_file_organizer/organizer.py): `smart_file_organizer/organizer.py`
- [Extension categories](https://github.com/debbuk/smart-file-organizer/blob/main/smart_file_organizer/organizer.py): `smart_file_organizer/organizer.py`

### Reporting

- [Console report](https://github.com/debbuk/smart-file-organizer/blob/main/smart_file_organizer/cli.py): `smart_file_organizer/cli.py`
- [JSON export](https://github.com/debbuk/smart-file-organizer/blob/main/smart_file_organizer/cli.py): `smart_file_organizer/cli.py`

### Other components

- **User**
- **Local filesystem**

## Connections

- User → CLI entry point: runs command (evidence: `README.md`)
- CLI entry point → Scan and organize: calls planner (evidence: `smart_file_organizer/cli.py`)
- Scan and organize → Local filesystem: scans and moves (evidence: `smart_file_organizer/organizer.py`)
- Scan and organize → Extension categories: classifies files (evidence: `smart_file_organizer/organizer.py`)
- Scan and organize → CLI entry point: returns result (evidence: `smart_file_organizer/cli.py`)
- CLI entry point → Console report: prints report (evidence: `smart_file_organizer/cli.py`)
- CLI entry point → JSON export: exports report (evidence: `smart_file_organizer/cli.py`)
- JSON export → Local filesystem: writes JSON (evidence: `smart_file_organizer/cli.py`)
