# arjundivecha/mlx-finetune-gui architecture

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

- Interactive diagram: https://gitdiagram.com/arjundivecha/mlx-finetune-gui
- Repository: https://github.com/arjundivecha/mlx-finetune-gui

## Overview

##### Main Components
- Electron Main Process (src/main.ts, debug_electron.py)
- React Frontend (frontend/src with Redux, React Router, WebSocket client)
- FastAPI Backend (backend/main.py)
- MLX Training Subsystem (Training Manager invoking run_finetune.py in MLX venv)
- Adapter Fusion Module (adapter_fusion folder with Python scripts to merge LoRA adapters)
- File System (model directories, dataset JSONL, logs, lora_adapters output)
- External MLX Environment (venv path pointing to local_qwen/.venv)

##### Relationships & Data Flows
- Electron main starts both the React renderer and the FastAPI server (spawn + IPC)
- React communicates with FastAPI via REST (HTTP) for control operations and via WebSocket for live updates
- FastAPI’s Training Manager invokes MLX fine-tune commands in the external venv, monitors log files, and parses metrics
- Adapter Fusion routines can be triggered via backend endpoints or CLI tests to merge multiple LoRA adapters
- File dialogs and filesystem operations (model discovery, dataset selection, adapter outputs) use Electron IPC to access OS APIs
- Frontend stores session state in Redux and persists to disk via backend file-I/O

##### Architectural Patterns
- Full-Stack Desktop: Electron shell containing a single-page React frontend and embedded FastAPI backend
- MVC-Like Separation:
- View: React components/pages (Setup, Training, Results, Compare)
- Controller: FastAPI endpoints & WebSocket handlers
- Model: Redux store slices and Python Training Manager state
- Real‐Time WebSocket Pattern for push‐style training updates
- Modular Python utilities (adapter_fusion) decoupled from core backend but integrated via Python imports or CLI

##### Technologies & Frameworks
- Electron (Node.js + Chromium) for desktop packaging
- React + Redux Toolkit + React Router + Tailwind CSS + Chart.js in the renderer
- FastAPI + WebSockets + uvicorn for backend
- Python MLX framework (LoRA fine-tuning on Apple Silicon)
- Adapter Fusion using safetensors and custom Python scripts
- IPC channels for Electron ↔ backend and Electron ↔ filesystem dialogs

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Electron Main Process
    EM["Electron Main Process"]:::electron
    EP["Preload Script"]:::electron
    ED["Debug Launcher"]:::electron
    DB1["dist/main.js"]:::electron
    DB2["dist/preload.js"]:::electron

    EM -->|"spawn backend"| FB
    EM -->|"open renderer"| FE
    EM -->|"build output"| DB1
    EP -->|"build output"| DB2

    click EM "https://github.com/arjundivecha/mlx-finetune-gui/blob/main/src/main.ts"
    click EP "https://github.com/arjundivecha/mlx-finetune-gui/blob/main/src/preload.ts"
    click ED "https://github.com/arjundivecha/mlx-finetune-gui/blob/main/debug_electron.py"
    click DB1 "https://github.com/arjundivecha/mlx-finetune-gui/blob/main/dist/main.js"
    click DB2 "https://github.com/arjundivecha/mlx-finetune-gui/blob/main/dist/preload.js"

    %% Frontend Renderer
    subgraph "Frontend Renderer"
        FE["React UI (React + Redux)"]:::frontend
        RC["Components Cluster"]:::frontend
        RP["Pages Cluster"]:::frontend
        RS["Redux Store & Slices"]:::frontend
        WH["WebSocket Hook"]:::frontend
    end

    FE --> RC
    FE --> RP
    FE --> RS
    FE --> WH
    FE -->|"HTTP (GET/POST)"| FB
    FE -->|"WebSocket↔"| FB

    click FE "https://github.com/arjundivecha/mlx-finetune-gui/tree/main/frontend/src/"
    click RC "https://github.com/arjundivecha/mlx-finetune-gui/tree/main/frontend/src/components/"
    click RP "https://github.com/arjundivecha/mlx-finetune-gui/tree/main/frontend/src/pages/"
    click RS "https://github.com/arjundivecha/mlx-finetune-gui/tree/main/frontend/src/store/"
    click WH "https://github.com/arjundivecha/mlx-finetune-gui/blob/main/frontend/src/hooks/useWebSocket.ts"

    %% Backend Server
    subgraph "FastAPI Server"
        FB["FastAPI API"]:::backend
        BD["Dependencies Spec"]:::backend
        TM["Training Manager"]:::backend
    end

    FB --> BD
    FB --> TM

    click FB "https://github.com/arjundivecha/mlx-finetune-gui/blob/main/backend/main.py"
    click BD "https://github.com/arjundivecha/mlx-finetune-gui/blob/main/backend/requirements.txt"

    %% Python Modules
    subgraph "Python Modules"
        MT["MLX Training Subsystem"]:::python
        AF["Adapter Fusion Module"]:::python
        FA["Fusion Routines Script"]:::python
        FT1["Fusion Test Suite 1"]:::python
        FT2["Fusion Test Suite 2"]:::python
    end

    TM -->|"invoke subprocess"| MT
    TM -->|"trigger fusion"| AF
    AF --> FA
    AF --> FT1
    AF --> FT2

    click MT "https://github.com/arjundivecha/mlx-finetune-gui/blob/main/monitor_training.py"
    click AF "https://github.com/arjundivecha/mlx-finetune-gui/tree/main/adapter_fusion/"
    click FA "https://github.com/arjundivecha/mlx-finetune-gui/blob/main/adapter_fusion/fusion_adapters.py"
    click FT1 "https://github.com/arjundivecha/mlx-finetune-gui/blob/main/adapter_fusion/test_fusion.py"
    click FT2 "https://github.com/arjundivecha/mlx-finetune-gui/blob/main/adapter_fusion/test_fused_models.py"

    %% External MLX Environment
    EX["MLX venv (local_qwen/.venv)"]:::external
    MT -->|"runs in"| EX

    %% File System Storage
    subgraph "File System"
        MD["models/ directory"]:::storage
        DS["dataset.jsonl"]:::storage
        LG["logs/ directory"]:::storage
        LA["lora_adapters/ output"]:::storage
    end

    EM -->|"IPC filesystem"| MD
    EM -->|"IPC filesystem"| DS
    MT -->|"write logs"| LG
    MT -->|"read models"| MD
    MT -->|"write adapters"| LA
    AF -->|"write adapters"| LA

    %% Styles
    classDef electron fill:#D6EAF8,stroke:#1B4F72,color:#1B2631;
    classDef frontend fill:#D5F5E3,stroke:#145A32,color:#0B5345;
    classDef backend fill:#FAD7A0,stroke:#B9770E,color:#7E5109;
    classDef python fill:#E8DAEF,stroke:#6C3483,color:#4A235A;
    classDef storage fill:#F2F3F4,stroke:#7B7D7D,color:#424949;
    classDef external fill:#FDEBD0,stroke:#B9770E,color:#6E2C00;
```
