# migoxlab/lmeterx architecture

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

- Interactive diagram: https://gitdiagram.com/migoxlab/lmeterx
- Repository: https://github.com/migoxlab/lmeterx

## Overview

##### Project type and purpose
- LMeterX is a full-stack, microservices-based performance testing platform for large language models.
- It provides a React/TypeScript web UI, a FastAPI backend, a Locust-based load-testing engine, and a MySQL database.
- Users create test tasks via the UI; the system runs high-concurrency requests against LLM inference endpoints (self-hosted frameworks or cloud APIs) and stores results for analysis.

##### File structure
Top-level:
- docker-compose.yml / docker-compose.dev.yml / quick-start.sh – compose scripts for orchestration.
- mysql/ – custom MySQL Dockerfile.
- init_db.sql – initial schema.
- backend/ – FastAPI service:
- api/ – route handlers (task, upload, analysis, logs, system)
- service/ – business logic
- db/ – SQLAlchemy setup and raw SQL
- middleware/, utils/, model/, tests/
- st_engine/ – load-testing engine service:
- engine/ – core Locust extensions, runner, processor, monitor
- service/ – task poller & result service
- db/ – database client (same MySQL)
- config/, utils/, data/ (prompts, datasets), tests/
- frontend/ – React + TypeScript + Ant Design UI:
- src/api – HTTP client & service definitions
- src/pages, components, hooks, utils, contexts, i18n
- Dockerfile, nginx.conf, env files for deployment

##### README for architecture insights
- Called out 4 core components:
1. Frontend Interface (React)
2. Backend Service (FastAPI + SQLAlchemy)
3. Load Testing Engine (Locust + custom extensions)
4. MySQL Database
- Mentions reverse proxy (Nginx) and external dependencies (LLM inference frameworks and cloud APIs).

- Web UI (Frontend)
- API Gateway / Reverse Proxy (Nginx)
- Backend Service (FastAPI)
- Load Testing Engine (st_engine)
- MySQL Database
- External LLM Inference Services (self-hosted frameworks & cloud providers)
1. User → Browser → HTTP(S) → Nginx → Frontend (Static files)
2. Frontend → HTTP(S) → Nginx → Backend API (task creation, status, logs, results)
3. Backend ↔ MySQL (read/write task metadata, mapping configurations, logs)
4. st_engine polls Backend API or directly reads DB for pending tasks → schedules Locust workers
5. Locust workers → HTTP(S) → External LLM endpoints → collect latency/throughput data
6. st_engine writes results back to MySQL (via its DB client) or calls Backend API to store results
7. Frontend fetches live logs & final reports from Backend API
c. Architectural patterns & design principles:
- Microservices: backend and engine are separate services, independently scalable.
- Clean layering in each service: API → Service → Model → DB
- Event-driven or poller pattern: st_engine polls for tasks, processes, then updates results.
- Infrastructure as code: Dockerfiles for each service, Docker Compose for orchestration, Kubernetes manifests optional.
d. Key technologies & frameworks:
- Frontend: React, TypeScript, Ant Design, Vite, i18n
- Backend: Python, FastAPI, SQLAlchemy, Pydantic, MySQL
- Engine: Python, Locust, multiprocess support, custom Locust runner/monitor
- Deployment: Docker, Docker Compose, Nginx, optional Kubernetes

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User and Entry
    User["User"]:::external
    Browser["Browser"]:::external

    %% Reverse Proxy
    subgraph "API Gateway / Reverse Proxy" 
        direction TB
        Nginx["Nginx Proxy"]:::proxy
    end

    %% Frontend Layer
    subgraph "Frontend Interface (React)" 
        direction TB
        FrontendDir["frontend/"]:::frontend
        FrontendSrc["src/"]:::frontend
        ReactApp["React App"]:::frontend
        StaticAssets["static files"]:::document
        FrontendDir --> FrontendSrc
        FrontendDir --> StaticAssets
    end

    %% Backend Service Layer
    subgraph "Backend Service (FastAPI)" 
        direction TB
        BackendDir["backend/"]:::api
        AppEntry["app.py"]:::api
        ApiLayer["api/"]:::api
        ServiceLayer["service/"]:::api
        DbLayer["db/"]:::database
        ModelLayer["model/"]:::api
        MiddlewareLayer["middleware/"]:::api
        UtilsLayer["utils/"]:::api
        BackendDir --> AppEntry
        BackendDir --> ApiLayer
        BackendDir --> ServiceLayer
        BackendDir --> DbLayer
        BackendDir --> ModelLayer
        BackendDir --> MiddlewareLayer
        BackendDir --> UtilsLayer
    end

    %% Load Testing Engine Layer
    subgraph "Load Testing Engine (st_engine)" 
        direction TB
        EngineDir["st_engine/"]:::engine
        EngineEntry["app.py"]:::engine
        EngineCore["engine/"]:::engine
        EngineService["service/"]:::engine
        EngineDb["db/"]:::database
        EngineConfig["config/"]:::engine
        EngineData["data/"]:::engine
        EngineUtils["utils/"]:::engine
        EngineDir --> EngineEntry
        EngineDir --> EngineCore
        EngineDir --> EngineService
        EngineDir --> EngineDb
        EngineDir --> EngineConfig
        EngineDir --> EngineData
        EngineDir --> EngineUtils
    end

    %% Database Layer
    subgraph "MySQL Database" 
        direction TB
        MysqlDir["mysql/"]:::database
        InitRoot["init_db.sql"]:::database
        BackendInit["backend/db/init_db.sql"]:::database
        MysqlDir --> InitRoot
        MysqlDir --> BackendInit
        MySQL["MySQL"]:::database
    end

    %% External Services
    subgraph "External LLM Inference Services" 
        direction TB
        LLMCloud["Cloud APIs"]:::external
        LLMSelf["Self-hosted LLM"]:::external
    end

    %% Orchestration
    DockerCompose["Docker Compose"]:::infra

    %% Connections
    User --> Browser
    Browser -->|"HTTP(S)"| Nginx
    Nginx -->|"serves static"| StaticAssets
    Nginx -->|"serves UI"| ReactApp
    ReactApp -->|"API calls"| Nginx
    Nginx -->|"proxies to API"| AppEntry
    AppEntry --> ApiLayer
    ApiLayer --> ServiceLayer
    ServiceLayer --> DbLayer
    ServiceLayer --> ModelLayer
    ApiLayer --> MiddlewareLayer
    ServiceLayer --> UtilsLayer
    DbLayer --> MySQL
    EngineService --> AppEntry
    EngineService --> MysqlDir
    EngineCore --> LLMCloud
    EngineCore --> LLMSelf
    EngineService --> MySQL
    ReactApp -->|"fetch logs/results"| AppEntry

    %% Orchestration edges
    DockerCompose --> Nginx
    DockerCompose --> FrontendDir
    DockerCompose --> BackendDir
    DockerCompose --> EngineDir
    DockerCompose --> MysqlDir

    %% Click Events
    click FrontendDir "https://github.com/migoxlab/lmeterx/tree/main/frontend/"
    click FrontendSrc "https://github.com/migoxlab/lmeterx/tree/main/frontend/src/"
    click ReactApp "https://github.com/migoxlab/lmeterx/blob/main/frontend/src/App.tsx"
    click StaticAssets "https://github.com/migoxlab/lmeterx/tree/main/frontend/public/"
    click FrontendDocker "https://github.com/migoxlab/lmeterx/tree/main/frontend/Dockerfile"
    click FrontendNginx "https://github.com/migoxlab/lmeterx/blob/main/frontend/nginx.conf"
    click BackendDir "https://github.com/migoxlab/lmeterx/tree/main/backend/"
    click AppEntry "https://github.com/migoxlab/lmeterx/blob/main/backend/app.py"
    click ApiLayer "https://github.com/migoxlab/lmeterx/tree/main/backend/api/"
    click ServiceLayer "https://github.com/migoxlab/lmeterx/tree/main/backend/service/"
    click DbLayer "https://github.com/migoxlab/lmeterx/tree/main/backend/db/"
    click ModelLayer "https://github.com/migoxlab/lmeterx/tree/main/backend/model/"
    click MiddlewareLayer "https://github.com/migoxlab/lmeterx/tree/main/backend/middleware/"
    click UtilsLayer "https://github.com/migoxlab/lmeterx/tree/main/backend/utils/"
    click BackendDocker "https://github.com/migoxlab/lmeterx/tree/main/backend/Dockerfile"
    click EngineDir "https://github.com/migoxlab/lmeterx/tree/main/st_engine/"
    click EngineEntry "https://github.com/migoxlab/lmeterx/blob/main/st_engine/app.py"
    click EngineCore "https://github.com/migoxlab/lmeterx/tree/main/st_engine/engine/"
    click EngineService "https://github.com/migoxlab/lmeterx/tree/main/st_engine/service/"
    click EngineDb "https://github.com/migoxlab/lmeterx/tree/main/st_engine/db/"
    click EngineConfig "https://github.com/migoxlab/lmeterx/tree/main/st_engine/config/"
    click EngineData "https://github.com/migoxlab/lmeterx/tree/main/st_engine/data/"
    click EngineUtils "https://github.com/migoxlab/lmeterx/tree/main/st_engine/utils/"
    click EngineDocker "https://github.com/migoxlab/lmeterx/tree/main/st_engine/Dockerfile"
    click MysqlDir "https://github.com/migoxlab/lmeterx/tree/main/mysql/"
    click InitRoot "https://github.com/migoxlab/lmeterx/blob/main/init_db.sql"
    click BackendInit "https://github.com/migoxlab/lmeterx/blob/main/backend/db/init_db.sql"
    click ComposeFile "https://github.com/migoxlab/lmeterx/blob/main/docker-compose.yml"
    click ComposeDev "https://github.com/migoxlab/lmeterx/blob/main/docker-compose.dev.yml"
    click QuickStart "https://github.com/migoxlab/lmeterx/blob/main/quick-start.sh"

    %% Styles
    classDef frontend fill:#E3F2FD,stroke:#90CAF9,color:#0D47A1;
    classDef api fill:#E8F5E9,stroke:#66BB6A,color:#1B5E20;
    classDef engine fill:#FFF3E0,stroke:#FFA726,color:#E65100;
    classDef database fill:#F3E5F5,stroke:#BA68C8,color:#4A148C;
    classDef external fill:#ECEFF1,stroke:#90A4AE,color:#37474F;
    classDef proxy fill:#E0F7FA,stroke:#4DD0E1,color:#006064;
    classDef document fill:#BBDEFB,stroke:#64B5F6,color:#0D47A1;
    classDef infra fill:#ECEFF1,stroke:#B0BEC5,color:#263238;
```
