# moxin-org/moly architecture

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

- Interactive diagram: https://gitdiagram.com/moxin-org/moly
- Repository: https://github.com/moxin-org/moly

## Overview

##### Project type and purpose
- Moly is a full‑stack, multi‑platform desktop application (built in Rust) that serves as an AI LLM client.
- It uses the Makepad UI toolkit for rendering the user interface, Robius to manage multi‑platform WASM execution, and communicates with LLM backends via WebAssembly (WASM) modules and/or an external MoFa server.

##### File structure
- Root
- Cargo.toml / workspace — defines multiple Rust crates.
- .github/workflows — CI build and release pipelines.
- build.sh, packaging/ — scripts and configuration for packaging into .app, .dmg, .deb, AppImage, .exe, etc.
- src/ — the front‑end desktop client built with Makepad. Contains:
- main.rs, app.rs — application entry and initialization.
- chat/, landing/, my_models/, settings/, shared/ — UI modules for different screens and shared components.
- data/ — local storage modules (chats, downloads, preferences) abstracting file system and remote model download.
- moly-protocol/ — shared data types and RPC/message schemas (chat messages, model descriptors, OpenAI protocol compliance).
- moly-backend/ — orchestrator crate that loads and executes backend WASM modules via WasmEdge:
- backend_impls/ — implementations for api_server.wasm and chat_ui.wasm.
- store/ — local model store: downloads, metadata, remote fetch.
- wasm/ — precompiled WASM binaries (chat_ui.wasm, llama-api-server.wasm).
- moly-fake-backend/ — a fake MoFa‑compatible HTTP server (for local development without a real MoFa server).
- moly-mofa/ — integration utilities to communicate with a real MoFa server via HTTP/dora.
- moly-runner/ — CLI helper to install WasmEdge, set environment, and forward any cargo command.
- packaging/ — initial template for build‑and‑packaging commands.

##### Extract insights from the README
- Describes multi‑platform building (macOS, Linux, Windows) via WasmEdge and cargo-packager.
- Explains how to connect to a MoFa server or use a fake backend.
- Emphasizes modular architecture: front‑end, protocol, back‑end WASM modules, external services.

##### Main components
a. Frontend (Makepad UI)
- src/main.rs → app.rs → UI modules (chat screen, landing page, settings).
- Local Data Layer (data/*): file system, preferences, cached models.
- Uses moly-protocol types to marshal/unmarshal requests and responses.
b. Wasm runtime (WasmEdge)
- Hosted by moly-backend crate.
- Loads two primary WASM modules:
- chat_ui.wasm — processes UI‑side logic in a sandbox.
- llama-api-server.wasm — communicates with local LLM libraries compiled to WASM (e.g., Llama).
c. Backend orchestrator (moly-backend)
- Exposes a local API server (via Robius) for the front‑end to call into WASM modules.
- Implements storage interfaces: download_models, metadata, remote communication.
d. External services
- Real MoFa server (HTTP/gRPC) via moly-mofa crate.
- Fake MoFa backend (HTTP) for testing (moly-fake-backend).
- Optional external LLM endpoints (OpenAI) driven by moly-protocol/open_ai.rs.
e. Packaging & CLI Tools
- moly-runner: CLI wrapper to ensure WasmEdge is installed and environment is configured.
- packaging scripts: cargo-packager configurations generating native installers.
f. CI/CD
- GitHub Actions workflows for continuous integration, build artifacts, and releases.

##### Relationships and interactions
- User interacts with Makepad UI → triggers actions (e.g., “new chat”, “download model”).
- UI layer calls into moly-backend’s local API (over in‑process RPC via Robius).
- moly-backend dispatches calls to:
- WASM modules (for UI rendering logic or LLM inference).
- Store module (downloads, reads/writes metadata).
- moly-mofa or fake-backend HTTP client (for agent interactions).
- WASM modules run in WasmEdge sandbox, returning results back to the orchestrator.
- Orchestrator returns results back to the UI via the Robius bridge.
- Packaging pipeline packages the final binary plus WASM files and resources into platform‑specific installers.

##### Architectural patterns and design principles
- Modular multi‑crate Rust workspace (separation of concerns).
- WASM-based plugin architecture (sandboxing LLM code).
- Clear separation between UI, protocol, backend orchestration, and storage.
- Use of a shared protocol crate to enforce strong typing across boundaries.
- Dependency injection of fake vs. real backends for testing and development.

##### Detail
- Every essential crate as its own component or subcomponent.
- Both real and fake backend paths.
- CI/CD and packaging as higher‑level external flows if space permits.
- Naming matches directory names (e.g., “moly-protocol”, “moly-backend”, “moly-runner”).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend (Makepad UI)" 
        direction TB
        Main["main.rs"]:::frontend
        App["app.rs"]:::frontend
        ChatUI["src/chat/"]:::frontend
        Landing["src/landing/"]:::frontend
        MyModels["src/my_models/"]:::frontend
        Settings["src/settings/"]:::frontend
        SharedUI["src/shared/"]:::frontend
    end

    subgraph "Local Data Layer" 
        direction TB
        DataRoot["src/data/"]:::frontend
        DataChats["src/data/chats/"]:::frontend
        DataDownloads["src/data/downloads/"]:::frontend
        DataPrefs["src/data/preferences.rs"]:::frontend
        DataSearch["src/data/search/"]:::frontend
        DataFS["src/data/filesystem.rs"]:::frontend
        DataStore["src/data/store.rs"]:::frontend
    end

    %% Protocol Definitions
    subgraph "moly-protocol" 
        direction TB
        ProtoToml["Cargo.toml"]:::protocol
        ProtoSchema["src/protocol.rs"]:::protocol
        ProtoData["src/data.rs"]:::protocol
        ProtoOpenAI["src/open_ai.rs"]:::protocol
    end

    %% Backend Orchestrator
    subgraph "moly-backend" 
        direction TB
        BE_Cargo["Cargo.toml"]:::backend
        BE_Lib["src/lib.rs"]:::backend
        subgraph "backend_impls"
            direction TB
            BE_APIImp["api_server.rs"]:::backend
            BE_UIImp["chat_ui.rs"]:::backend
        end
        subgraph "store"
            direction TB
            DownloadFiles["download_files.rs"]:::backend
            ModelCards["model_cards.rs"]:::backend
            Models["models.rs"]:::backend
            RemoteStore["remote.rs"]:::backend
        end
    end

    %% WASM Modules Sandbox
    subgraph "WASM Modules (WasmEdge Sandbox)" 
        direction TB
        chat_wasm["chat_ui.wasm"]:::wasm
        llama_wasm["llama-api-server.wasm"]:::wasm
    end

    %% External Services
    subgraph "External Services" 
        direction TB
        FakeMoFa["moly-fake-backend"]:::external
        RealMoFa["moly-mofa"]:::external
        OpenAIExt["OpenAI API"]:::external
    end

    %% Tools and Packaging
    subgraph "Tools & Packaging" 
        direction TB
        Runner["moly-runner"]:::tool
        BuildSh["build.sh"]:::tool
        PackagingDir["packaging/"]:::tool
    end

    %% CI/CD
    subgraph "CI/CD Workflows" 
        direction TB
        CI1[".github/workflows/ci-build.yml"]:::ci
        CI2[".github/workflows/release.yml"]:::ci
    end

    %% Connections
    Main --> App
    App --> ChatUI
    App --> Landing
    App --> MyModels
    App --> Settings
    App --> SharedUI
    App --> DataRoot
    SharedUI --> DataStore
    DataRoot --> DataChats
    DataRoot --> DataDownloads
    DataRoot --> DataPrefs
    DataRoot --> DataSearch
    DataRoot --> DataFS

    App -->|"RPC via Robius"| BE_Lib
    BE_Lib --> BE_APIImp
    BE_Lib --> BE_UIImp
    BE_Lib --> DownloadFiles
    BE_Lib --> ModelCards
    BE_Lib --> Models
    BE_Lib --> RemoteStore

    BE_Lib --> chat_wasm
    BE_Lib --> llama_wasm

    BE_Lib --> FakeMoFa
    BE_Lib --> RealMoFa
    RealMoFa --> ProtoOpenAI
    BE_Lib --> ProtoSchema
    App --> ProtoSchema

    BE_Lib --> DataRoot

    Runner --> BE_Lib
    Runner --> chat_wasm
    Runner --> llama_wasm

    PackagingDir --> BE_Lib
    BuildSh --> PackagingDir

    CI1 --> BE_Lib
    CI1 --> Main
    CI1 --> chat_wasm
    CI2 --> PackagingDir
    CI2 --> Runner

    %% Click Events
    click Main "https://github.com/moxin-org/moly/blob/main/src/main.rs"
    click App "https://github.com/moxin-org/moly/blob/main/src/app.rs"
    click ChatUI "https://github.com/moxin-org/moly/tree/main/src/chat/"
    click Landing "https://github.com/moxin-org/moly/tree/main/src/landing/"
    click MyModels "https://github.com/moxin-org/moly/tree/main/src/my_models/"
    click Settings "https://github.com/moxin-org/moly/tree/main/src/settings/"
    click SharedUI "https://github.com/moxin-org/moly/tree/main/src/shared/"
    click DataRoot "https://github.com/moxin-org/moly/tree/main/src/data/"
    click DataChats "https://github.com/moxin-org/moly/tree/main/src/data/chats/"
    click DataDownloads "https://github.com/moxin-org/moly/tree/main/src/data/downloads/"
    click DataPrefs "https://github.com/moxin-org/moly/blob/main/src/data/preferences.rs"
    click DataSearch "https://github.com/moxin-org/moly/tree/main/src/data/search/"
    click DataFS "https://github.com/moxin-org/moly/blob/main/src/data/filesystem.rs"
    click DataStore "https://github.com/moxin-org/moly/blob/main/src/data/store.rs"
    click ProtoToml "https://github.com/moxin-org/moly/blob/main/moly-protocol/Cargo.toml"
    click ProtoSchema "https://github.com/moxin-org/moly/blob/main/moly-protocol/src/protocol.rs"
    click ProtoData "https://github.com/moxin-org/moly/blob/main/moly-protocol/src/data.rs"
    click ProtoOpenAI "https://github.com/moxin-org/moly/blob/main/moly-protocol/src/open_ai.rs"
    click BE_Cargo "https://github.com/moxin-org/moly/blob/main/moly-backend/Cargo.toml"
    click BE_Lib "https://github.com/moxin-org/moly/blob/main/moly-backend/src/lib.rs"
    click BE_APIImp "https://github.com/moxin-org/moly/blob/main/moly-backend/src/backend_impls/api_server.rs"
    click BE_UIImp "https://github.com/moxin-org/moly/blob/main/moly-backend/src/backend_impls/chat_ui.rs"
    click DownloadFiles "https://github.com/moxin-org/moly/blob/main/moly-backend/src/store/download_files.rs"
    click ModelCards "https://github.com/moxin-org/moly/blob/main/moly-backend/src/store/model_cards.rs"
    click Models "https://github.com/moxin-org/moly/blob/main/moly-backend/src/store/models.rs"
    click RemoteStore "https://github.com/moxin-org/moly/blob/main/moly-backend/src/store/remote.rs"
    click chat_wasm "https://github.com/moxin-org/moly/blob/main/moly-backend/wasm/chat_ui.wasm"
    click llama_wasm "https://github.com/moxin-org/moly/blob/main/moly-backend/wasm/llama-api-server.wasm"
    click FakeMoFa "https://github.com/moxin-org/moly/blob/main/moly-fake-backend/src/lib.rs"
    click RealMoFa "https://github.com/moxin-org/moly/blob/main/moly-mofa/src/lib.rs"
    click Runner "https://github.com/moxin-org/moly/blob/main/moly-runner/src/main.rs"
    click BuildSh "https://github.com/moxin-org/moly/blob/main/build.sh"
    click PackagingDir "https://github.com/moxin-org/moly/tree/main/packaging/"
    click CI1 "https://github.com/moxin-org/moly/blob/main/.github/workflows/ci-build.yml"
    click CI2 "https://github.com/moxin-org/moly/blob/main/.github/workflows/release.yml"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0066CC,color:#003366
    classDef backend fill:#E6FFE6,stroke:#339933,color:#006600
    classDef wasm fill:#FFF4E6,stroke-dasharray: 5 5,stroke:#FF9900,color:#663300
    classDef external fill:#F2F2F2,stroke:#999999,color:#333333
    classDef tool fill:#FFF0F5,stroke:#CC3399,color:#660033
    classDef protocol fill:#F0F8FF,stroke:#3399FF,color:#003366
    classDef ci fill:#FFEFD5,stroke:#FF9900,color:#663300
```
