# didi/mpx architecture

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

- Interactive diagram: https://gitdiagram.com/didi/mpx
- Repository: https://github.com/didi/mpx

## Overview

##### Main components and layers
- Developer-facing Tools and CLI:
- mpx CLI (referenced in the README via “mpx create mpx-project”), which scaffolds and helps manage the project.
- Build and Transformation Layer:
- Webpack and Babel integrations, including the @mpxjs/webpack-plugin and related build scripts that perform code transformations (e.g., dynamic component conversion, single-file component parsing, etc.).
- Babel plugins (like @mpxjs/babel-plugin-inject-page-events) that facilitate enhanced API handling.
- Core Runtime & Abstraction:
- The @mpxjs/core package, which provides the runtime, data reactivity, component creation (createPage, createComponent, etc.), lifecycle management, and overall framework behavior.
- Platform-specific adapters in the “packages/api-proxy” which convert native mini-program API calls into a unified interface that works across platforms.
- State and Utility Modules:
- Store solutions (@mpxjs/store, @mpxjs/pinia) for state management.
- Utility libraries (e.g., @mpxjs/utils, size-report, etc.) that support logging, type inference, and performance profiling.
- Additional Ecosystem Modules:
- Packages for network requests (@mpxjs/fetch), UI components (mpx-cube-ui), and even plugins for unocss support.
- Documentation and Examples:
- The docs-vitepress directory and examples folder help illustrate usage and provide a live demonstration of the framework’s capabilities.

##### Relationships and Interactions
- A developer writes code in the Mpx “single file components” with enhanced template syntax.
- The CLI and build tools (webpack configuration using the mpx webpack-plugin) transform the source code:
- They invoke Babel and other transformers that compile extended syntax and apply performance and bundle optimizations.
- The build process converts components into platform‐specific artifacts (for WeChat, Ali, etc.).
- At runtime, the Mpx core provides a lightweight reactive layer (with computed, watch, and data binding) that interfaces with the low-level native mini-program APIs. The abstraction provided by the api-proxy ensures a consistent API experience across multiple platforms.
- State management libraries plug into the runtime to offer robust patterns similar to Vuex (store) or Pinia.
- Separate packages (like fetch) form adapter layers to manage network requests while considering platform nuances (e.g., concurrency limitations).

##### Key Architectural Patterns and Design Principles
- Modular Monorepo Structure:
- Sub-packages are organized under “packages” and “examples,” ensuring clear separation of concerns and independent versioning.
- Layered Separation:
- The architecture splits the concerns between development tooling (CLI, build plugins), runtime (core, reactivity, platform proxy), and ecosystem modularity (state, UI components, utilities).
- Platform Abstraction:
- The use of api-proxy and dynamic platform adapters enables uniform cross-platform behavior.
- Extensibility and Pluggability:
- The framework’s build layer (webpack, babel plugins) is designed to be extensible and integrate seamlessly with other npm and build ecosystem tools.
- High Performance via Lightweight Core:
- The runtime and compilation steps focus on optimized output and minimal runtime overhead (~14KB after compression), with heavy emphasis on compile-time optimizations.

- Top Layer: Developer’s environment (IDE, mpx CLI, scaffolded project)
- Middle Layer: Build and transformation pipeline (Webpack configuration, Babel plugins)
- Lower Layer: Runtime environment (Mpx core, platform adapters, state management, utilities) along with output targets (show separate branches for each platform like WeChat, Ali, etc.)
- Code transformation (from original source to compiled mini-app)
- Dependency flows (e.g., mpx core relies on state libraries and api-proxy)
- Labels such as “mpx CLI”, “Webpack Plugin (@mpxjs/webpack-plugin)”, “Runtime Layer (mpx core)”, “API Adapter (api-proxy)”, “State Modules (store, pinia)”, “Utility Modules”, and “Platform Targets”.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Developer Environment
    subgraph "Developer Environment"
        mpxCLI["mpx CLI"]:::developer
    end

    %% Build and Transformation Layer
    subgraph "Build and Transformation Layer"
        webpackPlugin["Webpack Plugin (@mpxjs/webpack-plugin)"]:::transformation
        babelPlugin["Babel Plugin (@mpxjs/babel-plugin-inject-page-events)"]:::transformation
    end

    %% Runtime Environment
    subgraph "Runtime Environment"
        core["Mpx Core (Runtime)"]:::runtime
        apiProxy["Platform API Adapter (api-proxy)"]:::runtime
        store["State Management (Store)"]:::runtime
        pinia["State Management (Pinia)"]:::runtime
        utils["Utility Modules (Utils)"]:::runtime
        fetchMod["Network Requests (fetch)"]:::runtime
        unocss["Unocss Support"]:::runtime
    end

    %% Documentation and Examples
    subgraph "Documentation and Examples"
        docs["Docs (docs-vitepress)"]:::documentation
        ex["Examples"]:::documentation
    end

    %% Platform Targets
    subgraph "Platform Targets"
        wechat["WeChat"]:::target
        ali["AliApp"]:::target
        baidu["Baidu"]:::target
        web["Web"]:::target
    end

    %% Connections from Developer Environment to Build Layer
    mpxCLI -->|"scaffolds"| webpackPlugin
    mpxCLI -->|"scaffolds"| babelPlugin

    %% Connections from Build Layer to Runtime Environment
    webpackPlugin -->|"transforms"| core
    babelPlugin -->|"transforms"| core

    %% Connections within Runtime Environment
    core -->|"integrates"| apiProxy
    core -->|"integrates"| store
    core -->|"integrates"| pinia
    core -->|"calls"| utils
    core -->|"adapts"| fetchMod
    core -->|"supports"| unocss

    %% Connection from Runtime to Platform Targets
    core -->|"deploys"| wechat
    core -->|"deploys"| ali
    core -->|"deploys"| baidu
    core -->|"deploys"| web

    %% Developer reference to Documentation and Examples
    mpxCLI -->|"refersTo"| docs
    mpxCLI -->|"refersTo"| ex

    %% Class Definitions for Colors and Styles
    classDef developer fill:#b3e5fc,stroke:#039be5,stroke-width:2px;
    classDef transformation fill:#ffe082,stroke:#ffb300,stroke-width:2px;
    classDef runtime fill:#c5e1a5,stroke:#7cb342,stroke-width:2px;
    classDef documentation fill:#d1c4e9,stroke:#7e57c2,stroke-width:2px;
    classDef target fill:#ffccbc,stroke:#ff7043,stroke-width:2px;

    %% Click Events
    click mpxCLI "https://github.com/didi/mpx/tree/master/legacy/cli"
    click webpackPlugin "https://github.com/didi/mpx/tree/master/packages/webpack-plugin"
    click babelPlugin "https://github.com/didi/mpx/tree/master/packages/babel-plugin-inject-page-events"
    click core "https://github.com/didi/mpx/tree/master/packages/core"
    click apiProxy "https://github.com/didi/mpx/tree/master/packages/api-proxy"
    click store "https://github.com/didi/mpx/tree/master/packages/store"
    click pinia "https://github.com/didi/mpx/tree/master/packages/pinia"
    click utils "https://github.com/didi/mpx/tree/master/packages/utils"
    click fetchMod "https://github.com/didi/mpx/tree/master/packages/fetch"
    click unocss "https://github.com/didi/mpx/tree/master/packages/unocss-plugin"
    click docs "https://github.com/didi/mpx/tree/master/docs-vitepress"
    click ex "https://github.com/didi/mpx/tree/master/examples"
```
