# simerusm/arceus architecture

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

- Interactive diagram: https://gitdiagram.com/simerusm/arceus
- Repository: https://github.com/simerusm/arceus

## Overview

##### Project type and purpose
- Arceus is a distributed deep-learning training framework with a full-stack architecture.
- Purpose: Orchestrate model-parallel neural‐network training across Apple M-series devices on a local network, and support single-machine transformer (GPT) training.

##### File structure
- Top-level directories:
- api/          → Flask REST API server for job registration, device registration, orchestration
- nn/           → Core Python modules: coordinator, device_client, device_server for distributed training
- protos/       → gRPC service definitions and generated stubs for device-to-server RPC
- gpt/          → Transformer model code and training pipeline
- frontend/     → Next.js + Tauri desktop UI for monitoring and job setup
- Configuration/build: requirements.txt, Cargo.toml (Tauri), next.config.mjs, postcss.config.mjs, tailwind.config.ts

##### README for additional insights
- REST endpoints under api/server.py for jobs, network initialization, and training
- Devices register themselves via HTTP, then orchestrator uses gRPC (device_service.proto) to push work
- Two training modes:
- Model-parallel across devices (requires device_client processes on each node)
- Transformer training (runs entirely within the Flask process + gpt/model.py)

a. Main components
- User interface (Next.js + Tauri app)
- REST API server (Flask app.py & server.py)
- Orchestrator / Scheduler (nn/coordinator.py)
- Device workers (nn/device_client.py + nn/device_server.py)
- gRPC layer (protos/device_service.proto)
- Data sources: local dataset files (e.g., MNIST), gpt/data.txt
- (Optional) In-memory job registry or future database
b. Relationships & interactions
1. User clicks “Create Job” in Frontend → HTTP POST to Flask REST API
2. API server stores job configuration and returns a job ID
3. Device workers call HTTP POST /api/devices/register to register with the server
4. Coordinator (invoked by REST endpoint) sends gRPC Initialize messages to each device’s gRPC server
5. For each training epoch, Coordinator invokes gRPC Train/Forward/Backward calls to devices in pipeline order
6. Devices compute segment forward/backward on MPS, return activations/gradients via gRPC
7. Coordinator aggregates results; REST API returns progress back to Frontend via polling or WebSocket (future enhancement)
8. For transformer jobs, API directly invokes gpt/model.py training loop (no gRPC)
c. Architectural patterns & design principles
- Separation of concerns: UI ←→ REST API ←→ Orchestrator ←→ Workers
- Micro-service style: independent device worker processes communicating over gRPC
- Model parallel pipeline: each layer segment deployed to a different device
- Pluggable training modes (add new model types by extending gpt/ or nn/)
d. Key technologies & frameworks
- Python 3, Flask (REST API)
- Protobuf + gRPC (device_service.proto)
- Apple MPS (device compute backend)
- Next.js + React + Tailwind CSS + Tauri (desktop UI)

##### Elements
- Clear, concise labels for each component (e.g., “Flask API Server”, “Device Worker (gRPC)” )

##### Detailed capture of essential architecture
- Don’t just list files—group by function: UI vs. API vs. Compute
- How protos tie into device_server & device_client
- Both training modes side-by-side, with shared and unique flows

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation Layer
    subgraph "Presentation Layer"
        UI["User"]:::external
        FE["Frontend (Next.js + Tauri)"]:::frontend
        FE -->|“Create Job”| UI
    end

    %% API Layer
    subgraph "API Layer"
        API["Flask REST API Server"]:::api
    end

    %% Orchestration Layer
    subgraph "Orchestration Layer"
        ORC["Coordinator / Scheduler"]:::orchestrator
    end

    %% Device Cluster
    subgraph "Device Cluster"
        DC1["Device Worker (gRPC Server)"]:::device
        DC2["Device Worker Client"]:::device
        PROTO["device_service.proto"]:::proto
        STUBS["gRPC Stubs"]:::proto
    end

    %% Transformer Pipeline
    subgraph "Transformer Training"
        GPT["gpt/model.py"]:::transformer
        DATA1["gpt/small.txt"]:::data
        DATA2["gpt/completions.txt"]:::data
        ROOT_DATA["completions.txt"]:::data
    end

    %% Data Store (Future)
    JOBSTORE["Job Store (In-Memory / Future DB)"]:::future

    %% Connections
    UI -->|uses| FE
    FE -->|HTTP POST /jobs| API
    API -->|invoke| ORC
    API -->|HTTP POST /devices/register| DC2
    ORC -->|gRPC Initialize/Train| DC1
    DC1 -->|gRPC responses| ORC
    ORC -->|aggregate| API
    API -->|polling/WebSocket progress| FE

    %% Transformer path
    FE -->|start transformer job| API
    API -->|invoke training loop| GPT
    GPT -->|read| DATA1
    GPT -->|read| DATA2
    GPT -->|read| ROOT_DATA
    GPT -->|progress| API

    %% Protos relations
    PROTO -->|generate| STUBS
    STUBS -->|used by| DC1
    STUBS -->|used by| ORC

    %% Click Events
    click FE "https://github.com/simerusm/arceus/tree/main/frontend/"
    click FE "https://github.com/simerusm/arceus/tree/main/frontend/app/"
    click FE "https://github.com/simerusm/arceus/tree/main/frontend/components/"
    click FE "https://github.com/simerusm/arceus/tree/main/frontend/lib/"
    click FE "https://github.com/simerusm/arceus/tree/main/frontend/src-tauri/"
    click API "https://github.com/simerusm/arceus/blob/main/api/app.py"
    click API "https://github.com/simerusm/arceus/blob/main/api/server.py"
    click ORC "https://github.com/simerusm/arceus/blob/main/nn/coordinator.py"
    click DC2 "https://github.com/simerusm/arceus/blob/main/nn/device_client.py"
    click DC1 "https://github.com/simerusm/arceus/blob/main/nn/device_server.py"
    click PROTO "https://github.com/simerusm/arceus/blob/main/protos/device_service.proto"
    click STUBS "https://github.com/simerusm/arceus/blob/main/protos/device_service_pb2.py"
    click STUBS "https://github.com/simerusm/arceus/blob/main/protos/device_service_pb2_grpc.py"
    click GPT "https://github.com/simerusm/arceus/blob/main/gpt/model.py"
    click DATA1 "https://github.com/simerusm/arceus/blob/main/gpt/small.txt"
    click DATA2 "https://github.com/simerusm/arceus/blob/main/gpt/completions.txt"
    click ROOT_DATA "https://github.com/simerusm/arceus/blob/main/completions.txt"
    click JOBSTORE "https://github.com/simerusm/arceus/blob/main/requirements.txt"

    %% Styles
    classDef external fill:#E3F2FD,stroke:#90CAF9,color:#0D47A1;
    classDef frontend fill:#BBDEFB,stroke:#2196F3,color:#0D47A1;
    classDef api fill:#C8E6C9,stroke:#4CAF50,color:#1B5E20;
    classDef orchestrator fill:#FFE0B2,stroke:#FB8C00,color:#E65100;
    classDef device fill:#ECEFF1,stroke:#90A4AE,color:#37474F;
    classDef proto fill:#D1C4E9,stroke:#7E57C2,color:#311B92;
    classDef transformer fill:#F3E5F5,stroke:#CE93D8,color:#4A148C;
    classDef data fill:#FFF9C4,stroke:#FDD835,color:#F57F17;
    classDef future stroke-dasharray: 5 5,fill:none,stroke:#9E9E9E,color:#616161
```
