# mui/toolpad architecture

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

- Interactive diagram: https://gitdiagram.com/mui/toolpad
- Repository: https://github.com/mui/toolpad

## Overview

##### Project type and purpose
- This is a monorepo for “Toolpad,” a low-code dashboard builder.
- Toolpad Core: A React component library for dashboards (packages/toolpad-core).
- Toolpad Studio: A self-hosted low-code UI editor (packages/toolpad-studio) plus its runtime (packages/toolpad-studio-runtime and packages/toolpad-studio-components).
- CLI scaffolding: create-toolpad-app (packages/create-toolpad-app) to bootstrap new Toolpad projects.
- Utility libraries: toolpad-utils.
- Examples, playgrounds, docs (docs/ and examples/).
- CI/CD and build scripts for testing, linting, publishing.

##### File structure analysis
- Monorepo root: pnpm-workspace, lerna.json, scripts/, .github/ and .circleci/ define CI workflows.
- packages/: each package encapsulates a distinct component (Core, Studio, CLI, Utils, etc.).
- docs/: Next.js-based documentation site.
- examples/ & playground/: sample Toolpad apps demonstrating usage.
- scripts/: custom build and release orchestration.
- test/: integration & visual test fixtures.

##### Key README insights
- “Toolpad Core” for React dashboards.
- “Toolpad Studio” low-code builder with drag-drop, built on Toolpad Core.
- CLI commands generate Core or Studio projects.
- Documentation and examples are hosted via Next.js/docs.

a. Main components
- Monorepo Orchestrator: pnpm/Lerna, root-level scripts, CI pipelines.
- CLI Scaffolder: create-toolpad-app (template engine, project generator).
- Toolpad Core Library: React components, theming, routing abstractions.
- Toolpad Studio Frontend: React-based low-code editor UI.
- Toolpad Studio Server: Node.js server providing data sources, function runtimes, project RPC.
- Studio Runtime: Browser/runtime engine for running published Toolpad apps.
- Studio Components Package: Pre-built UI elements for Studio and runtime.
- Utility Library: toolpad-utils (shared hooks, HTTP adapters, file utilities).
- Documentation Site: Next.js app under docs/.
- Example Apps & Playground: sample Next.js/Vite projects for reference.

b. Relationships and interactions
- CLI → generates new project using Core or Studio templates.
- Generated apps → import Toolpad Core (UI), Studio Runtime (if low-code), and Utils.
- Studio Frontend ↔ Studio Server over HTTP/RPC for project editing.
- Studio Server → manages DataManager, FunctionsManager, EnvManager, Vite virtual modules.
- Studio Runtime (in user projects) → executes functions, queries, and renders pages.
- Documentation Site → imports docs data and compiles examples.
- CI/CD pipelines → run lint/test/build for all packages and publish to npm.

c. Architectural patterns and design principles
- Monorepo modularization: each package is isolated, with explicit dependencies.
- Package templates & code generation (CLI).
- Client-Server separation in Studio: Editor UI vs. backend project runner.
- Library vs. Application: Core & Utils are libraries; Studio is an application with frontend and backend.
- Micro-frontend feel: Studio Runtime runs inside scaffolded apps.
- Standard web patterns: Next.js for docs, React for UI, Vite for dev.

d. Relevant technologies
- Package management: pnpm, Lerna.
- Build/test: TypeScript, tsup, Vitest, Playwright.
- UI: React, Material-UI.
- Server: Node.js, Express/RPC.
- Docs: Next.js, markdown.
- CI: GitHub Actions, CircleCI.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Monorepo Orchestrator
    subgraph "Monorepo Orchestrator"
        direction TB
        Orch_Lerna["lerna.json"]:::tool
        Orch_Pnpm["pnpm-workspace.yaml"]:::tool
        Orch_Scripts["scripts/"]:::tool
        Orch_GH[".github/"]:::tool
        Orch_Circle[".circleci/"]:::tool
    end

    %% Libraries Layer
    subgraph "Libraries" 
        direction TB
        Core["Toolpad Core Library"]:::lib
        Utils["Utility Library (toolpad-utils)"]:::lib
        Studio_Comp["Studio Components Package"]:::lib
        Runtime_Eng["Studio Runtime Engine"]:::lib
    end

    %% Applications Layer
    subgraph "Applications & Tools"
        direction TB
        CLI["CLI Scaffolder"]:::tool
        Studio_FE["Toolpad Studio Frontend"]:::app
        Studio_BE["Toolpad Studio Server"]:::server
        Docs["Documentation Site"]:::app
        Examples["Example Apps & Playground"]:::app
    end

    %% CI/CD
    CI["CI/CD Pipelines"]:::tool

    %% Connections
    CI -->|"runs build/test"| Core
    CI -->|"runs build/test"| Utils
    CI -->|"runs build/test"| Studio_Comp
    CI -->|"runs build/test"| Runtime_Eng
    CI -->|"runs build/test"| Studio_FE
    CI -->|"runs build/test"| Studio_BE
    CI -->|"runs build/test"| Docs
    CI -->|"runs build/test"| Examples

    Orch_Lerna -->|"manages workspace"| Core
    Orch_Pnpm -->|"manages workspace"| Utils
    Orch_Scripts -->|"orchestrates"| Studio_Comp
    Orch_GH -->|"CI workflows"| CI
    Orch_Circle -->|"CI workflows"| CI

    CLI -->|"generates project"| Examples
    Examples -->|"imports"| Core
    Examples -->|"imports"| Runtime_Eng
    Examples -->|"imports"| Utils

    Studio_FE -->|"RPC/HTTP"| Studio_BE
    Studio_BE -->|"RPC/HTTP"| Studio_FE

    Studio_FE -->|"depends on"| Studio_Comp
    Studio_FE -->|"depends on"| Runtime_Eng
    Studio_FE -->|"uses"| Utils

    Docs -->|"imports markdown/data"| Examples
    Docs -->|"depends on"| Core

    %% Click Events
    click Orch_Lerna "https://github.com/mui/toolpad/blob/master/lerna.json"
    click Orch_Pnpm "https://github.com/mui/toolpad/blob/master/pnpm-workspace.yaml"
    click Orch_Scripts "https://github.com/mui/toolpad/tree/master/scripts/"
    click Orch_GH "https://github.com/mui/toolpad/tree/master/.github/"
    click Orch_Circle "https://github.com/mui/toolpad/tree/master/.circleci/"

    click CLI "https://github.com/mui/toolpad/tree/master/packages/create-toolpad-app/"
    click KI_CLI_SRC "https://github.com/mui/toolpad/tree/master/packages/create-toolpad-app/src/"
    click KI_CLI_TEST "https://github.com/mui/toolpad/tree/master/packages/create-toolpad-app/tests/"

    click Core "https://github.com/mui/toolpad/tree/master/packages/toolpad-core/"
    click CP_Core_SRC "https://github.com/mui/toolpad/tree/master/packages/toolpad-core/src/"
    click CP_Core_TS "https://github.com/mui/toolpad/blob/master/packages/toolpad-core/tsconfig.json"
    click CP_Core_VITE "https://github.com/mui/toolpad/blob/master/packages/toolpad-core/vitest.config.mts"

    click Studio_FE "https://github.com/mui/toolpad/tree/master/packages/toolpad-studio/"
    click FE_SRC "https://github.com/mui/toolpad/tree/master/packages/toolpad-studio/src/"
    click FE_COMP "https://github.com/mui/toolpad/tree/master/packages/toolpad-studio/src/components/"
    click FE_TOOLPAD "https://github.com/mui/toolpad/tree/master/packages/toolpad-studio/src/toolpad/"
    click FE_RUNTIME "https://github.com/mui/toolpad/tree/master/packages/toolpad-studio/src/runtime/"
    click FE_SERVER_SRC "https://github.com/mui/toolpad/tree/master/packages/toolpad-studio/src/server/"
    click FE_CLI "https://github.com/mui/toolpad/tree/master/packages/toolpad-studio/cli/"
    click FE_PUBLIC "https://github.com/mui/toolpad/tree/master/packages/toolpad-studio/public/"

    click Studio_BE "https://github.com/mui/toolpad/tree/master/packages/toolpad-studio/src/server/"
    click BE_PRJ "https://github.com/mui/toolpad/blob/master/packages/toolpad-studio/src/server/projectRpcServer.ts"
    click BE_RUN "https://github.com/mui/toolpad/blob/master/packages/toolpad-studio/src/server/runtimeRpcServer.ts"
    click BE_DM "https://github.com/mui/toolpad/blob/master/packages/toolpad-studio/src/server/DataManager.ts"
    click BE_FM "https://github.com/mui/toolpad/blob/master/packages/toolpad-studio/src/server/FunctionsManager.ts"
    click BE_EM "https://github.com/mui/toolpad/blob/master/packages/toolpad-studio/src/server/EnvManager.ts"
    click BE_APP "https://github.com/mui/toolpad/blob/master/packages/toolpad-studio/src/server/toolpadAppServer.ts"

    click Runtime_Eng "https://github.com/mui/toolpad/tree/master/packages/toolpad-studio-runtime/"
    click RT_SRC "https://github.com/mui/toolpad/tree/master/packages/toolpad-studio-runtime/src/"
    click RT_RUNTIME "https://github.com/mui/toolpad/blob/master/packages/toolpad-studio-runtime/src/runtime.tsx"
    click RT_JS "https://github.com/mui/toolpad/blob/master/packages/toolpad-studio-runtime/src/jsRuntime.tsx"
    click RT_SVRUNTIME "https://github.com/mui/toolpad/blob/master/packages/toolpad-studio-runtime/src/jsServerRuntime.tsx"
    click RT_SERV "https://github.com/mui/toolpad/blob/master/packages/toolpad-studio-runtime/src/server.ts"

    click Studio_Comp "https://github.com/mui/toolpad/tree/master/packages/toolpad-studio-components/"
    click SC_SRC "https://github.com/mui/toolpad/tree/master/packages/toolpad-studio-components/src/"
    click SC_INDEX "https://github.com/mui/toolpad/blob/master/packages/toolpad-studio-components/src/index.tsx"

    click Utils "https://github.com/mui/toolpad/tree/master/packages/toolpad-utils/"
    click UT_SRC "https://github.com/mui/toolpad/tree/master/packages/toolpad-utils/src/"
    click UT_TS "https://github.com/mui/toolpad/blob/master/packages/toolpad-utils/tsconfig.json"
    click UT_VITE "https://github.com/mui/toolpad/blob/master/packages/toolpad-utils/vitest.config.mts"

    click Docs "https://github.com/mui/toolpad/tree/master/docs/"
    click DOC_PG "https://github.com/mui/toolpad/tree/master/docs/pages/"
    click DOC_SRC "https://github.com/mui/toolpad/tree/master/docs/src/"
    click DOC_CFG "https://github.com/mui/toolpad/blob/master/docs/next.config.ts"
    click DOC_PKG "https://github.com/mui/toolpad/blob/master/docs/package.json"
    click DOC_SCR "https://github.com/mui/toolpad/tree/master/docs/scripts/"

    click Examples "https://github.com/mui/toolpad/tree/master/examples/"
    click Playground1 "https://github.com/mui/toolpad/tree/master/playground/nextjs-pages/"
    click Playground2 "https://github.com/mui/toolpad/tree/master/playground/nextjs/"
    click Playground3 "https://github.com/mui/toolpad/tree/master/playground/vite/"

    %% Styles
    classDef lib fill:#D2E3FC,stroke:#333,stroke-width:1px
    classDef app fill:#D5F5E3,stroke:#333,stroke-width:1px
    classDef server fill:#FDEBD0,stroke:#333,stroke-width:1px
    classDef tool fill:#E0E0E0,stroke:#333,stroke-width:1px
```
