# xevila/openmcx architecture

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

- Interactive diagram: https://gitdiagram.com/xevila/openmcx
- Repository: https://github.com/xevila/openmcx

## Overview

##### Main Components
- User Interface (GUI)
– PyQt6-based windows and file‐selection dialogs
– Widgets for model, labels, input folder, output folder, progress bar, results list
- Classification Engine (Background Thread)
– ClassificationThread class
– Loads the ML model via TensorFlow or TFLite runtime
– Uses NumPy + Pillow to preprocess images
– Runs inference and returns class indices
- File System Manager
– Scans input folder (up to 50 images)
– Reads/writes image files, creates per‐class subfolders in output directory
– Persists last‐used paths (e.g., via QSettings or a small config file)
- Model & Labels
– External `.h5`, `.tflite` or `.pb` file
– `.txt` label file mapping indices to class names

##### Relationships & Data Flow
a. User → UI: user selects model file, label file, input/output folders
b. UI → ClassificationThread: once “Start” is clicked, the UI spawns the thread
c. ClassificationThread → File System Manager:
- Reads images via Pillow/NumPy
- For each image: run inference, get class index, map to label
- Write or move image into the appropriate output subfolder
- Emit progress and individual‐result signals back to UI
d. ClassificationThread → UI: emits signals to update progress bar and results list
e. UI → Persistent Storage: saves last‐used paths on exit or after file selection

##### Architectural Patterns & Principles
- Event‐Driven / Asynchronous: GUI remains responsive by delegating compute to a worker thread
- MVC‐Lite:
– View: PyQt6 widgets
– Controller: main.py logic wiring UI events to worker thread
– Model: ML model + image data
- Single‐Process Desktop App: all components live in one process but logically separated

##### Technologies
– PyQt6 for GUI
– TensorFlow or TFLite Runtime for inference
– NumPy + Pillow for image preprocessing
– Python 3.7+ runtime
– QSettings or local config for path persistence

##### Detail Without Overthinking
– Capture each technology (PyQt6, TensorFlow, NumPy, Pillow) next to its component.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User and External Artifacts
    User["User"]:::external
    ModelFile[".h5/.tflite/.pb Model File"]:::external
    LabelFile[".txt Label File"]:::external
    InputFolder["Input Folder"]:::external
    OutputFolder["Output Folder"]:::external

    %% UI Layer
    subgraph "User Interface Layer"
        PyQtGUI["PyQt6 GUI"]:::ui
        ProgressBar["Progress Bar Widget"]:::ui
        ResultList["Results List Widget"]:::ui
    end

    %% Classification Engine
    subgraph "Classification Engine"
        ClassThread["ClassificationThread"]:::backend
        TFModel["TensorFlow/TFLite Model"]:::external
    end

    %% File System Manager
    subgraph "File System Manager"
        FSManager["File System Manager"]:::fs
    end

    %% Persistent Storage
    Persist["Persistent Paths (QSettings)"]:::fs

    %% Connections
    User -->|"select Model File"| ModelFile
    User -->|"select Label File"| LabelFile
    User -->|"select Input Folder"| InputFolder
    User -->|"select Output Folder"| OutputFolder
    User -->|"interact"| PyQtGUI

    PyQtGUI -->|"start thread"| ClassThread
    PyQtGUI -->|"update progress"| ProgressBar
    ClassThread -.->|"emit signal"| ResultList
    ClassThread -->|"load model"| TFModel
    ClassThread -->|"read from"| InputFolder
    ClassThread -->|"write to"| OutputFolder
    ClassThread -->|"invoke FS Manager"| FSManager
    ClassThread -->|"map index → label"| LabelFile
    PyQtGUI -->|"save paths"| Persist

    FSManager -->|"scan (max 50)"| InputFolder
    FSManager -->|"create subfolders"| OutputFolder

    %% Click Events
    click PyQtGUI "https://github.com/xevila/openmcx/blob/main/main.py"
    click ClassThread "https://github.com/xevila/openmcx/blob/main/main.py"
    click FSManager "https://github.com/xevila/openmcx/blob/main/main.py"
    click Persist "https://github.com/xevila/openmcx/blob/main/main.py"

    %% Styles
    classDef ui fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef backend fill:#90EE90,stroke:#000,stroke-width:1px
    classDef fs fill:#FFFFE0,stroke:#000,stroke-width:1px
    classDef external fill:#D3D3D3,stroke:#000,stroke-width:1px
```
