# kli447/cs-598-fal-project architecture

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

- Interactive diagram: https://gitdiagram.com/kli447/cs-598-fal-project
- Repository: https://github.com/kli447/cs-598-fal-project

## Overview

##### Project Type and Purpose
- mLoRA is a machine learning fine-tuning framework. Its primary goal is to enable fast, concurrent training of multiple LoRA adapters over a shared base LLM.
- The framework supports various LoRA variants (QLoRA, LoRA+, VeRA, DoRA) as well as reinforcement learning alignment (DPO, CPO, CIT). It also includes an end-to-end training pipeline and service deployment capabilities.
- The presence of Dockerfiles, a CLI client (mlora_cli), server components (mlora/server), and multiple training scripts (mlora_train.py, mlora_pp_train.py) indicates the system has both standalone training components and service-oriented deployment options.

##### File Structure to Determine Architectural Components
- Top-Level Components:
- .github: Contains CI/CD workflows for code testing, formatting, and publishing.
- docs: Contains design documents and developer guides (e.g., design.md, develop_new_adapter.md) which can be referenced for internal module interactions.
- demo: Provides example configuration (YAML files) for various LoRA cases, reinforcement algorithms, and pipeline parallelism setups.
- mlora: This core piece is organized into submodules:
▸ backends (cpu, cuda, mps) – for hardware-abstracted computational backends.
▸ config – for configuration schema for adapters, tasks, and learning rate scheduling.
▸ executor – divided into context (for different training/inference scenarios), dispatcher (for task distribution including pipeline and backend dispatchers), pipeline modules (for message and transport among processing units), and actual task definitions.
▸ model – for managing model components, checkpoints, module definitions (adapter, attention, embedding, etc.), and tokenization.
▸ profiler – for performance metrics and tracing train/inference operations.
▸ prompter – for generating prompts from templates/data.
▸ server – which handles service deployment (adapter management, dataset management, file operations, task submission, etc.).
▸ utils – helper functions and command-line utilities.
- Additional modules such as mlora_cli, mlora_client.py, and multiple training entry scripts indicate interfaces for both manual and distributed training.

##### Key Architectural Patterns and Relationships
- Separation of Concerns: The source tree clearly separates configuration, execution, model loading, backend operations, and service interaction.
- Modular Executor Design: The executor is split into contexts (for training, inference, adapter-specific operations) and dispatchers (tasks are distributed based on hardware capabilities and pipeline parallelism).
- Client/Server Interaction: The existence of a dedicated CLI (mlora_cli) and server module (mlora/server) suggests that task submission and management are handled through a REST-like interface, supporting remote or even multi-node deployment.
- Pipeline Parallelism: With dedicated scripts (mlora_pp_train.py) and executor modules for pipeline communication, the system is designed to partition model layers or tasks across devices/nodes.
- Deployment Flexibility: Dockerfile and deployment scripts indicate that the system can be containerized, supporting both batch fine-tuning and continuous service operations.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core Modules
    subgraph "Core Modules"
        BaseModel["Base Model Repository"]:::training
        LoRAAdapter["LoRA Adapter Factory"]:::training
        Configuration["Configuration Modules"]:::config
        Hardware["Hardware Abstraction Layer"]:::training
        Prompter["Prompter and Data Pipeline"]:::training
    end

    %% Executor Components
    subgraph "Training Pipeline Components"
        ExecutorCore["Executor Core"]:::training
        Context["Context Submodules"]:::training
        Dispatcher["Dispatcher Submodules"]:::training
        PipelineCom["Pipeline Communication"]:::training
        RLAlignment["Reinforcement Learning Alignment Modules"]:::training
    end

    %% Service Deployment
    subgraph "Service Deployment"
        Server["Server Module"]:::client
        CLI["CLI Client"]:::client
    end

    %% Deployment & CI/CD
    subgraph "Deployment & CI/CD"
        Docker["Dockerfile"]:::external
        CI_CD["CI/CD Workflows"]:::external
    end

    %% Connections between Core Modules and Executor
    Configuration -->|"init_config"| Prompter
    Configuration -->|"init_config"| ExecutorCore
    Prompter -->|"task_creation"| ExecutorCore

    %% Executor internal connections
    ExecutorCore -->|"init_context"| Context
    ExecutorCore -->|"dispatch_tasks"| Dispatcher
    Dispatcher -->|"RPC_transport"| PipelineCom
    ExecutorCore -->|"trigger_RL"| RLAlignment
    ExecutorCore -->|"model_loading"| BaseModel
    ExecutorCore -->|"dispatch_to"| Hardware

    %% LoRA Adapter integration
    LoRAAdapter -->|"adapter_setup"| BaseModel

    %% Service Deployment interactions
    CLI -->|"REST_API"| Server
    Server -->|"model_management"| BaseModel

    %% Deployment & CI/CD influence on Service and Executor
    Docker -->|"containerized"| Server
    Docker -->|"containerized"| ExecutorCore
    CI_CD -->|"automated_builds"| Server

    %% Class definitions
    classDef training fill:#cfe2f3,stroke:#0b5394,stroke-width:2px;
    classDef config fill:#d9ead3,stroke:#38761d,stroke-width:2px;
    classDef client fill:#f9cb9c,stroke:#b45f06,stroke-width:2px;
    classDef external fill:#ead1dc,stroke:#741b47,stroke-width:2px;

    %% Click Events
    click BaseModel "https://github.com/kli447/cs-598-fal-project/blob/main/mlora/model/llm/model_llama.py"
    click LoRAAdapter "https://github.com/kli447/cs-598-fal-project/blob/main/mlora/config/adapter.py"
    click Configuration "https://github.com/kli447/cs-598-fal-project/tree/main/mlora/config/"
    click Prompter "https://github.com/kli447/cs-598-fal-project/tree/main/mlora/prompter/"
    click Hardware "https://github.com/kli447/cs-598-fal-project/tree/main/mlora/backends/"
    click ExecutorCore "https://github.com/kli447/cs-598-fal-project/blob/main/mlora/executor/executor.py"
    click Context "https://github.com/kli447/cs-598-fal-project/tree/main/mlora/executor/context/"
    click Dispatcher "https://github.com/kli447/cs-598-fal-project/tree/main/mlora/executor/dispatcher/"
    click PipelineCom "https://github.com/kli447/cs-598-fal-project/tree/main/mlora/executor/pipeline/"
    click RLAlignment "https://github.com/kli447/cs-598-fal-project/tree/main/mlora/executor/task/"
    click Server "https://github.com/kli447/cs-598-fal-project/tree/main/mlora/server/"
    click CLI "https://github.com/kli447/cs-598-fal-project/tree/main/mlora_cli/"
    click Docker "https://github.com/kli447/cs-598-fal-project/tree/main/Dockerfile"
    click CI_CD "https://github.com/kli447/cs-598-fal-project/tree/main/.github/workflows/"
```
