# jupyterlite/demo architecture

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

- Interactive diagram: https://gitdiagram.com/jupyterlite/demo
- Repository: https://github.com/jupyterlite/demo

## Overview

##### Project Type & Purpose
- This is a **static site demo** of JupyterLite—a 100% client-side Jupyter distribution that runs entirely in the browser (no Python server).
- It showcases three kernels (Pyodide/Python, JavaScript, p5) and example notebooks & data under `content/`.
- It is built and deployed automatically to GitHub Pages via a GitHub Actions workflow.

##### File Structure Highlights
Top-level:
- `.github/workflows/deploy.yml` → CI/CD pipeline that builds and pushes the static site to the `gh-pages` branch.
- `repl/jupyter-lite.json` → JupyterLite configuration (which kernels/extensions to include).
- `content/` → All example notebooks (`.ipynb`) and data files served by the site.
- `requirements.txt` → Lists Python-side dependencies baked into the Pyodide environment.
- `.nojekyll` → Ensures GitHub Pages serve raw files without Jekyll processing.

##### Key Architectural Patterns
- **Static-site architecture**: source repo → CI build → GitHub Pages (CDN) → browser.
- **Client-side compute**: WebAssembly (Pyodide) loads in browser, runs Python.
- **Modular kernels**: each kernel (Python, JS, p5) is an independent WASM/JS bundle loaded on demand.

##### Main Components & Interactions
a. **Developer/GitHub Repo**
– Hosts source: content, config, notebook assets, workflow.
– Push triggers GitHub Actions.
b. **CI/CD (GitHub Actions)**
– `deploy.yml` job:
· Installs build dependencies
· Invokes JupyterLite build (bundles HTML/JS/CSS + kernels + content)
· Publishes to `gh-pages` branch
c. **Hosting (GitHub Pages / CDN)**
– Serves static files over HTTPS.
– `.nojekyll` ensures direct file access.
d. **Client (Browser)**
– Downloads HTML/CSS/JS assets.
– JupyterLite front-end initializes.
– Loads kernels:
· **Pyodide Kernel**: Python via WebAssembly + `requirements.txt` libs
· **JavaScript Kernel**: pure JS REPL
· **p5 Kernel**: p5.js graphics demos
– Loads notebook UI, mounts `content/` as file system.
– User interacts with notebooks; code sends messages to kernels via in-browser messaging.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Developer"
        Dev["Developer"]:::external
    end

    subgraph "GitHub Repository"
        Repo["GitHub Repo"]:::external
        GI[".gitignore"]:::external
        RD["README.md"]:::external
        Config["JupyterLite Configuration"]:::cicd
        NoJ[".nojekyll"]:::cicd
        Req["requirements.txt"]:::cicd
        ContentSrc["content/ (source)"]:::content
        Dev -->|git push| Repo
        Repo --> GI
        Repo --> RD
        Repo --> Config
        Repo --> NoJ
        Repo --> Req
        Repo --> ContentSrc
        click GI "https://github.com/jupyterlite/demo/blob/main/.gitignore"
        click RD "https://github.com/jupyterlite/demo/blob/main/README.md"
        click Config "https://github.com/jupyterlite/demo/blob/main/repl/jupyter-lite.json"
        click NoJ "https://github.com/jupyterlite/demo/blob/main/.nojekyll"
        click Req "https://github.com/jupyterlite/demo/blob/main/requirements.txt"
        click ContentSrc "https://github.com/jupyterlite/demo/tree/main/content/"
    end

    Repo -->|push triggers| CI["CI/CD Pipeline"]:::cicd
    click CI "https://github.com/jupyterlite/demo/blob/main/.github/workflows/deploy.yml"
    CI -->|build static site| Build["Static Build Output"]:::cicd
    CI -->|publishes to gh-pages| CDN["GitHub Pages/CDN"]:::hosting

    CDN -->|HTTP GET| Browser["Browser Client"]:::client
    Browser --> FL["JupyterLite Front-end"]:::client

    FL -->|mounts| FS["In-browser File System"]:::client

    subgraph "Kernels"
        PK["Pyodide WASM Kernel"]:::kernel
        JK["JavaScript Kernel"]:::kernel
        P5["p5.js Kernel"]:::kernel
    end
    FL -->|WASM load| PK
    FL -->|JS load| JK
    FL -->|p5 load| P5

    subgraph "Content Files"
        JSDemo["JavaScript Notebook"]:::content
        P5Demo["p5 Notebook"]:::content
        DataF["Data Files"]:::content
        PyNB["Pyodide Notebooks"]:::content
        Py2D["pyb2d Tutorials"]:::content
        click JSDemo "https://github.com/jupyterlite/demo/blob/main/content/javascript.ipynb"
        click P5Demo "https://github.com/jupyterlite/demo/blob/main/content/p5.ipynb"
        click DataF "https://github.com/jupyterlite/demo/tree/main/content/data/"
        click PyNB "https://github.com/jupyterlite/demo/tree/main/content/pyodide/"
        click Py2D "https://github.com/jupyterlite/demo/tree/main/content/pyodide/pyb2d/"
    end
    FS --> JSDemo
    FS --> P5Demo
    FS --> DataF
    FS --> PyNB
    FS --> Py2D

    classDef external fill:#cccccc,stroke:#666,stroke-width:1px
    classDef cicd fill:#f9c74f,stroke:#e09f3e,stroke-width:1px
    classDef hosting fill:#90e0ef,stroke:#457b9d,stroke-width:1px
    classDef client fill:#a8dadc,stroke:#1d3557,stroke-width:1px
    classDef kernel fill:#b5838d,stroke:#6d6875,stroke-width:1px
    classDef content fill:#e0ecff,stroke:#3a86ff,stroke-width:1px
```
