# qiuyannnn/local-file-organizer architecture

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

- Interactive diagram: https://gitdiagram.com/qiuyannnn/local-file-organizer
- Repository: https://github.com/qiuyannnn/local-file-organizer

## Overview

##### Project type and purpose
- This is an open-source, local CLI tool (“Local File Organizer”) written in Python.
- Purpose: scan a user-specified directory, analyze file contents (text and images) via on-device AI (Nexa SDK LLM and VLM models), generate metadata (folder names, filenames), and reorganize files into a new directory tree—all without sending data off-device.

##### File structure
Top level:
- main.py              ← CLI entry point / orchestrator
- data_processing_common.py ← shared helper functions (prompt templates, metadata structures)
- text_data_processing.py   ← handles text/document analysis via NexaTextInference
- image_data_processing.py  ← handles image analysis via NexaVLMInference
- file_utils.py         ← scanning folders, creating target dirs, moving/renaming files
- output_filter.py      ← optional post-processing or log filtering
- requirements.txt      ← Python dependencies (nexaai, Pillow, pytesseract, PyMuPDF, python-docx, etc.)
- sample_data/…         ← example inputs
- license & README      ← metadata and usage

##### README for additional insights
- Processing pipeline stages described (“Scanning input directory → Content Understanding → Organize into new structure”).
- Three sorting modes (content, date, type), dry-run & silent modes, real-time progress bar, multiprocessing for performance.
- Relies on external native deps: Tesseract OCR, PyMuPDF.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core Modules
    CLI["CLI Interface / Orchestrator"]:::core
    FileScanner["File Scanner & Manager"]:::core
    subgraph "Processing Pipeline"
        SharedUtils["Shared Data & Prompt Utilities"]:::core
        TextProc["Text Processor Module"]:::ai
        ImageProc["Image Processor Module"]:::ai
    end
    OutputFilter["Output Filter & Logger"]:::core

    %% File System
    subgraph "Local File System"
        SampleData["(Sample Input Data)"]:::fs
        OutputDir["(Organized Output Dir)"]:::fs
    end

    %% External Dependencies
    subgraph "External & Native Dependencies"
        NexaSDK["Nexa SDK (LLM & VLM)"]:::extdep
        Tesseract["Tesseract OCR"]:::extdep
        PyMuPDF["PyMuPDF"]:::extdep
        PythonDocx["python-docx, Pillow"]:::extdep
    end

    %% Flow
    SampleData -->|reads files| CLI
    CLI -->|invokes scan| FileScanner
    FileScanner -->|"file list"| TextProc
    FileScanner -->|"file list"| ImageProc
    TextProc -->|metadata| SharedUtils
    ImageProc -->|metadata| SharedUtils
    SharedUtils -->|enrich metadata| OutputFilter
    OutputFilter -->|filtered metadata| FileScanner
    FileScanner -->|move/rename| OutputDir
    OutputFilter -->|logs/progress| CLI

    %% Click Events
    click CLI "https://github.com/qiuyannnn/local-file-organizer/blob/main/main.py"
    click FileScanner "https://github.com/qiuyannnn/local-file-organizer/blob/main/file_utils.py"
    click SharedUtils "https://github.com/qiuyannnn/local-file-organizer/blob/main/data_processing_common.py"
    click TextProc "https://github.com/qiuyannnn/local-file-organizer/blob/main/text_data_processing.py"
    click ImageProc "https://github.com/qiuyannnn/local-file-organizer/blob/main/image_data_processing.py"
    click OutputFilter "https://github.com/qiuyannnn/local-file-organizer/blob/main/output_filter.py"
    click SampleData "https://github.com/qiuyannnn/local-file-organizer/tree/main/sample_data/"
    click Requirements "https://github.com/qiuyannnn/local-file-organizer/blob/main/requirements.txt"
    click Readme "https://github.com/qiuyannnn/local-file-organizer/blob/main/README.md"
    click License "https://github.com/qiuyannnn/local-file-organizer/tree/main/LICENSE"

    %% Documentation and Config
    Requirements["requirements.txt"]:::doc
    Readme["README.md"]:::doc
    License["LICENSE"]:::doc

    %% Styles
    classDef core fill:#D0E1F9,stroke:#000,stroke-width:1px
    classDef ai fill:#D9F2D9,stroke:#000,stroke-width:1px
    classDef extdep fill:#F9E0D0,stroke:#000,stroke-width:1px
    classDef fs fill:#E0E0E0,stroke:#000,stroke-width:1px
    classDef doc fill:#FFF2CC,stroke:#000,stroke-width:1px
```
