# marimo-team/marimo architecture

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

- Interactive diagram: https://gitdiagram.com/marimo-team/marimo
- Repository: https://github.com/marimo-team/marimo

## Overview

marimo is a reactive Python notebook platform: users edit or run Python/SQL cells, and dependent cells rerun to keep notebook state and outputs consistent. Its product spans the browser editor, notebook model, reactive runtime, data/UI integrations, and deployment modes including scripts, web apps, slides, and browser WASM. The README supports these capability branches; source-index imports and excerpts provide narrower implementation links. Several major backend areas were not sampled, so their internal calls are intentionally not inferred.

Main entry points: [`marimo/_runtime`](https://github.com/marimo-team/marimo/tree/main/marimo/_runtime) (Kernel runtime), [`frontend/src/components/editor/app-container.tsx`](https://github.com/marimo-team/marimo/blob/main/frontend/src/components/editor/app-container.tsx) (Notebook editor), [`marimo/_ast/cell_manager.py`](https://github.com/marimo-team/marimo/blob/main/marimo/_ast/cell_manager.py) (Cell manager), [`marimo/_runtime/commands.py`](https://github.com/marimo-team/marimo/blob/main/marimo/_runtime/commands.py) (Kernel command protocol)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_editor["Notebook editor"]
  node_editor_ui["Notebook editor<br/>[app-container.tsx]"]
  node_cell_ui["Cell editing and run controls<br/>[useRunCells.ts]"]
  node_chat_ui["Editor AI features<br/>[chat-panel.tsx]"]
end

subgraph group_execution["Notebook execution"]
  node_notebook["Notebook app model<br/>[app.py]"]
  node_cells["Cell manager<br/>[cell_manager.py]"]
  node_commands["Kernel command protocol<br/>[commands.py]"]
  node_session["Session management<br/>[session_manager.py]"]
  node_kernel["Kernel runtime"]
end

subgraph group_data["Data and integrations"]
  node_ui_elements["Interactive UI elements"]
  node_dataframes["Dataframe tables<br/>[table_manager.py]"]
  node_sql["SQL engines<br/>[get_engines.py]"]
  node_storage_callbacks["External storage callbacks"]
  node_storage_backend["External storage backends<br/>[storage.py]"]
  node_storage_ui["Storage inspector"]
end

subgraph group_platform["Configuration and sharing"]
  node_packages["Package management"]
  node_config["Configuration manager<br/>[manager.py]"]
  node_virtual_files[("Virtual file storage<br/>[storage.py]")]
  node_deploy["Script and app deployment"]
  node_wasm["Browser WASM runtime<br/>[pyodide_session.py]"]
end

subgraph group_assist["AI and tooling"]
  node_agent_pair["Agent pairing service<br/>[main.py]"]
  node_lint["Notebook linting<br/>[rule_engine.py]"]
end

node_author(("Notebook author"))
node_browser(("Browser user"))
node_database[("External data sources")]
node_ai_agent(("External AI agent"))

node_author -->|"edits notebook"| node_editor_ui
node_browser -->|"interacts with"| node_editor_ui
node_editor_ui -->|"edits cells"| node_cell_ui
node_cell_ui -->|"runs cells"| node_notebook
node_notebook -->|"manages cells"| node_cells
node_cells -->|"emits changes"| node_commands
node_session -->|"dispatches commands"| node_commands
node_commands -->|"instructs runtime"| node_kernel
node_kernel -->|"runs dependents"| node_cells
node_kernel -->|"updates elements"| node_ui_elements
node_kernel -->|"serves table data"| node_dataframes
node_kernel -->|"discovers engines"| node_sql
node_database -->|"provides connections"| node_sql
node_storage_callbacks -->|"lists and downloads"| node_storage_backend
node_storage_callbacks -->|"registers previews"| node_virtual_files
node_storage_ui -->|"inspects storage"| node_editor_ui
node_kernel -->|"installs packages"| node_packages
node_session -->|"loads settings"| node_config
node_author -->|"deploys notebook"| node_deploy
node_author -->|"runs in browser"| node_wasm
node_chat_ui -.->|"pairs with agents"| node_agent_pair
node_ai_agent -->|"connects to"| node_agent_pair
node_author -.->|"checks notebook"| node_lint

click node_editor_ui "https://github.com/marimo-team/marimo/blob/main/frontend/src/components/editor/app-container.tsx"
click node_cell_ui "https://github.com/marimo-team/marimo/blob/main/frontend/src/components/editor/cell/useRunCells.ts"
click node_chat_ui "https://github.com/marimo-team/marimo/blob/main/frontend/src/components/chat/chat-panel.tsx"
click node_notebook "https://github.com/marimo-team/marimo/blob/main/marimo/_ast/app.py"
click node_cells "https://github.com/marimo-team/marimo/blob/main/marimo/_ast/cell_manager.py"
click node_commands "https://github.com/marimo-team/marimo/blob/main/marimo/_runtime/commands.py"
click node_session "https://github.com/marimo-team/marimo/blob/main/marimo/_server/session_manager.py"
click node_kernel "https://github.com/marimo-team/marimo/tree/main/marimo/_runtime"
click node_ui_elements "https://github.com/marimo-team/marimo/tree/main/marimo/_plugins/ui"
click node_dataframes "https://github.com/marimo-team/marimo/blob/main/marimo/_plugins/ui/_impl/tables/table_manager.py"
click node_sql "https://github.com/marimo-team/marimo/blob/main/marimo/_sql/get_engines.py"
click node_storage_callbacks "https://github.com/marimo-team/marimo/blob/main/marimo/_runtime/callbacks/external_storage.py"
click node_storage_backend "https://github.com/marimo-team/marimo/blob/main/marimo/_data/_external_storage/storage.py"
click node_storage_ui "https://github.com/marimo-team/marimo/blob/main/frontend/src/components/storage/storage-inspector.tsx"
click node_packages "https://github.com/marimo-team/marimo/blob/main/marimo/_runtime/packages/pypi_package_manager.py"
click node_config "https://github.com/marimo-team/marimo/blob/main/marimo/_config/manager.py"
click node_virtual_files "https://github.com/marimo-team/marimo/blob/main/marimo/_runtime/virtual_file/storage.py"
click node_deploy "https://github.com/marimo-team/marimo/tree/main/marimo/_server"
click node_wasm "https://github.com/marimo-team/marimo/blob/main/marimo/_pyodide/pyodide_session.py"
click node_agent_pair "https://github.com/marimo-team/marimo/blob/main/marimo/_mcp/code_server/main.py"
click node_lint "https://github.com/marimo-team/marimo/blob/main/marimo/_lint/rule_engine.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_editor_ui,node_cell_ui,node_chat_ui,node_browser toneBlue
class node_notebook,node_cells,node_commands,node_session,node_kernel,node_database toneAmber
class node_ui_elements,node_dataframes,node_sql,node_storage_callbacks,node_storage_backend,node_storage_ui toneMint
class node_packages,node_config,node_virtual_files,node_deploy,node_wasm toneRose
class node_agent_pair,node_lint,node_author,node_ai_agent toneIndigo
```

## Components

### Notebook editor

- [Notebook editor](https://github.com/marimo-team/marimo/blob/main/frontend/src/components/editor/app-container.tsx): `frontend/src/components/editor/app-container.tsx`
- [Cell editing and run controls](https://github.com/marimo-team/marimo/blob/main/frontend/src/components/editor/cell/useRunCells.ts): `frontend/src/components/editor/cell/useRunCells.ts`
- [Editor AI features](https://github.com/marimo-team/marimo/blob/main/frontend/src/components/chat/chat-panel.tsx): `frontend/src/components/chat/chat-panel.tsx`

### Notebook execution

- [Notebook app model](https://github.com/marimo-team/marimo/blob/main/marimo/_ast/app.py): `marimo/_ast/app.py`
- [Cell manager](https://github.com/marimo-team/marimo/blob/main/marimo/_ast/cell_manager.py): `marimo/_ast/cell_manager.py`
- [Kernel command protocol](https://github.com/marimo-team/marimo/blob/main/marimo/_runtime/commands.py): `marimo/_runtime/commands.py`
- [Session management](https://github.com/marimo-team/marimo/blob/main/marimo/_server/session_manager.py): `marimo/_server/session_manager.py`
- [Kernel runtime](https://github.com/marimo-team/marimo/tree/main/marimo/_runtime): `marimo/_runtime`

### Data and integrations

- [Interactive UI elements](https://github.com/marimo-team/marimo/tree/main/marimo/_plugins/ui): `marimo/_plugins/ui`
- [Dataframe tables](https://github.com/marimo-team/marimo/blob/main/marimo/_plugins/ui/_impl/tables/table_manager.py): `marimo/_plugins/ui/_impl/tables/table_manager.py`
- [SQL engines](https://github.com/marimo-team/marimo/blob/main/marimo/_sql/get_engines.py): `marimo/_sql/get_engines.py`
- [External storage callbacks](https://github.com/marimo-team/marimo/blob/main/marimo/_runtime/callbacks/external_storage.py): `marimo/_runtime/callbacks/external_storage.py`
- [External storage backends](https://github.com/marimo-team/marimo/blob/main/marimo/_data/_external_storage/storage.py): `marimo/_data/_external_storage/storage.py`
- [Storage inspector](https://github.com/marimo-team/marimo/blob/main/frontend/src/components/storage/storage-inspector.tsx): `frontend/src/components/storage/storage-inspector.tsx`

### Configuration and sharing

- [Package management](https://github.com/marimo-team/marimo/blob/main/marimo/_runtime/packages/pypi_package_manager.py): `marimo/_runtime/packages/pypi_package_manager.py`
- [Configuration manager](https://github.com/marimo-team/marimo/blob/main/marimo/_config/manager.py): `marimo/_config/manager.py`
- [Virtual file storage](https://github.com/marimo-team/marimo/blob/main/marimo/_runtime/virtual_file/storage.py): `marimo/_runtime/virtual_file/storage.py`
- [Script and app deployment](https://github.com/marimo-team/marimo/tree/main/marimo/_server): `marimo/_server`
- [Browser WASM runtime](https://github.com/marimo-team/marimo/blob/main/marimo/_pyodide/pyodide_session.py): `marimo/_pyodide/pyodide_session.py`

### AI and tooling

- [Agent pairing service](https://github.com/marimo-team/marimo/blob/main/marimo/_mcp/code_server/main.py): `marimo/_mcp/code_server/main.py`
- [Notebook linting](https://github.com/marimo-team/marimo/blob/main/marimo/_lint/rule_engine.py): `marimo/_lint/rule_engine.py`

### Other components

- **Notebook author**
- **Browser user**
- **External data sources**
- **External AI agent**

## Connections

- Notebook author → Notebook editor: edits notebook
- Browser user → Notebook editor: interacts with
- Notebook editor → Cell editing and run controls: edits cells
- Cell editing and run controls → Notebook app model: runs cells
- Notebook app model → Cell manager: manages cells (evidence: `marimo/_ast/cell_manager.py`)
- Cell manager → Kernel command protocol: emits changes (evidence: `marimo/_ast/cell_manager.py`)
- Session management → Kernel command protocol: dispatches commands (evidence: `marimo/_server/session_manager.py`)
- Kernel command protocol → Kernel runtime: instructs runtime (evidence: `marimo/_runtime/callbacks/external_storage.py`)
- Kernel runtime → Cell manager: runs dependents
- Kernel runtime → Interactive UI elements: updates elements
- Kernel runtime → Dataframe tables: serves table data (evidence: `marimo/_plugins/ui/_impl/tables/table_manager.py`)
- Kernel runtime → SQL engines: discovers engines (evidence: `marimo/_sql/get_engines.py`)
- External data sources → SQL engines: provides connections
- External storage callbacks → External storage backends: lists and downloads (evidence: `marimo/_runtime/callbacks/external_storage.py`)
- External storage callbacks → Virtual file storage: registers previews (evidence: `marimo/_runtime/callbacks/external_storage.py`)
- Storage inspector → Notebook editor: inspects storage (evidence: `frontend/src/components/storage/storage-inspector.tsx`)
- Kernel runtime → Package management: installs packages (evidence: `marimo/_runtime/packages/pypi_package_manager.py`)
- Session management → Configuration manager: loads settings (evidence: `marimo/_server/session_manager.py`)
- Notebook author → Script and app deployment: deploys notebook
- Notebook author → Browser WASM runtime: runs in browser
- Editor AI features → Agent pairing service: pairs with agents
- External AI agent → Agent pairing service: connects to (evidence: `marimo/_mcp/code_server/main.py`)
- Notebook author → Notebook linting: checks notebook
