# devthayron/download-organizer architecture

> Architecture diagram of the GitHub repository devthayron/download-organizer, 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/devthayron/download-organizer
- Repository: https://github.com/devthayron/download-organizer

## Overview

#### Purpose and principal workflow

This Python application organizes a user’s `Downloads` folder by file extension. The external caller is the user or an optional systemd service launching `python main.py`; startup loads configuration and sorts existing files, then Watchdog observes filesystem events. New or changed files are checked for stable size before being moved into a configured category or `Outros`.

#### Components

##### Application startup and monitoring
- **Command-line entry point** — `main.py`: Exposes `main()`, calls the watcher startup function, and exits with an error status if startup fails.
- **Download monitor and startup orchestration** — `monitor.py`: Loads JSON configuration, creates the organizer, processes existing downloads, configures Watchdog, handles filesystem events, and runs stability checks in background threads.
- **Watchdog observer library** — `requirements.txt`: Declares the Watchdog dependency used by the monitor to observe filesystem changes. The README documents systemd as an optional way to launch the application.

##### Organization and filesystem operations
- **Download organizer** — `organizador.py`: Validates rules, maps extensions to folders, ignores directories and selected files, creates category folders, avoids overwrites, and moves files using `shutil`.
- **Downloads folder and files** — null repository path: The user’s filesystem directory is the application’s input, monitored location, and destination for organized files.

##### Configuration and diagnostics
- **Organization configuration** — `config.json`: Holds the category rules, ignored extensions, and stability interval consumed by the monitor and organizer.
- **Logging setup** — `logger.py`: Configures console and file logging; the monitor invokes it during watcher startup.
- **User or systemd service** — null repository path: The external launcher starts the application; the README documents direct invocation and optional systemd operation.

#### Relationships

- **User or systemd service -> Command-line entry point**: launches `python main.py`; the README documents both direct execution and systemd `ExecStart`.
- **Command-line entry point -> Download monitor and startup orchestration**: calls `iniciar_watcher()`; `main.py` imports it from the monitor module.
- **Download monitor and startup orchestration -> Logging setup**: configures logging at startup; `iniciar_watcher()` calls `configurar_logger()`.
- **Download monitor and startup orchestration -> Organization configuration**: reads and parses the JSON configuration; `carregar_config()` opens the configured path.
- **Download monitor and startup orchestration -> Download organizer**: constructs the organizer with loaded rules and calls it to process existing files.
- **Download organizer -> Downloads folder and files**: reads directory entries and moves eligible files into category folders; the implementation uses `Path` and `shutil.move`.
- **Download monitor and startup orchestration -> Watchdog observer library**: registers the event handler on the Downloads path and starts the observer.
- **Watchdog observer library -> Download monitor and startup orchestration**: dispatches created, modified, and moved events to handler methods; the handler schedules stability checks.
- **Downloads folder and files -> Watchdog observer library**: supplies filesystem changes from the watched directory.
- **Download monitor and startup orchestration -> Downloads folder and files**: checks file existence and size over time, then asks the organizer to move a stable file.

#### Coverage limits

The source excerpts establish the main workflow and direct calls. They do not establish the contents of `config.json` or details of runtime behavior across platforms; systemd support is documented, not implemented in the sampled repository code.

Main entry points: [`monitor.py`](https://github.com/devthayron/download-organizer/blob/main/monitor.py) (Download monitor), [`main.py`](https://github.com/devthayron/download-organizer/blob/main/main.py) (CLI entry point), [`requirements.txt`](https://github.com/devthayron/download-organizer/blob/main/requirements.txt) (Watchdog observer), [`organizador.py`](https://github.com/devthayron/download-organizer/blob/main/organizador.py) (Download organizer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Startup and monitoring"]
  node_main["CLI entry point<br/>Python entry point"]
  node_monitor["Download monitor<br/>Watcher orchestration"]
  node_watchdog["Watchdog observer<br/>Filesystem event library"]
end

subgraph group_organization["File organization"]
  node_organizer["Download organizer<br/>File organization service"]
  node_downloads["Downloads folder<br/>Filesystem location"]
end

subgraph group_configuration["Configuration and diagnostics"]
  node_config["Organization config<br/>JSON configuration"]
  node_logger["Logging setup<br/>Logging configuration"]
end

node_user["User<br/>External actor"]
node_systemd["systemd service<br/>External launcher"]

node_user -->|"launches"| node_main
node_systemd -.->|"launches"| node_main
node_main -->|"starts watcher"| node_monitor
node_monitor -->|"configures logging"| node_logger
node_monitor -->|"loads rules"| node_config
node_monitor -->|"organizes files"| node_organizer
node_organizer -->|"moves files"| node_downloads
node_monitor -->|"starts observer"| node_watchdog
node_watchdog -->|"dispatches events"| node_monitor
node_downloads -->|"emits changes"| node_watchdog
node_monitor -->|"checks stability"| node_downloads

click node_main "https://github.com/devthayron/download-organizer/blob/main/main.py"
click node_monitor "https://github.com/devthayron/download-organizer/blob/main/monitor.py"
click node_watchdog "https://github.com/devthayron/download-organizer/blob/main/requirements.txt"
click node_organizer "https://github.com/devthayron/download-organizer/blob/main/organizador.py"
click node_config "https://github.com/devthayron/download-organizer/blob/main/config.json"
click node_logger "https://github.com/devthayron/download-organizer/blob/main/logger.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_main,node_monitor,node_watchdog,node_user toneBlue
class node_organizer,node_downloads toneAmber
class node_config,node_logger toneMint
class node_systemd toneIndigo
```

## Components

### Startup and monitoring

- [CLI entry point](https://github.com/devthayron/download-organizer/blob/main/main.py): Python entry point · `main.py`
- [Download monitor](https://github.com/devthayron/download-organizer/blob/main/monitor.py): Watcher orchestration · `monitor.py`
- [Watchdog observer](https://github.com/devthayron/download-organizer/blob/main/requirements.txt): Filesystem event library · `requirements.txt`

### File organization

- [Download organizer](https://github.com/devthayron/download-organizer/blob/main/organizador.py): File organization service · `organizador.py`
- **Downloads folder**: Filesystem location · User filesystem input, monitored location, and destination for organized files.

### Configuration and diagnostics

- [Organization config](https://github.com/devthayron/download-organizer/blob/main/config.json): JSON configuration · `config.json`
- [Logging setup](https://github.com/devthayron/download-organizer/blob/main/logger.py): Logging configuration · `logger.py`

### Other components

- **User**: External actor
- **systemd service**: External launcher · Optional launcher documented in the README.

## Connections

- User → CLI entry point: launches · Runs python main.py.
- systemd service → CLI entry point: launches · Optional systemd ExecStart.
- CLI entry point → Download monitor: starts watcher · Calls iniciar_watcher().
- Download monitor → Logging setup: configures logging · Calls configurar_logger() at startup.
- Download monitor → Organization config: loads rules · Reads and parses the JSON configuration.
- Download monitor → Download organizer: organizes files · Constructs the organizer with loaded rules and processes existing files.
- Download organizer → Downloads folder: moves files · Reads directory entries and moves eligible files into category folders.
- Download monitor → Watchdog observer: starts observer · Registers the event handler on the Downloads path.
- Watchdog observer → Download monitor: dispatches events · Created, modified, and moved events trigger stability checks.
- Downloads folder → Watchdog observer: emits changes · Filesystem changes from the watched directory.
- Download monitor → Downloads folder: checks stability · Checks file existence and size over time before requesting a move.