# codingmango/learn-vpython architecture

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

- Interactive diagram: https://gitdiagram.com/codingmango/learn-vpython
- Repository: https://github.com/codingmango/learn-vpython

## Overview

##### Project type & purpose (what you’re diagramming)
This repo is **not a traditional multi-tier app** (no backend/frontend/services). It’s a **learning content + executable notebooks** project: a curated set of **Jupyter Notebooks teaching VPython** (3D animations/simulations) plus one standalone Python script (`014-thousand-cubes.py`).

- **Execution environment** (user + Jupyter runtime)
- **Notebook content** (individual lessons)
- **VPython rendering stack** (Python → VPython → browser/canvas/WebGL)
- Optional: **widgets/interactive inputs**, and **time-based animation loops**

##### File structure analysis (components implied by tree)
Top-level artifacts:
- `001-...ipynb` through `013-widgets.ipynb`: incremental lessons (basics → animations → physics-ish behaviors → text/labels → widgets)
- `README.md`: usage instructions and learning goals

Architecturally, each notebook is a **self-contained “module”** that executes in the same general pipeline:
**Jupyter kernel (Python) → VPython library → renders to browser output**.

##### README-derived architecture cues
The README makes clear:
- **Runtime**: Python 3.7+, Jupyter Notebook/Lab
- **Core dependency**: `vpython`
- **UI**: browser-based notebook rendering; some notebooks use **widgets** to change parameters live
- **Primary behavior**: **3D animations/simulations**, typically with a time loop (e.g., `rate()` in VPython), and sometimes non-blocking/dual animation patterns (notebooks 002, 006)

- the **interactive feedback loop** (user modifies params → kernel updates scene → browser re-renders)
- the **animation loop timing control**

##### Learner / Developer (User)
Runs notebooks, edits code, interacts with widgets.

**Execution & Orchestration**
##### Jupyter UI (Notebook/Lab in Browser)
Displays notebooks, captures user interactions, shows outputs.
##### Jupyter Server (local process)
Serves notebook documents, websocket channels, forwards execution requests.
##### Python Kernel (IPython kernel)
Executes cells, holds runtime state.

**Core Library / Rendering**
##### VPython Rendering Layer (Browser-side)
VPython commonly renders via a browser canvas/WebGL pipeline; represent it as:
- **Web Canvas / WebGL** (or “3D Renderer”)

**Interactive Controls (where relevant)**
##### Widget/Input Layer (notebook 013)
Sliders/buttons/etc. that send parameter changes to the kernel.

**Content Modules (the repo itself)**
- 1: Basics & primitives (`001`, `012`)
- 2: Animation patterns (`002`, `004`, `006`)
- 3: Example simulations (`003`, `005`, `010`, `011`)
- 5: Geometry/orientation (`009`)
- 6: Widgets (`013`)
- Standalone script: `014-thousand-cubes.py`

**External/Stdlib**

##### User → Jupyter UI
- edits notebook cells
- clicks run
- manipulates widgets

##### Jupyter UI ↔ Jupyter Server
- HTTP/WebSocket communication for execution requests and output streaming

##### Jupyter Server ↔ Python Kernel
- execution commands
- stdout/stderr/results
- widget comm messages (for interactive controls)

##### VPython API → Browser Renderer (Canvas/WebGL)
- scene updates are sent/displayed in the notebook output area

##### Animation loop feedback
- Kernel executes loop (often `while True:` with `rate(fps)`)
- Each iteration updates VPython objects → triggers re-render
- For “non-blocking/dual animation” notebook: show **two object update streams** driven by one loop/tick scheduler.

##### Widgets path (013)
- User changes slider → widget event → kernel callback updates parameters → VPython scene updates.

##### Time source path (011)
- Kernel calls `time` → updates clock hands → VPython scene updates.

##### Architectural patterns used here

- **Interactive REPL-style execution**: stateful kernel; successive cells mutate the same runtime scene.
- **Scene graph / object model**: VPython objects (primitives) represent a scene; updates modify properties.
- **Render loop / tick-based simulation**: animation driven by a timing function (`rate()` conceptually) rather than multi-threading.
- **Event-driven parameter updates**: widgets produce events that update simulation parameters.

##### Relevant technologies/frameworks
- Python 3.7+
- Jupyter Notebook/Lab (browser UI + local server)
- IPython Kernel
- VPython
- Browser rendering (Canvas/WebGL)
- (Optional) ipywidgets-style widget comms (since notebook 013 focuses on widgets)
- Python `time` module (accurate clock)

##### Clear labels for each component
Use explicit names like:
- “Jupyter UI (Browser)”
- “Jupyter Server (local)”
- “Python Kernel (IPython)”
- “VPython (Python API)”
- “VPython Renderer (Canvas/WebGL)”
- “Notebook: 003 Bouncing Ball (loop + collision logic)”
- “Notebook: 013 Widgets (event callbacks)”

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% =========================
    %% Actor
    %% =========================
    U["Learner / Developer (User)"]:::actor

    %% =========================
    %% Notebook Platform (Browser + Local Runtime)
    %% =========================
    subgraph "Notebook Platform (Local)"
        direction TB

        UI["Jupyter UI (Notebook/Lab in Browser)"]:::runtime
        JS["Jupyter Server (local)"]:::runtime
        K["Python Kernel (IPython)"]:::runtime

        UI <-->|"HTTP+WebSocket(exec+outputs)"| JS
        JS <-->|"ZMQ+channels(code+results)"| K
    end

    %% =========================
    %% Rendering Stack (VPython)
    %% =========================
    subgraph "VPython Rendering Stack"
        direction TB

        VAPI["VPython (Python API)"]:::lib
        VR["VPython Renderer (Notebook output: Canvas/WebGL)"]:::render
    end

    %% =========================
    %% Optional Interaction + Timing Sources
    %% =========================
    subgraph "Interaction & Timing"
        direction TB

        W["Widget/Input Layer (sliders/buttons, comms)"]:::interaction
        T["Python Stdlib (time, math, etc.)"]:::stdlib
        LOOP["Animation Tick Loop (rate()/frame scheduler)"]:::loop
    end

    %% =========================
    %% Repo Content Modules (Lessons + Script)
    %% =========================
    subgraph "Repo Content (Executable Lessons)"
        direction TB

        subgraph "Basics & Primitives"
            direction TB
            N001["001 Intro to Basics (primitives/scene)"]:::content
            N012["012 Labels and Text"]:::content
        end

        subgraph "Animation Patterns"
            direction TB
            N002["002 Basic Animations (loop + rate)"]:::content
            N004["004 Animating by Changing Dimensions"]:::content
            N006["006 Non-blocking / Dual Animations"]:::content
        end

        subgraph "Example Simulations"
            direction TB
            N003["003 Bouncing Ball (collision loop)"]:::content
            N005["005 Thermometer 3D"]:::content
            N010["010 Analog Clock"]:::content
            N011["011 Accurate Analog Clock (time module)"]:::content
        end

        subgraph "Color / RGB"
            direction TB
            N007["007 Mixing Colours"]:::content
            N008["008 Colour Varying Orb"]:::content
        end

        subgraph "Geometry / Orientation"
            direction TB
            N009["009 Orientation and Axis"]:::content
        end

        subgraph "Widgets"
            direction TB
            N013["013 Widgets (callbacks drive params)"]:::content
        end

        S014["014 Thousand Cubes (standalone script)"]:::content
        RMD["README (usage instructions + learning goals)"]:::doc
    end

    %% =========================
    %% High-level user interactions
    %% =========================
    U -->|"edit/run_cells"| UI
    U -->|"manipulate_widgets"| UI

    %% =========================
    %% Execution flow: content -> kernel state
    %% =========================
    N001 -->|"execute_cells"| K
    N002 -->|"execute_cells"| K
    N003 -->|"execute_cells"| K
    N004 -->|"execute_cells"| K
    N005 -->|"execute_cells"| K
    N006 -->|"execute_cells"| K
    N007 -->|"execute_cells"| K
    N008 -->|"execute_cells"| K
    N009 -->|"execute_cells"| K
    N010 -->|"execute_cells"| K
    N011 -->|"execute_cells"| K
    N012 -->|"execute_cells"| K
    N013 -->|"execute_cells"| K
    S014 -->|"run_script"| K

    %% =========================
    %% Kernel -> VPython -> Renderer (render/update propagation)
    %% =========================
    K -->|"create/update_scene_objects"| VAPI
    VAPI -.->|"scene_updates"| VR
    VR -.->|"rendered_3D_output"| UI

    %% =========================
    %% Animation loop pattern (tick drives repeated updates)
    %% =========================
    K -->|"runs_loop"| LOOP
    LOOP -->|"tick(step)"| K

    %% =========================
    %% Widgets event loop (user -> UI -> server -> kernel -> vpython)
    %% =========================
    UI -->|"widget_events"| W
    W -->|"comm_msgs(callbacks)"| K
    N013 -->|"defines_callbacks"| W
    W -->|"param_updates"| VAPI

    %% =========================
    %% Time source for accurate clock
    %% =========================
    N011 -->|"calls_time()"| T
    T -->|"time_values"| K

    %% =========================
    %% Non-blocking/dual animation note (two update streams)
    %% =========================
    N006 -->|"dual_update_streams"| LOOP

    %% =========================
    %% README informs setup/runtime usage
    %% =========================
    RMD -.->|"setup_instructions"| UI
    RMD -.->|"runtime_requirements"| JS

    %% =========================
    %% Click events (from component_mapping)
    %% =========================
    click N001 "https://github.com/codingmango/learn-vpython/blob/main/001-intro-to-basics.ipynb"
    click N002 "https://github.com/codingmango/learn-vpython/blob/main/002-basic-animations.ipynb"
    click N003 "https://github.com/codingmango/learn-vpython/blob/main/003-bouncing-ball.ipynb"
    click N004 "https://github.com/codingmango/learn-vpython/blob/main/004-animating-by-changing-dimensions.ipynb"
    click N005 "https://github.com/codingmango/learn-vpython/blob/main/005-thermometer-3d.ipynb"
    click N006 "https://github.com/codingmango/learn-vpython/blob/main/006-non-blocking-animations.ipynb"
    click N007 "https://github.com/codingmango/learn-vpython/blob/main/007-mixing-colours.ipynb"
    click N008 "https://github.com/codingmango/learn-vpython/blob/main/008-colour-varying-orb.ipynb"
    click N009 "https://github.com/codingmango/learn-vpython/blob/main/009-orientation-and-axis.ipynb"
    click N010 "https://github.com/codingmango/learn-vpython/blob/main/010-analog-clock.ipynb"
    click N011 "https://github.com/codingmango/learn-vpython/blob/main/011-accurate-analog-clock.ipynb"
    click N012 "https://github.com/codingmango/learn-vpython/blob/main/012-labels-and-text.ipynb"
    click N013 "https://github.com/codingmango/learn-vpython/blob/main/013-widgets.ipynb"
    click S014 "https://github.com/codingmango/learn-vpython/blob/main/014-thousand-cubes.py"
    click RMD "https://github.com/codingmango/learn-vpython/blob/main/README.md"

    %% =========================
    %% Styles (color-coded)
    %% =========================
    classDef actor fill:#E5E7EB,stroke:#6B7280,stroke-width:1px,color:#111827
    classDef runtime fill:#DBEAFE,stroke:#1D4ED8,stroke-width:1px,color:#0F172A
    classDef lib fill:#FFEDD5,stroke:#C2410C,stroke-width:1px,color:#0F172A
    classDef render fill:#FED7AA,stroke:#9A3412,stroke-width:1px,color:#0F172A
    classDef interaction fill:#D1FAE5,stroke:#047857,stroke-width:1px,color:#052e16
    classDef stdlib fill:#F3F4F6,stroke:#4B5563,stroke-width:1px,color:#111827
    classDef loop fill:#FEF9C3,stroke:#A16207,stroke-width:1px,color:#0F172A
    classDef content fill:#DCFCE7,stroke:#15803D,stroke-width:1px,color:#052e16
    classDef doc fill:#EDE9FE,stroke:#6D28D9,stroke-width:1px,color:#111827
```
