# jupyter/try-jupyter architecture

> Architecture diagram of the GitHub repository jupyter/try-jupyter, 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/jupyter/try-jupyter
- Repository: https://github.com/jupyter/try-jupyter

## Overview

##### Project type and purpose
- This is a demo “Try Jupyter” full-stack front-end application with no traditional backend. It uses JupyterLite to embed a self-contained JupyterLab environment (Python, R kernels compiled to WebAssembly) entirely in the browser.
- Its purpose is to serve static assets (HTML, JS, CSS, notebooks, data) via GitHub Pages so that end users can run notebooks directly in-browser.

##### File structure
- Top-level config files
- .github/workflows/*.yml – CI workflows to build and deploy the static site
- .gitignore, build-environment.yml, environment-*.yml – environment configs
- readthedocs & conf.py – documentation build
- jupyter-lite.json, repl/jupyter-lite.json – JupyterLite front-end configuration
- content/
- data/ – sample datasets (CSV, GeoJSON, FASTA, Vega-Lite spec)
- notebooks/ – example notebooks (Intro, Lorenz, SQL, R)
- No server-side code: all logic lives in browser via WASM kernels

##### README for additional insights
- Confirms usage of JupyterLite and GitHub Pages
- Instructs users to edit notebooks via the live Try Jupyter page, then commit updates locally
- No mention of external APIs or microservices

a. Main components
- Static Web Host (GitHub Pages)
- Browser / Client
– JupyterLite Front-end (JupyterLab UI, JS bundle)
– Wasm Kernels (Python, R as WebAssembly modules)
– In-memory Virtual File System (Emscripten FS, persisted to IndexedDB)
– Sample content (notebooks & data) loaded at startup
- CI/CD Pipelines (GitHub Actions)
- Documentation Builder (ReadTheDocs)
b. Relationships & interactions
- Browser → (HTTP GET) → GitHub Pages: fetch HTML, JS, CSS, assets, content/
- JupyterLite UI loads kernels (WASM) and mounts the content folder into the in-memory FS
- User interacts through the notebook UI → code is executed by the Wasm kernel → reads/writes to FS → changes stored in IndexedDB
- GitHub Actions builds/validates the site on push and deploys to GitHub Pages
- ReadTheDocs uses conf.py to build project docs from content/ if documentation changes
c. Architectural patterns & principles
- Client-only architecture (no server backend)
- Static hosting + JAMstack approach
- WebAssembly for in-browser execution sandbox
- Virtual FS with client-side persistence
d. Key technologies
- JupyterLite (jupyter-lite.json)
- JupyterLab front-end (JS/CSS bundles)
- Emscripten FS + IndexedDB persistence
- GitHub Pages for static hosting
- GitHub Actions (deploy.yml, rtd-preview.yml)

##### Detailed but focused
- Every major moving part without splitting hairs on minor utilities

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Static Host
    subgraph "Static Hosting" 
        direction TB
        GitHubPages["GitHub Pages\n(serves HTML, JS, CSS, content/)"]:::static
    end

    %% Runtime Environment in Browser
    subgraph "Client Runtime (Browser)" 
        direction TB
        Browser["Browser / Client"]:::runtime
        UI["JupyterLite UI\n(JupyterLab Front-end)"]:::runtime
        Kernels["WASM Kernels\n(Python, R)"]:::runtime
        FS["Virtual FS\n(Emscripten FS)"]:::persistence
        IndexedDB["IndexedDB\n(persistence)"]:::persistence
        subgraph "Static Content" 
            direction TB
            DataDir["content/data/"]:::data
            Museums["Museums_in_DC.geojson"]:::data
            BarVL["bar.vl.json"]:::data
            Fasta["fasta-example.fasta"]:::data
            Iris["iris.csv"]:::data
            NotebooksDir["content/notebooks/"]:::data
            IntroNB["Intro.ipynb"]:::data
            LorenzNB["Lorenz.ipynb"]:::data
            RNB["r.ipynb"]:::data
            SqliteNB["sqlite.ipynb"]:::data
        end
    end

    %% Build & Documentation
    subgraph "Build-Time & Docs" 
        direction TB
        CI["CI/CD (GitHub Actions)"]:::build
        DeployYML["deploy.yml"]:::config
        RTDPreview["rtd-preview.yml"]:::config
        Docs["ReadTheDocs"]:::build
        ConfPy["conf.py"]:::config
        RTDConfig[".readthedocs.yml"]:::config
        EnvBuild["Environment/Kernels Build Specs"]:::config
        EnvPy["environment-python.yml"]:::config
        EnvR["environment-r.yml"]:::config
        BuildEnv["build-environment.yml"]:::config
        Gitignore[".gitignore"]:::config
        Readme["README.md"]:::config
        JLiteCfg["jupyter-lite.json"]:::config
        LegacyCfg["jupyter_lite_config.json"]:::config
        REPLCfg["repl/jupyter-lite.json"]:::config
    end

    %% Relationships
    Browser -->|"HTTP GET assets"| GitHubPages
    GitHubPages -->|serves static content| UI
    UI -->|"loads kernels"| Kernels
    UI -->|"mounts FS"| FS
    FS -->|"persist/write"| IndexedDB
    Kernels -->|"executes code"| FS
    Browser -->|"user interacts"| UI

    CI -->|"runs workflows"| DeployYML
    CI -->|"runs workflows"| RTDPreview
    CI -->|"push to Pages"| GitHubPages
    Docs -->|"build docs from content"| ConfPy
    Docs -->|"uses config"| RTDConfig
    Docs -->|"source content"| NotebooksDir
    CI -->|"uses specs"| EnvPy
    CI -->|"uses specs"| EnvR
    CI -->|"uses specs"| BuildEnv
    CI -->|"checks ignore"| Gitignore
    CI -->|"references readme"| Readme
    CI -->|"reads front-end config"| JLiteCfg
    CI -->|"reads legacy config"| LegacyCfg
    CI -->|"reads repl config"| REPLCfg

    %% Click events
    click JLiteCfg "https://github.com/jupyter/try-jupyter/blob/main/jupyter-lite.json"
    click LegacyCfg "https://github.com/jupyter/try-jupyter/blob/main/jupyter_lite_config.json"
    click REPLCfg "https://github.com/jupyter/try-jupyter/blob/main/repl/jupyter-lite.json"
    click DataDir "https://github.com/jupyter/try-jupyter/tree/main/content/data/"
    click Museums "https://github.com/jupyter/try-jupyter/blob/main/content/data/Museums_in_DC.geojson"
    click BarVL "https://github.com/jupyter/try-jupyter/blob/main/content/data/bar.vl.json"
    click Fasta "https://github.com/jupyter/try-jupyter/blob/main/content/data/fasta-example.fasta"
    click Iris "https://github.com/jupyter/try-jupyter/blob/main/content/data/iris.csv"
    click NotebooksDir "https://github.com/jupyter/try-jupyter/tree/main/content/notebooks/"
    click IntroNB "https://github.com/jupyter/try-jupyter/blob/main/content/notebooks/Intro.ipynb"
    click LorenzNB "https://github.com/jupyter/try-jupyter/blob/main/content/notebooks/Lorenz.ipynb"
    click RNB "https://github.com/jupyter/try-jupyter/blob/main/content/notebooks/r.ipynb"
    click SqliteNB "https://github.com/jupyter/try-jupyter/blob/main/content/notebooks/sqlite.ipynb"
    click DeployYML "https://github.com/jupyter/try-jupyter/blob/main/.github/workflows/deploy.yml"
    click RTDPreview "https://github.com/jupyter/try-jupyter/blob/main/.github/workflows/rtd-preview.yml"
    click ConfPy "https://github.com/jupyter/try-jupyter/blob/main/conf.py"
    click RTDConfig "https://github.com/jupyter/try-jupyter/blob/main/.readthedocs.yml"
    click EnvPy "https://github.com/jupyter/try-jupyter/blob/main/environment-python.yml"
    click EnvR "https://github.com/jupyter/try-jupyter/blob/main/environment-r.yml"
    click BuildEnv "https://github.com/jupyter/try-jupyter/blob/main/build-environment.yml"
    click Gitignore "https://github.com/jupyter/try-jupyter/blob/main/.gitignore"
    click Readme "https://github.com/jupyter/try-jupyter/blob/main/README.md"

    %% Styles
    classDef runtime fill:#D0E8FF,stroke:#0366d6,color:#0366d6;
    classDef static fill:#FFE8B0,stroke:#D97706,color:#87460F;
    classDef data fill:#FFF4D6,stroke:#D4A017,color:#927C04;
    classDef persistence fill:#FFE0E0,stroke:#D62828,color:#b62a2a;
    classDef build fill:#E8FFE8,stroke:#228B22,color:#1B6E1B;
    classDef config fill:#E0E0FF,stroke:#4B0082,color:#4B0082;
```
