# koaning/drawdata architecture

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

- Interactive diagram: https://gitdiagram.com/koaning/drawdata
- Repository: https://github.com/koaning/drawdata

## Overview

##### Project Type and Purpose
- drawdata is a Python library that provides interactive Jupyter widgets (ScatterWidget, BarWidget) for hand-drawing datasets in a notebook. Under the hood it leverages the anywidget/ip ywidgets machinery to connect a Python backend (the “kernel”) with a JavaScript frontend running in Jupyter, VS Code or Colab. It ships both Python code (drawdata package) and JavaScript/CSS assets (drawdata/static and js/).

##### File-Structure Analysis
- Top-level:
- setup.py, readme.md, demo scripts (demo.py, bar-demo.py, scatter-demo.py)
- drawdata/ – the Python package containing:
– __init__.py and widget implementers (ScatterWidget, BarWidget)
– static/ – the compiled widget JS & CSS for the frontend
- js/ – source JS for the widgets (bar_widget.js, scatter_widget.js)
- docs/ – static site (Vite-powered) with built assets for documentation
- Key patterns: separation of Python logic vs frontend assets; use of anywidget/ip ywidgets for comms; standard packaging via setup.py.

##### README Insights
- Confirms use of anywidget and ipywidgets.
- Describes two main APIs (ScatterWidget, BarWidget).

a. Main Components
1. Jupyter Notebook Frontend (in Browser or VS Code)
2. JavaScript Widget View & Model (drawdata/static + anywidget runtime)
3. Jupyter Comm Layer (WebSocket/JSON comms between frontend & kernel)
4. Python Kernel Backend (drawdata package: widget classes, state management)
5. Data Consumers (user code retrieving widget.data → pandas/polars → scikit-learn)
6. Documentation Site (Vite + static assets under docs/)
b. Relationships & Interactions
- User instantiates ScatterWidget in notebook → Python kernel registers a widget instance.
- Notebook front-end loads the corresponding JS view & model (from drawdata/static).
- As the user draws, mouse events trigger JS updates → sent over the comm channel → Python backend receives new coordinates.
- Python backend updates internal state (`widget.data`) and notifies any observers.
- User code calls `widget.data_as_pandas` or `widget.data_as_polars` → Python side converts the stored list of dicts into a DataFrame.
- Optionally, user feeds X, y into scikit-learn pipelines.
c. Architectural Patterns & Principles
- MVC-style split between JS “View” & Python “Model.”
- Publish-subscribe via Jupyter comms for real-time updates.
- Packaging assets alongside Python code (using anywidget conventions).
- Clear separation of core library vs documentation site.
d. Key Technologies & Frameworks
- Python: anywidget, ipywidgets, pandas, polars, scikit-learn (optional)
- JavaScript: custom widget code (bar_widget.js, scatter_widget.js), d3.v7.js (for drawing), anywidget/browser runtime

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Frontend Container
    subgraph "Jupyter Frontend (Browser / VS Code)"
        direction TB
        UI["Notebook UI"]:::frontend
        subgraph "JS Widget View & Model"
            direction TB
            BW_JS["bar_widget.js"]:::frontend
            BW_CSS["bar_widget.css"]:::frontend
            SW_JS["scatter_widget.js"]:::frontend
            SW_CSS["scatter_widget.css"]:::frontend
        end
    end

    %% Comm Channel
    Comm["Jupyter Comm Channel\n(WebSocket/JSON)"]:::comm

    %% Backend Container
    subgraph "Python Kernel Backend"
        direction TB
        Kernel["drawdata/__init__.py\n(Python Widget Model)"]:::backend
    end

    %% Data Consumers
    subgraph "Data Conversion & Consumers"
        direction TB
        Clients["demo.py\nbar-demo.py\nscatter-demo.py"]:::external
        ExtDeps["pandas / polars / scikit-learn"]:::external
    end

    %% Documentation Site
    subgraph "Documentation Site (Vite)"
        direction TB
        IDX["docs/index.html"]:::docs
        MAN["docs/manifest.json"]:::docs
        SWEB["docs/site.webmanifest"]:::docs
        ARCHJS["architectureDiagram-IEHRJDOE-DJyOE9c0.js"]:::docs
        OTH["other docs/assets JS & CSS"]:::docs
    end

    %% Connections
    UI -->|"loads widget view"| BW_JS
    UI -->|"loads widget view"| SW_JS
    BW_JS -->|"renders & captures events"| Comm
    SW_JS -->|"renders & captures events"| Comm
    Comm -->|"sends events"| Kernel
    Kernel -->|"state updates"| Comm
    Kernel -->|"provides widget.data"| Clients
    Clients -->|"uses"| ExtDeps

    %% Click Events
    click BW_JS "https://github.com/koaning/drawdata/blob/main/drawdata/static/bar_widget.js"
    click BW_CSS "https://github.com/koaning/drawdata/blob/main/drawdata/static/bar_widget.css"
    click SW_JS "https://github.com/koaning/drawdata/blob/main/drawdata/static/scatter_widget.js"
    click SW_CSS "https://github.com/koaning/drawdata/blob/main/drawdata/static/scatter_widget.css"
    click Kernel "https://github.com/koaning/drawdata/blob/main/drawdata/__init__.py"
    click Clients "https://github.com/koaning/drawdata/blob/main/demo.py"
    click OTH "https://github.com/koaning/drawdata/blob/main/docs/assets/architectureDiagram-IEHRJDOE-DJyOE9c0.js"
    click IDX "https://github.com/koaning/drawdata/blob/main/docs/index.html"
    click MAN "https://github.com/koaning/drawdata/blob/main/docs/manifest.json"
    click SWEB "https://github.com/koaning/drawdata/blob/main/docs/site.webmanifest"

    %% Styles
    classDef frontend fill:#b3d4fc,stroke:#2f6f9f,color:#000
    classDef backend fill:#d2f8d2,stroke:#3f9f3f,color:#000
    classDef comm fill:#ffffff,stroke:#999999,color:#000,stroke-dasharray: 5 5
    classDef external fill:#eeeeee,stroke:#aaaaaa,color:#000
    classDef docs fill:#ffe0b3,stroke:#ff9933,color:#000
```
