# arnog/mathlive architecture

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

- Interactive diagram: https://gitdiagram.com/arnog/mathlive
- Repository: https://github.com/arnog/mathlive

## Overview

##### Project type and purpose
- Type: An open-source, frontend-only JavaScript/TypeScript library
- Purpose: Expose a `<math-field>` web component for rich math input in browsers (with mobile support, virtual keyboards, accessibility, and multiple export formats)

##### File structure
- Top-level modules:
– src/core: core data structures (atoms), parser, layout, types, fonts, localization
– src/editor-model: the editable model (commands, selection, undo/redo)
– src/editor-mathfield: glue between model, core layout, and the browser (event handling, rendering, options)
– src/public: the public API exports, including `mathfield-element`, server-side rendering stub
– src/ui & src/virtual-keyboard: mouse/touch/keyboard UI, popovers, menus, virtual-keyboard logic and data
– src/formats, src/latex-commands, src/addons: extensibility points for input/output formats, LaTeX command definitions, and plug-ins
- Infrastructure: examples/, documentation/, test/, scripts/, build-config (tsconfig, jest.config, GitHub workflows)
- Deployment: package.json, npm scripts, CI configs, publishing scripts

##### Extract insights from README
- A single web component
- Emphasizes customization, multiple output formats, and accessibility
- No backend: pure client-side library, but supports SSR module

a. Main components
1. Browser / Host Page (user’s HTML page)
2. `<math-field>` Web Component (public API)
3. Editor Layer (src/editor-model + src/editor-mathfield)
4. Core Engine (src/core + atoms + formats + LaTeX definitions)
5. UI Layer (virtual keyboard, popovers, menus, styling)
6. -ons & Plug-ins (optional modules loaded at runtime)
7. Build & Packaging (scripts → npm package, CDN bundle)
8. Test & CI (Jest unit tests, Playwright E2E, GitHub Actions / Travis)

b. Relationships and data flow
- User interacts → Browser dispatches events → Web Component → Editor Layer (commands, model updates)
- Editor Layer invokes Core Engine to re-parse and re-layout → returns render tree or SVG/DOM elements
- UI Layer displays popovers, virtual keyboard → emits events back to Editor Layer
- Public API methods (getValue, setValue) call into Editor Layer/Core Engine
- -ons register with Core or Editor to extend functionality (e.g., static render, custom math-to-speech)
- Build & Packaging: source modules → bundler/transpiler → output to npm / CDN
- Test & CI validate code via unit tests and browser automation

c. Architectural patterns and design principles
- Modular layering: Public API → Editor → Core → Formats → Add-ons
- Event-driven: all user inputs and UI interactions flow as events/commands
- Plug-in architecture: src/addons, plugins/* for extensibility
- Separation of concerns: core parsing/layout vs. editor state vs. UI presentation
- SSR support: public SSR stub uses same Core logic without DOM

d. Key technologies/frameworks
- TypeScript + ES Modules
- Web Components (Custom Elements API)
- Less/PostCSS for styling
- Jest (unit tests), Playwright (E2E)
- Node.js build scripts (build.mjs, shell scripts)
- GitHub Actions & Travis CI

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Runtime Modules (Blue)
    subgraph "Host"
        Browser["Browser / Host Page"]:::runtime
    end

    subgraph "Public API"
        WebComp["<math-field> Web Component"]:::runtime
    end

    subgraph "Editor Layer"
        Model["Editable Model"]:::runtime
        Glue["Mathfield Glue"]:::runtime
    end

    subgraph "Core Engine"
        Core["Core Data Structures & Parser/Layout"]:::runtime
        Atoms["Atom Definitions"]:::runtime
        Formats["Export Formats"]:::runtime
        Latex["LaTeX Command Definitions"]:::runtime
    end

    subgraph "UI Layer"
        UI["Mouse/Touch/Keyboard UI, Menus"]:::runtime
        VK["Virtual Keyboard"]:::runtime
    end

    AddOns["Add-ons & Plug-ins"]:::ext

    %% Build & Packaging (Green)
    subgraph "Build & Packaging"
        Scripts["Build Scripts & Config"]:::build
        Package["Package Definitions"]:::build
    end

    %% Test & CI (Green)
    subgraph "Test & CI"
        Unit["Unit & Snapshot Tests"]:::build
        E2E["E2E Tests & Config"]:::build
        CI["CI Workflows"]:::build
    end

    %% Runtime Flow
    Browser -->|"loads component"| WebComp
    WebComp -->|"calls API"| Model
    Model -->|"commands & model updates"| Glue
    Glue -->|"parse & layout"| Core
    Core --> Atoms
    Core --> Formats
    Core --> Latex
    Core -->|"returns render tree"| Glue
    Glue -->|"renders DOM/SVG"| WebComp
    UI -->|"UI events"| Glue
    VK -->|"keyboard events"| Glue
    WebComp -->|"public methods"| Core

    %% Extensions (Orange)
    AddOns -.->|"hooks"| Core
    AddOns -.->|"hooks"| Glue
    AddOns -.->|"optional modules"| Formats

    %% Build/Deploy Flow (Dashed)
    Scripts ---|"bundles modules"| WebComp
    Scripts --- Model
    Scripts --- Core
    Scripts --- UI
    Scripts --- AddOns
    Package --- Scripts

    %% Testing & CI Flow (Dashed)
    Unit --- Core
    Unit --- Model
    Unit --- WebComp
    E2E --- WebComp
    CI --- Unit
    CI --- E2E

    %% Click Events
    click Browser "https://github.com/arnog/mathlive/tree/master/examples/"
    click WebComp "https://github.com/arnog/mathlive/blob/master/src/public/mathfield-element.ts"
    click Model "https://github.com/arnog/mathlive/tree/master/src/editor-model/"
    click Glue "https://github.com/arnog/mathlive/tree/master/src/editor-mathfield/"
    click Core "https://github.com/arnog/mathlive/tree/master/src/core/"
    click Atoms "https://github.com/arnog/mathlive/tree/master/src/atoms/"
    click Formats "https://github.com/arnog/mathlive/tree/master/src/formats/"
    click Latex "https://github.com/arnog/mathlive/tree/master/src/latex-commands/"
    click UI "https://github.com/arnog/mathlive/tree/master/src/ui/"
    click VK "https://github.com/arnog/mathlive/tree/master/src/virtual-keyboard/"
    click AddOns "https://github.com/arnog/mathlive/tree/master/src/addons/"
    click Scripts "https://github.com/arnog/mathlive/tree/master/scripts/"
    click Package "https://github.com/arnog/mathlive/blob/master/package.json"
    click Unit "https://github.com/arnog/mathlive/tree/master/test/"
    click E2E "https://github.com/arnog/mathlive/tree/master/test/playwright-tests/"
    click CI "https://github.com/arnog/mathlive/tree/master/.github/workflows/"

    %% Styles
    classDef runtime fill:#cfe2f3,stroke:#0366d6,color:#000;
    classDef build fill:#d9ead3,stroke:#006400,color:#000;
    classDef ext fill:#fce5cd,stroke:#b35900,color:#000;
```
