# cglacet/pyodide architecture

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

- Interactive diagram: https://gitdiagram.com/cglacet/pyodide
- Repository: https://github.com/cglacet/pyodide

## Overview

Pyodide runs Python and scientific packages in a browser through WebAssembly, exposing Python execution and JavaScript/Web API interoperability. The main workflow is browser code loading the runtime, submitting Python, and receiving results through the JavaScript-facing conversion layer. Separate capabilities include loading built-in packages, installing pure-Python wheels with micropip, and rendering Matplotlib figures to HTML canvas. The tree and excerpts support the bootstrap and conversion links shown; unsampled runtime internals are represented only where documented or named by the tree.

Main entry points: [`src/main.c`](https://github.com/cglacet/pyodide/blob/master/src/main.c) (Python WebAssembly), [`src/type_conversion/jsproxy.c`](https://github.com/cglacet/pyodide/blob/master/src/type_conversion/jsproxy.c) (JavaScript proxies), [`src/pyodide.js`](https://github.com/cglacet/pyodide/blob/master/src/pyodide.js) (Runtime loader), [`src/type_conversion/runpython.c`](https://github.com/cglacet/pyodide/blob/master/src/type_conversion/runpython.c) (Python execution)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime bootstrap"]
  node_pyodide_js["Runtime loader<br/>[pyodide.js]"]
  node_wasm_python["Python WebAssembly<br/>[main.c]"]
  node_worker["Worker entry<br/>[webworker.js]"]
  node_runpython["Python execution<br/>[runpython.c]"]
  node_pyodide_python["Python API<br/>[pyodide.py]"]
end

subgraph group_interop["Python JavaScript bridge"]
  node_hiwire["JavaScript value handles<br/>[hiwire.c]"]
  node_js2python["JS to Python<br/>[js2python.c]"]
  node_python2js["Python to JS<br/>[python2js.c]"]
  node_jsproxy["JavaScript proxies<br/>[jsproxy.c]"]
  node_pyproxy["Python proxies<br/>[pyproxy.c]"]
end

subgraph group_packages["Package access"]
  node_package_loader["Built-in package loader<br/>[pyodide.js]"]
  node_micropip["Wheel installer<br/>[micropip.py]"]
end

subgraph group_visualization["Browser capabilities"]
  node_matplotlib_backend["Canvas plotting backend<br/>[wasm_backend.py]"]
end

node_browser_user(("Browser caller"))
node_web_apis["Browser Web APIs"]
node_package_catalog["Package catalog"]
node_wheel_source["Wheel sources"]
node_html_canvas["HTML canvas"]

node_browser_user -->|"loads runtime"| node_pyodide_js
node_pyodide_js -->|"loads WebAssembly"| node_wasm_python
node_browser_user -->|"submits Python"| node_runpython
node_pyodide_js -->|"exposes execution"| node_runpython
node_worker -->|"imports loader"| node_pyodide_js
node_worker -->|"dispatches script"| node_runpython
node_wasm_python -->|"initializes handles"| node_hiwire
node_wasm_python -->|"initializes conversion"| node_js2python
node_wasm_python -->|"initializes conversion"| node_python2js
node_wasm_python -->|"initializes proxies"| node_jsproxy
node_wasm_python -->|"initializes proxies"| node_pyproxy
node_jsproxy -->|"uses handles"| node_hiwire
node_jsproxy -->|"converts arguments"| node_python2js
node_jsproxy -->|"converts results"| node_js2python
node_pyodide_python -->|"provides Python API"| node_runpython
node_package_loader -->|"reads metadata"| node_package_catalog
node_package_loader -->|"loads packages"| node_wasm_python
node_micropip -->|"reads built-in metadata"| node_package_catalog
node_micropip -->|"fetches wheels"| node_wheel_source
node_micropip -->|"installs wheels"| node_wasm_python
node_jsproxy -->|"accesses objects"| node_web_apis
node_matplotlib_backend -->|"renders figures"| node_html_canvas
node_matplotlib_backend -->|"uses DOM"| node_web_apis

click node_pyodide_js "https://github.com/cglacet/pyodide/blob/master/src/pyodide.js"
click node_wasm_python "https://github.com/cglacet/pyodide/blob/master/src/main.c"
click node_worker "https://github.com/cglacet/pyodide/blob/master/src/webworker.js"
click node_runpython "https://github.com/cglacet/pyodide/blob/master/src/type_conversion/runpython.c"
click node_pyodide_python "https://github.com/cglacet/pyodide/blob/master/src/pyodide.py"
click node_hiwire "https://github.com/cglacet/pyodide/blob/master/src/type_conversion/hiwire.c"
click node_js2python "https://github.com/cglacet/pyodide/blob/master/src/type_conversion/js2python.c"
click node_python2js "https://github.com/cglacet/pyodide/blob/master/src/type_conversion/python2js.c"
click node_jsproxy "https://github.com/cglacet/pyodide/blob/master/src/type_conversion/jsproxy.c"
click node_pyproxy "https://github.com/cglacet/pyodide/blob/master/src/type_conversion/pyproxy.c"
click node_package_loader "https://github.com/cglacet/pyodide/blob/master/src/pyodide.js"
click node_micropip "https://github.com/cglacet/pyodide/blob/master/packages/micropip/micropip/micropip.py"
click node_matplotlib_backend "https://github.com/cglacet/pyodide/blob/master/packages/matplotlib/src/wasm_backend.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_pyodide_js,node_wasm_python,node_worker,node_runpython,node_pyodide_python,node_browser_user,node_web_apis toneBlue
class node_hiwire,node_js2python,node_python2js,node_jsproxy,node_pyproxy toneAmber
class node_package_loader,node_micropip toneMint
class node_matplotlib_backend toneRose
class node_package_catalog,node_wheel_source,node_html_canvas toneIndigo
```

## Components

### Runtime bootstrap

- [Runtime loader](https://github.com/cglacet/pyodide/blob/master/src/pyodide.js): `src/pyodide.js`
- [Python WebAssembly](https://github.com/cglacet/pyodide/blob/master/src/main.c): `src/main.c`
- [Worker entry](https://github.com/cglacet/pyodide/blob/master/src/webworker.js): `src/webworker.js`
- [Python execution](https://github.com/cglacet/pyodide/blob/master/src/type_conversion/runpython.c): `src/type_conversion/runpython.c`
- [Python API](https://github.com/cglacet/pyodide/blob/master/src/pyodide.py): `src/pyodide.py`

### Python JavaScript bridge

- [JavaScript value handles](https://github.com/cglacet/pyodide/blob/master/src/type_conversion/hiwire.c): `src/type_conversion/hiwire.c`
- [JS to Python](https://github.com/cglacet/pyodide/blob/master/src/type_conversion/js2python.c): `src/type_conversion/js2python.c`
- [Python to JS](https://github.com/cglacet/pyodide/blob/master/src/type_conversion/python2js.c): `src/type_conversion/python2js.c`
- [JavaScript proxies](https://github.com/cglacet/pyodide/blob/master/src/type_conversion/jsproxy.c): `src/type_conversion/jsproxy.c`
- [Python proxies](https://github.com/cglacet/pyodide/blob/master/src/type_conversion/pyproxy.c): `src/type_conversion/pyproxy.c`

### Package access

- [Built-in package loader](https://github.com/cglacet/pyodide/blob/master/src/pyodide.js): `src/pyodide.js`
- [Wheel installer](https://github.com/cglacet/pyodide/blob/master/packages/micropip/micropip/micropip.py): `packages/micropip/micropip/micropip.py`

### Browser capabilities

- [Canvas plotting backend](https://github.com/cglacet/pyodide/blob/master/packages/matplotlib/src/wasm_backend.py): `packages/matplotlib/src/wasm_backend.py`

### Other components

- **Browser caller**
- **Browser Web APIs**
- **Package catalog**
- **Wheel sources**
- **HTML canvas**

## Connections

- Browser caller → Runtime loader: loads runtime
- Runtime loader → Python WebAssembly: loads WebAssembly
- Browser caller → Python execution: submits Python
- Runtime loader → Python execution: exposes execution
- Worker entry → Runtime loader: imports loader
- Worker entry → Python execution: dispatches script
- Python WebAssembly → JavaScript value handles: initializes handles
- Python WebAssembly → JS to Python: initializes conversion
- Python WebAssembly → Python to JS: initializes conversion
- Python WebAssembly → JavaScript proxies: initializes proxies
- Python WebAssembly → Python proxies: initializes proxies
- JavaScript proxies → JavaScript value handles: uses handles
- JavaScript proxies → Python to JS: converts arguments
- JavaScript proxies → JS to Python: converts results
- Python API → Python execution: provides Python API
- Built-in package loader → Package catalog: reads metadata
- Built-in package loader → Python WebAssembly: loads packages
- Wheel installer → Package catalog: reads built-in metadata
- Wheel installer → Wheel sources: fetches wheels
- Wheel installer → Python WebAssembly: installs wheels
- JavaScript proxies → Browser Web APIs: accesses objects
- Canvas plotting backend → HTML canvas: renders figures
- Canvas plotting backend → Browser Web APIs: uses DOM