Pyodide Architecture: A Narrative Pattern Language

Engineering Blueprints for Browser-Native Python Applications

Overview

This project is the definitive architectural reference for building production-ready, client-side Python applications. It goes beyond simple code snippets to provide a Narrative Pattern Language for the browser-native ecosystem.

Each pattern documents the Forces (competing constraints), the Engineering Solution, and the Resulting Context of specific implementations.

The core philosophy is Python-Centric Development: providing the tools to build complex, reactive, and high-performance front-ends without leaving the Python ecosystem.

🏛️ Narrative Pattern Language

For a deep dive into the architectural reasoning behind these implementations, see our Pattern Index.

1. Architectural & UI Patterns

• Reactive UI (VDOM, Signals, Observer): Three 100% Python implementations for syncing state to the DOM.
• Synchronous-Looking Async UI: Linear Python logic that offloads heavy work to background threads using async/await.
• Test Suite Isolation: Strategies for running Playwright and pytest-asyncio without event loop conflicts.
• Console Log Capturing: Bridging browser output to Python test reports.

2. High Performance & Workers

• Worker Pool: Scaling Pyodide across multiple CPU cores with task queuing.
• Shared Memory (SAB): True zero-copy coordination between JS, Python, and the GPU.
• WebGPU Compute: Direct GPU acceleration for NumPy-based workloads.
• Worker RPC (Comlink): Object-oriented communication between main and worker threads.

3. Loading & Persistence

• Persistent File System (IDBFS): Mounting IndexedDB so Python file I/O survives page reloads.
• Bootstrapping & Warm Starts: Optimizing perceived performance via background loading.
• Service Worker Caching: Local caching of the Pyodide runtime and Python wheels.
• Worker Load Failure: Robust detection of network and CORS issues in workers.

🛠️ The Unified Python Bridge

All patterns leverage src/pyodide_app/bridge/, a modular utility package that provides:

• bridge.reactivity.Signal: Fine-grained reactivity.
• bridge.reactivity.observable: Dataclass-based state management.
• bridge.vdom.PythonVDOM: A pure Python Virtual DOM engine.
• bridge.core.keep_alive: Automatic proxy lifecycle management to prevent GC memory leaks.

🚀 Getting Started

Installation

# Clone and setup environment
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
playwright install chromium

# Build required wheels
python -m pip install build
python -m build
python -m build _my_local_package

Running Tests

We use a comprehensive test suite that mirrors the pattern structure:

# Run all verified patterns
pytest tests/patterns

# Run specific category
pytest tests/patterns/architectural

✨ Engineering Standards

• 100% Typed: All source files use strict Python type hinting verified by mypy.
• Linted & Formatted: Enforcement via ruff and pre-commit hooks.
• CI/CD Matrix: Every pattern is tested against Pyodide versions 0.26, 0.27, and 0.28.

Contributing

Contributions are welcome! If you have a new architectural pattern for Pyodide, please see our contributing guide.