# mamoe/mirai architecture

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

- Interactive diagram: https://gitdiagram.com/mamoe/mirai
- Repository: https://github.com/mamoe/mirai

## Overview

##### Main modules and components
- Core API & Implementation:
– “mirai-core-api” defines the public interfaces: the bot, contact, message, and event models.
– “mirai-core” holds the main implementations (network handling, message protocols, lifecycle management, event channels, etc.).
– “mirai-core-mock” is used for testing simulations of bots, contacts, and messages.
– “mirai-core-utils” provides shared utility functions, data structures, cryptography, logging and other helper classes.
- Console and Frontend Components:
– “mirai-console” (with subcomponents for backend and testing) works as an interactive console-based bot launcher/command processor.
– Android frontend components such as “mirai-console/frontend/mirai‐android” and “mirai-console-frontend‐base” support Android integration.
– “mirai-console/frontend/mirai‐console-terminal” handles terminal/CLI frontends.
- Build, Packaging and Tools:
– “buildSrc” (with many Kotlin scripts and utilities) provides build configuration, dependency management and publishing helpers.
– “ci-release-helper” and “mirai-dokka” are also integrated into the project for continuous integration, release automation and documentation generation.
– Other modules such as the Gradle plugin and IntelliJ plugin (under “mirai-tools”) help extend mirai for development and integration into build environments.

##### Main architectural layers and relationships
- API and Domain Layer:
– Represented by the “mirai-core-api” project. This contains all the domain classes that represent bots, contacts, messages, events, etc.
- Core Logic / Infrastructure Layer:
– Found in “mirai-core”, “mirai-core-mock” and “mirai-core-utils”. This is where the business logic lives (message decoding/encoding, network protocol handling, event channel, plugin system, cryptographic routines). These components are largely independent of any frontend.
- Network and Communication Layer:
– Features the network components found in “mirai-core” (particularly in the network/handler, protocol, and components directories). It implements the communication pipelines, such as connection management, authentication, the protocol “packet” system, event channels, and message routing.
- Frontends & Client Layers:
– The “mirai-console” and its various submodules (Android, terminal, etc.) act as the presentation/interaction layer where users (or developers) can interact with the bot library.
- Build and Extension Tooling:
– Build scripts, Gradle plugins, and IDE integrations enable modular deployment, plugin management, testing and release automation.

##### Architectural design patterns and principles to capture
- Modular & Plugin Architecture:
– The system is divided into several independent modules that interact through clearly defined APIs—facilitating extension (e.g. plugins, custom message processes).
- Event-Driven and Asynchronous Capabilities:
– The design uses event channels and listeners (with decoupled event dispatchers) that enable asynchronous message processing.
- Separation of Concerns:
– Core network and protocol logic is separated from the frontend aspects so that the same API can serve both headless and UI–driven clients.
- Dependency Injection & Component-based design:
– Components like network handlers, event dispatchers, and protocol strategies are loosely coupled so that they can be replaced or extended.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% API and Domain Layer
    subgraph "API and Domain Layer"
        A["mirai-core-api"]:::core
    end

    %% Core Logic / Infrastructure Layer
    subgraph "Core Logic / Infrastructure Layer"
        B["mirai-core"]:::core
        C["mirai-core-utils"]:::core
        D["mirai-core-mock"]:::core
    end

    %% Frontends & Client Layers
    subgraph "Frontends & Client Layers"
        E["mirai-console"]:::frontend
        subgraph "Console Frontends"
            F["mirai-android"]:::frontend
            G["mirai-console-frontend-base"]:::frontend
            H["mirai-console-terminal"]:::frontend
        end
    end

    %% Build & Deployment Tools
    subgraph "Build & Deployment Tools"
        I["buildSrc"]:::build
        J["ci-release-helper"]:::build
        K["mirai-dokka"]:::build
        L["mirai-deps-test"]:::build
    end

    %% Relationships between layers
    A -->|"providesAPIfor"| B
    A -->|"providesAPIfor"| C
    A -->|"providesAPIfor"| D

    B -->|"implementsNetwork/Events"| C
    B -->|"testedBy"| D

    E -->|"invokesAPI/Core"| A
    E -->|"invokesCoreLogic"| B

    F -->|"integratesWith"| E
    G -->|"integratesWith"| E
    H -->|"integratesWith"| E

    %% Tools support
    I ---|"builds"| A
    I ---|"builds"| B
    I ---|"builds"| E

    J ---|"CIRelease"| A
    J ---|"CIRelease"| B
    J ---|"CIRelease"| E

    K ---|"docsFor"| A
    K ---|"docsFor"| B
    K ---|"docsFor"| E

    L ---|"dependencyTests"| A
    L ---|"dependencyTests"| B
    L ---|"dependencyTests"| E

    %% Click Events
    click A "https://github.com/mamoe/mirai/tree/dev/mirai-core-api/"
    click B "https://github.com/mamoe/mirai/tree/dev/mirai-core/"
    click C "https://github.com/mamoe/mirai/tree/dev/mirai-core-utils/"
    click D "https://github.com/mamoe/mirai/tree/dev/mirai-core-mock/"
    click E "https://github.com/mamoe/mirai/tree/dev/mirai-console/"
    click F "https://github.com/mamoe/mirai/tree/dev/mirai-console/frontend/mirai-android/"
    click G "https://github.com/mamoe/mirai/tree/dev/mirai-console/frontend/mirai-console-frontend-base/"
    click H "https://github.com/mamoe/mirai/tree/dev/mirai-console/frontend/mirai-console-terminal/"
    click I "https://github.com/mamoe/mirai/tree/dev/buildSrc/"
    click J "https://github.com/mamoe/mirai/tree/dev/ci-release-helper/"
    click K "https://github.com/mamoe/mirai/tree/dev/mirai-dokka/"
    click L "https://github.com/mamoe/mirai/tree/dev/mirai-deps-test/"

    %% Styles
    classDef core fill:#FFCCFF,stroke:#8B008B,stroke-width:2px;
    classDef frontend fill:#ADD8E6,stroke:#00008B,stroke-width:2px;
    classDef build fill:#CCFFCC,stroke:#006400,stroke-width:2px;
```
