# milkyway-labs/milkyway architecture

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

- Interactive diagram: https://gitdiagram.com/milkyway-labs/milkyway
- Repository: https://github.com/milkyway-labs/milkyway

## Overview

##### Project Overview and Purpose
- MilkyWay is a blockchain-based protocol that provides liquid staking and restaking capabilities. It is a modular layer-1 coordination chain built on Cosmos SDK that allows diverse modules (assets, liquidvesting, operators, pools, restaking, rewards, services, tokenfactory, IBC hooks, etc.) to plug into the system.
- The README makes it clear that the project is designed to provide a secure and flexible staking infrastructure while allowing external tools (CLI, wallets, block explorers) to interact with the chain.
- The file structure contains directories for application logic (“app”), command-line interface (“cmd”), module implementations under “x”, and APIs and protobuf definitions (in “api” and “proto”), all indicative of a complex, modular blockchain ecosystem.

##### Major Components
Breaking the system into these high-level components:
A. Node and Core Application:
- “app” – Contains core blockchain application logic (ABCI, genesis, encoding, forks, upgrades, simulation, etc.).
- “cmd/milkywayd” – Provides the CLI/node daemon to start a MilkyWay blockchain node.
B. Modules/Subsystems:
- “x” directory – Includes all functional modules such as assets, bank, ibc-hooks, liquidvesting, operators, pools, restaking, rewards, services, and tokenfactory.
- Each module has its keeper, message server, client CLI, and testing utilities to encapsulate its functionality.
C. API and Communication Layer:
- “api” directory – Contains REST and gRPC endpoints for the modules (with versioned subdirectories and auto-generated protobuf files). This indicates support for client communication.
- “proto” directory – Provides protobuf definitions for all modules and external compatibility; this is essential for both the gRPC services and integration with CosmJS-compatible client libraries.
D. Development, Testing, and Build Infrastructure:
- “client”, “tools”, “scripts”, and “Makefile” – Components that support documentation generation, consensus testing, mock generation, and overall build/deployment.
E. External Interactions:
- Integration with wallets (Keplr, Cosmos Station, Leap) and external blockchain explorers as mentioned in the README.
- GitHub workflows, CI/CD configurations, and Dockerfiles for deployment.

##### Relationships and Data Flow
- The CLI daemon (milkywayd) initializes the core “app” which acts as a container for all individual modules (from “x”) that run the on-chain logic. The “app” communicates with the Tendermint-based consensus engine using ABCI.
- When transactions are submitted (from external wallets or direct CLI commands), they get normalized by the API layer (REST/gRPC as defined in “api” and “proto” directories) and then processed by the appropriate module (e.g., liquidvesting, rewards, operators).
- Internal state transitions, genesis initialization, and upgrades are handled within the “app” and through module-specific upgrade logic.
- Various “keepers” in the modules encapsulate business logic and ensure safe manipulation of the blockchain state.

##### Architectural Patterns and Design Principles
- Modular Architecture: The use of separate modules (each in the “x” folders) reflects a microkernel design where common infrastructure (e.g., account management, staking) is decoupled from application-specific logic.
- API-Driven Communication: The clearly separated “api” and “proto” directories indicate a well-defined communication layer using gRPC and protocol buffers.
- Separation of Concerns: The organization keeps CLI commands, application logic, module-specific keepers, and tests in different directories, enforcing a clear separation between interface, implementation, and testing.
- Extensibility: The number of modules and available hooks (for instance, IBC hooks) demonstrates the system’s flexibility and extensibility.

##### Assembly of the Components
- Branch it out to two major sections: “Core Application (app)” and “Module Services (x/*)”. Inside the module section, show individual modules grouped logically.
- Also plot “External Clients” (CLI, Wallets, Third-party Explorers) and show their communication channels into the API layer.

##### Final Advice to the Principal Software Engineer
- That architectural patterns such as modularity, separation of concerns, and resiliency are visually evident.
- Don’t hesitate to break down complex modules into further sub-components if necessary, especially if they own several “keeper”, “msg_server”, and “client” elements.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Clients
    EC["External Clients (CLI,Wallets,Explorers)"]:::external

    %% API Layer and Proto Definitions
    API["API Layer (api)"]:::api
    Proto["Proto Definitions (proto)"]:::api

    %% MilkyWay Node and Core App
    MW["MilkyWay Blockchain Node (milkywayd)"]:::nodeCore
    Core["Core Application (app)"]:::nodeCore

    %% Module Services Subgraph
    subgraph "Module Services"
        Assets["Assets Module"]:::module
        Liquidvesting["Liquidvesting Module"]:::module
        Operators["Operators Module"]:::module
        Pools["Pools Module"]:::module
        Restaking["Restaking Module"]:::module
        Rewards["Rewards Module"]:::module
        Services["Services Module"]:::module
        Tokenfactory["Tokenfactory Module"]:::module
        IBCHooks["IBC Hooks Module"]:::module
    end

    %% Developer Tools & Build Pipeline Subgraph
    subgraph "Developer Tools & Build Pipeline"
        Client["Client & Documentation"]:::infra
        Tools["Development Tools (tools)"]:::infra
        Scripts["Scripts & Build Utilities"]:::infra
        Make["Build Config (Makefile)"]:::infra
        CI["CI/CD (.github/workflows)"]:::infra
        Docker1["Dockerfile"]:::infra
        Docker2["Dockerfile-ubuntu"]:::infra
        BuildPipe["Build Pipeline"]:::infra
    end

    %% Data Flow Connections
    EC -->|"submitTransactions"| API
    API -->|"normalizeCalls"| MW
    MW -->|"initialize"| Core
    Core -->|"manageLogic"| Assets
    Core --> Liquidvesting
    Core --> Operators
    Core --> Pools
    Core --> Restaking
    Core --> Rewards
    Core --> Services
    Core --> Tokenfactory
    Core --> IBCHooks
    %% Modules respond back to API
    IBCHooks -.->|"returnResults"| API

    %% API to Proto Definitions
    API -->|"useDefs"| Proto

    %% Build Pipeline deployment to Node
    BuildPipe -->|"deploys"| MW

    %% Styling
    classDef nodeCore fill:#FFC107,stroke:#000,stroke-width:2px;
    classDef module fill:#FF9800,stroke:#000,stroke-width:1px;
    classDef api fill:#03A9F4,stroke:#000,stroke-width:1px;
    classDef external fill:#9C27B0,stroke:#000,stroke-width:1px;
    classDef infra fill:#8BC34A,stroke:#000,stroke-width:1px;

    %% Click Events
    click Core "https://github.com/milkyway-labs/milkyway/tree/main/app"
    click MW "https://github.com/milkyway-labs/milkyway/tree/main/cmd/milkywayd"
    click Assets "https://github.com/milkyway-labs/milkyway/tree/main/x/assets"
    click Liquidvesting "https://github.com/milkyway-labs/milkyway/tree/main/x/liquidvesting"
    click Operators "https://github.com/milkyway-labs/milkyway/tree/main/x/operators"
    click Pools "https://github.com/milkyway-labs/milkyway/tree/main/x/pools"
    click Restaking "https://github.com/milkyway-labs/milkyway/tree/main/x/restaking"
    click Rewards "https://github.com/milkyway-labs/milkyway/tree/main/x/rewards"
    click Services "https://github.com/milkyway-labs/milkyway/tree/main/x/services"
    click Tokenfactory "https://github.com/milkyway-labs/milkyway/tree/main/x/tokenfactory"
    click IBCHooks "https://github.com/milkyway-labs/milkyway/tree/main/x/ibc-hooks"
    click API "https://github.com/milkyway-labs/milkyway/tree/main/api"
    click Proto "https://github.com/milkyway-labs/milkyway/tree/main/proto"
    click Client "https://github.com/milkyway-labs/milkyway/tree/main/client"
    click Tools "https://github.com/milkyway-labs/milkyway/tree/main/tools"
    click Scripts "https://github.com/milkyway-labs/milkyway/tree/main/scripts"
    click Make "https://github.com/milkyway-labs/milkyway/tree/main/Makefile"
    click CI "https://github.com/milkyway-labs/milkyway/blob/main/.github"
    click Docker1 "https://github.com/milkyway-labs/milkyway/tree/main/Dockerfile"
    click Docker2 "https://github.com/milkyway-labs/milkyway/tree/main/Dockerfile-ubuntu"
```
