# dralletje/notebook-experiments architecture

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

- Interactive diagram: https://gitdiagram.com/dralletje/notebook-experiments
- Repository: https://github.com/dralletje/notebook-experiments

## Overview

##### Main Components
- Lezer Playground Module – This is the dedicated section for testing and visualizing Lezer grammars. It features its own HTML, a React-based front end (in src/), and multiple packages (like lezer-inspector, lezer-generator-worker, etc.) that manage grammar analysis and transformation.
- Simple Notebooks Module – This module hosts the notebook experiments and is separated into a web-app (with React-based components such as App.jsx, Notebook.jsx, etc.), a node-based engine (node-engine directory), and supplementary packages specific to notebook operations.
- Common / Shared Packages – There is a top-level "packages" directory (and additional package subdirectories under lezer-playground and simple-notebooks) that provides libraries for CodeMirror features, transformation routines, worker helpers, and other utilities shared by the frontend and backend components.
- Configuration and Build/Deployment Tools – At the repository level, you have configuration files (like .gitignore, vercel.json, vite.config.js, and turbo.json) plus Yarn configuration and plugin management that support development and deployment.

##### Relationships and Interactions
- The front-end applications (Lezer Playground and the Simple Notebooks web-app) interact with shared libraries through direct package imports, often leveraging React components and CodeMirror editors to present rich editing and syntax-highlighting experiences.
- Worker processes and environment-specific components (workers in transform-javascript, typescript-server-webworker, and worker-typescript-magic) illustrate the separation of long-running background tasks from the main UI threads. Represent them as separate compute nodes connected to the UI via a defined communication channel (e.g., websockets or message passing).
- The node-engine within Simple Notebooks shows a backend-processing pipeline that acts as a computation layer (it includes circuits, testing suites, and file management routines) which links to the web-app, likely via APIs or shared event handling.

##### Architectural Patterns and Design Principles
- Modular Design – The repository leverages a highly modular structure, with clear separation between the UI, business logic (node-engine), shared libraries, and worker components. This promotes reusability and maintainability.
- Separation of Concerns – There is a clear delineation between editor UI components, parsing/processing logic (with Lezer and CodeMirror integrations), and background worker channels.
- Micro Frontends / Plugin-Based Architecture – The large number of specialized packages (for example, codemirror-x-react, inspector-x-react, use-immer-store, etc.) suggest that adding or swapping functionality might be done in a plug-and-play manner.

##### Relevant Technologies and Frameworks
- React and JSX components are the foundation for the user interfaces in both Lezer Playground and the Simple Notebooks web-app.
- CodeMirror is used extensively for code editing, syntax highlighting, and interactive functionality.
- Lezer is employed for grammar generation and inspection.
- Workers (webworkers) and node-based scripts indicate a design choice to offload heavy computations, likely in a concurrent manner.
- Yarn is used for package management along with configuration data in files like .yarnrc.yml.

## Diagram (Mermaid)

```mermaid
flowchart TD
    Config("Configuration & Build Tools"):::config

    LP_Module("Lezer Playground Module"):::module
    LP_HTML("HTML (UI)"):::frontend
    LP_REACT("React Frontend"):::frontend
    LP_Inspector("Lezer Inspector"):::package
    LP_GenWorker("Lezer Generator Worker"):::worker
    LP_Helper("Lezer Helper (lezer-lezer-error)"):::package

    SN_Module("Simple Notebooks Module"):::module
    SN_Web("Web App (React UI)"):::frontend
    SN_Node("Node Engine (Backend)"):::backend
    SN_NotebookPkg("Notebook Package (javascript-notebook-runner)"):::package

    Shared("Shared Packages"):::package

    %% Configuration connects to main modules and shared libraries
    Config --> LP_Module
    Config --> SN_Module
    Config --> Shared

    %% Lezer Playground Module composition
    LP_Module -->|"contains"| LP_HTML
    LP_Module -->|"contains"| LP_REACT
    LP_Module -->|"includes"| LP_Inspector
    LP_Module -->|"includes"| LP_GenWorker
    LP_Module -->|"includes"| LP_Helper

    %% Simple Notebooks Module composition
    SN_Module -->|"contains"| SN_Web
    SN_Module -->|"contains"| SN_Node
    SN_Module -->|"includes"| SN_NotebookPkg

    %% Interactions between UI and Shared Packages
    LP_HTML -->|"imports"| Shared
    LP_REACT -->|"imports"| Shared
    SN_Web -->|"imports"| Shared

    %% Communication between Simple Notebooks UI and its Node Engine
    SN_Web -->|"API/event"| SN_Node

    %% Asynchronous messaging within Lezer Playground between UI and worker
    LP_HTML -->|"asyncMsg"| LP_GenWorker
    LP_REACT -->|"asyncMsg"| LP_GenWorker

    %% Click Events
    click LP_Module "https://github.com/dralletje/notebook-experiments/tree/main/lezer-playground/"
    click LP_HTML "https://github.com/dralletje/notebook-experiments/blob/main/lezer-playground/index.html"
    click LP_REACT "https://github.com/dralletje/notebook-experiments/tree/main/lezer-playground/src/"
    click LP_Inspector "https://github.com/dralletje/notebook-experiments/tree/main/lezer-playground/packages/lezer-inspector/"
    click LP_GenWorker "https://github.com/dralletje/notebook-experiments/tree/main/lezer-playground/packages/lezer-generator-worker/"
    click LP_Helper "https://github.com/dralletje/notebook-experiments/tree/main/lezer-playground/packages/lezer-lezer-error/"
    click SN_Web "https://github.com/dralletje/notebook-experiments/tree/main/simple-notebooks/web-app/"
    click SN_Node "https://github.com/dralletje/notebook-experiments/tree/main/simple-notebooks/node-engine/"
    click SN_NotebookPkg "https://github.com/dralletje/notebook-experiments/tree/main/simple-notebooks/packages/javascript-notebook-runner/"
    click Shared "https://github.com/dralletje/notebook-experiments/tree/main/packages/"
    click Config "https://github.com/dralletje/notebook-experiments/blob/main/.gitignore"

    %% Class Definitions for styling
    classDef frontend fill:#cfe2f3,stroke:#0b5394,stroke-width:2px
    classDef backend fill:#fce5cd,stroke:#b45f06,stroke-width:2px
    classDef worker fill:#d9ead3,stroke:#38761d,stroke-width:2px
    classDef package fill:#ead1dc,stroke:#99004d,stroke-width:2px
    classDef config fill:#fff2cc,stroke:#bf9000,stroke-width:2px
    classDef module fill:#d9d2e9,stroke:#6d3b8d,stroke-width:2px
```
