# latticexyz/mud architecture

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

- Interactive diagram: https://gitdiagram.com/latticexyz/mud
- Repository: https://github.com/latticexyz/mud

## Overview

##### High-Level Architecture Components

- World (central component representing the smart contract environment)
- Store (data storage layer)
- Systems (business logic layer)
- Tables (data structure layer)

b. Client-Side Components (Top Layer):
- React Integration
- Phaser Integration
- ThreeJS Integration
- Vanilla JS Integration
- Client Sync Layer

c. Development Tools (Right Side):
- CLI Tools
- Dev Tools
- Explorer
- Indexer Services

d. Infrastructure Components (Bottom Layer):
- EVM Compatible Chains
- Storage Adapters (SQLite, PostgreSQL)
- Faucet Service

##### Connection and Data Flow

- Bidirectional sync between clients and blockchain
- Data flow from Systems to Store
- Indexer data flow to storage adapters
- CLI interactions with deployment process

##### Component Details

For each major component, include:
- Component name
- Key subcomponents
- Primary responsibilities
- Interface points

##### Specific Implementation Details

Specialized features:
- Module system integration
- ECS (Entity Component System) pattern
- Table-based storage structure
- Network synchronization layer

##### Layer Organization

In clear layers:
- Application Layer (Top)
- Protocol Layer (Middle)
- Infrastructure Layer (Bottom)

##### Integration Points

Integration capabilities:
- ERC20/ERC721 module connections
- Custom module extension points
- Client framework integrations
- External service connections

- The modular nature of the framework
- The separation between onchain and offchain components
- The synchronization mechanisms between clients and blockchain
- The development workflow and tools integration

Key Considerations:
##### Extensibility points for custom modules and systems

- How components interact in a MUD application
- Where their code fits in the larger architecture
- How data flows through the system
- Available integration points and tools
- The relationship between onchain and offchain components

Remember to maintain a balance between detail and clarity, focusing on the key architectural patterns while avoiding overwhelming detail at the component implementation level.

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Client Layer"
        direction TB
        React["React Integration"]:::client
        Phaser["Phaser Integration"]:::client
        ThreeJS["ThreeJS Integration"]:::client
        VanillaJS["Vanilla JS Integration"]:::client
        ClientSync["Client Sync Layer"]:::client
    end

    subgraph "Core Layer"
        direction TB
        World["World"]:::core
        Store["Store"]:::core
        Systems["Systems"]:::core
        Tables["Tables"]:::core
    end

    subgraph "Development Tools"
        direction TB
        CLI["CLI Tools"]:::devtools
        DevTools["Dev Tools"]:::devtools
        Explorer["Explorer"]:::devtools
        Indexer["Indexer Services"]:::devtools
    end

    subgraph "Infrastructure Layer"
        direction TB
        EVM["EVM Compatible Chains"]:::infra
        subgraph "Storage Adapters"
            SQLite["SQLite"]:::storage
            PostgreSQL["PostgreSQL"]:::storage
        end
        Faucet["Faucet Service"]:::infra
    end

    %% Connections
    React --> ClientSync
    Phaser --> ClientSync
    ThreeJS --> ClientSync
    VanillaJS --> ClientSync
    ClientSync <--> World
    World <--> Store
    World <--> Systems
    Store <--> Tables
    Systems <--> Tables
    Indexer --> SQLite
    Indexer --> PostgreSQL
    World <--> EVM
    CLI --> World
    DevTools --> World
    Explorer --> Store
    Faucet --> EVM

    %% Click Events
    click World "https://github.com/latticexyz/mud/tree/main/packages/world/"
    click Store "https://github.com/latticexyz/mud/tree/main/packages/store/"
    click React "https://github.com/latticexyz/mud/tree/main/packages/react/"
    click Phaser "https://github.com/latticexyz/mud/tree/main/templates/phaser/"
    click ThreeJS "https://github.com/latticexyz/mud/tree/main/templates/threejs/"
    click VanillaJS "https://github.com/latticexyz/mud/tree/main/templates/vanilla/"
    click CLI "https://github.com/latticexyz/mud/tree/main/packages/cli/"
    click DevTools "https://github.com/latticexyz/mud/tree/main/packages/dev-tools/"
    click Explorer "https://github.com/latticexyz/mud/tree/main/packages/explorer/"
    click Indexer "https://github.com/latticexyz/mud/tree/main/packages/store-indexer/"
    click SQLite "https://github.com/latticexyz/mud/tree/main/packages/store-sync/src/sqlite/"
    click PostgreSQL "https://github.com/latticexyz/mud/tree/main/packages/store-sync/src/postgres/"
    click Faucet "https://github.com/latticexyz/mud/tree/main/packages/faucet/"

    %% Styles
    classDef core fill:#2374ab,stroke:#333,stroke-width:2px
    classDef client fill:#57a773,stroke:#333,stroke-width:2px
    classDef devtools fill:#ff8c42,stroke:#333,stroke-width:2px
    classDef infra fill:#7d4e57,stroke:#333,stroke-width:2px
    classDef storage fill:#6c757d,stroke:#333,stroke-width:2px

    %% Legend
    subgraph Legend
        L1["Core Components"]:::core
        L2["Client Components"]:::client
        L3["Development Tools"]:::devtools
        L4["Infrastructure"]:::infra
        L5["Storage"]:::storage
    end
```
