# filecoin-project/lotus architecture

> Architecture diagram of the GitHub repository filecoin-project/lotus, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2024-12-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/filecoin-project/lotus
- Repository: https://github.com/filecoin-project/lotus

## Overview

##### Main Components Identification

The system can be broken down into these major components:

a. Core Components:
- Chain Management (/chain)
- Storage System (/storage)
- Node Management (/node)
- API Layer (/api)
- Blockchain Components (/chain/actors)
- Mining Operations (/miner)

b. Supporting Components:
- CLI Interface (/cli)
- Configuration Management (/node/config)
- Network Communication (/lib/peermgr)
- Metrics and Monitoring (/metrics)

##### Architectural Layers

**┌─────────────────────────────────────────────┐**
- Interface Layer               │
- API (REST/RPC)                          │
- CLI Tools                               │
- ┤
- Service Layer                  │
- Node Services                           │
- Chain Management                        │
- Storage Management                      │
- ┤
- Core Layer                      │
- Blockchain Logic                        │
- Mining Operations                       │
- Actor System                            │
- ┤
- Storage Layer                   │
- Sector Management                       │
- IPFS Integration                        │
- Proof Subsystem                         │
- ┘

##### Component Relationships

- Data flow (→): Shows how data moves between components
- Dependencies (⇢): Shows which components depend on others
- Event flow (⇉): Shows event propagation paths

##### Specific Implementation Details

Technical details such as:
- Go modules structure
- Actor system implementation
- Storage pipeline flow
- Network communication protocols

##### Monitoring and Management

Integration points for:
- Prometheus metrics
- Grafana dashboards
- Health checking systems
- Logging infrastructure

- Nested components
- Different connection types
- Clear labeling
- Proper grouping of related components

Remember to:
- Notes for critical components
- Both synchronous and asynchronous interactions
- Scalability points
- Security boundaries

This system design should reflect Lotus's nature as a complex distributed system implementing the Filecoin protocol, with emphasis on its storage, consensus, and networking capabilities.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Styles and classes
    classDef interface fill:#9370DB,stroke:#333,stroke-width:2px
    classDef core fill:#4169E1,stroke:#333,stroke-width:2px
    classDef storage fill:#3CB371,stroke:#333,stroke-width:2px
    classDef network fill:#FFA500,stroke:#333,stroke-width:2px
    classDef support fill:#A9A9A9,stroke:#333,stroke-width:2px

    %% Interface Layer
    subgraph Interface
        API["API Layer"]
        CLI["CLI Interface"]
        APIDoc["API Documentation"]
        APIClient["API Client"]
    end

    %% Service Layer
    subgraph Services
        NodeMgmt["Node Management"]
        Config["Configuration"]
        PeerMgr["Peer Manager"]
        Metrics["Metrics & Monitoring"]
        PayCh["Payment Channels"]
    end

    %% Core Layer
    subgraph Core
        ChainMgmt["Chain Management"]
        BlockProc["Block Processing"]
        StateMgmt["State Management"]
        VM["Virtual Machine"]
        Actors["Actor System"]
        Mining["Mining Operations"]
    end

    %% Storage Layer
    subgraph Storage
        StorageMgmt["Storage Management"]
        SectorMgmt["Sector Management"]
        StoragePipe["Storage Pipeline"]
        WinPost["Window PoSt"]
        PathMgmt["Path Management"]
        BlockStore["Block Store"]
        SplitStore["Split Store"]
    end

    %% Relationships
    API --> NodeMgmt
    CLI --> NodeMgmt
    NodeMgmt --> ChainMgmt
    NodeMgmt --> StorageMgmt
    PeerMgr --> ChainMgmt
    ChainMgmt --> BlockProc
    ChainMgmt --> StateMgmt
    ChainMgmt --> VM
    VM --> Actors
    StorageMgmt --> SectorMgmt
    StorageMgmt --> StoragePipe
    StorageMgmt --> WinPost
    StorageMgmt --> PathMgmt
    BlockStore --> ChainMgmt
    SplitStore --> BlockStore
    Mining --> ChainMgmt
    Mining --> StorageMgmt
    PayCh --> ChainMgmt
    Metrics --> NodeMgmt
    Config --> NodeMgmt

    %% Click events
    click ChainMgmt "https://github.com/filecoin-project/lotus/tree/master/chain"
    click BlockProc "https://github.com/filecoin-project/lotus/tree/master/chain/store"
    click StateMgmt "https://github.com/filecoin-project/lotus/tree/master/chain/state"
    click VM "https://github.com/filecoin-project/lotus/tree/master/chain/vm"
    click Actors "https://github.com/filecoin-project/lotus/tree/master/chain/actors"
    click StorageMgmt "https://github.com/filecoin-project/lotus/tree/master/storage"
    click SectorMgmt "https://github.com/filecoin-project/lotus/tree/master/storage/sealer"
    click StoragePipe "https://github.com/filecoin-project/lotus/tree/master/storage/pipeline"
    click WinPost "https://github.com/filecoin-project/lotus/tree/master/storage/wdpost"
    click PathMgmt "https://github.com/filecoin-project/lotus/tree/master/storage/paths"
    click NodeMgmt "https://github.com/filecoin-project/lotus/tree/master/node"
    click Config "https://github.com/filecoin-project/lotus/tree/master/node/config"
    click API "https://github.com/filecoin-project/lotus/blob/master/api/api_full.go"
    click APIClient "https://github.com/filecoin-project/lotus/tree/master/api/client"
    click APIDoc "https://github.com/filecoin-project/lotus/tree/master/api/docgen"
    click Mining "https://github.com/filecoin-project/lotus/blob/master/miner/miner.go"
    click PeerMgr "https://github.com/filecoin-project/lotus/blob/master/lib/peermgr/peermgr.go"
    click CLI "https://github.com/filecoin-project/lotus/blob/master/cli/cmd.go"
    click Metrics "https://github.com/filecoin-project/lotus/blob/master/metrics/exporter.go"
    click PayCh "https://github.com/filecoin-project/lotus/blob/master/paychmgr/paych.go"
    click BlockStore "https://github.com/filecoin-project/lotus/blob/master/blockstore/blockstore.go"
    click SplitStore "https://github.com/filecoin-project/lotus/tree/master/blockstore/splitstore"

    %% Style applications
    class API,CLI,APIDoc,APIClient interface
    class ChainMgmt,BlockProc,StateMgmt,VM,Actors,Mining core
    class StorageMgmt,SectorMgmt,StoragePipe,WinPost,PathMgmt,BlockStore,SplitStore storage
    class PeerMgr network
    class NodeMgmt,Config,Metrics,PayCh support
```
