# codelv/enaml-web architecture

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

- Interactive diagram: https://gitdiagram.com/codelv/enaml-web
- Repository: https://github.com/codelv/enaml-web

## Overview

##### Project Type and Purpose
- **Type**: An open-source Python web component toolkit / framework for building websites declaratively with Enaml.
- **Purpose**: Provides a component API (Html, Markdown, Code, etc.), a core application engine to render and manage a server-side DOM, and an LXML-based implementation with optional C speedups. Enables both static site generation and interactive, stateful pages via WebSockets or polling.

##### High-Level Architecture & Main Components
A. **Developer Layer**
- .enaml view definitions (e.g., `index.enaml`, examples/**/*.enaml)
- Python glue code (examples/*.py, user handlers)
B. **Framework Layer (enaml-web core)**
1. **Component API** (`web/components/`)
– High-level Enaml component classes: Html, Raw, Markdown, Code, AutoForm, Block, Looper, etc.
2. **Core Engine** (`web/core/`)
– `WebApplication` (app startup, request routing, DOM lifecycle)
– `Block`, `View` abstractions (template inheritance and composition)
– Event handling and data binding API
C. **Implementation Layer (DOM & Rendering)**
1. **LXML Back-end** (`web/impl/`)
– Parsers & renderers for each component using lxml etree
2. **C Speedups** (`src/speedups.c`)
– Performance-critical routines for diffing or attribute updates
D. **Integration & Delivery**
1. **Web Framework Adapter** (e.g., Tornado, Flask)
– Uses `WebApplication` to handle HTTP GET/POST and WebSocket endpoints
2. **Client-Side Script** (examples/*/app.js)
– Listens on WebSocket for diff messages, applies patches to browser DOM
– Captures user events and sends “modified” messages back to server
E. **Supporting Infrastructure**
- **Examples** (`examples/`) and **Tests** (`tests/`)
- **CI/CD** (GitHub Actions `ci.yml`)
- **Documentation** (`docs/`, `README.md`)

##### Relationships & Data Flows
- **Startup**: User’s Python application creates a `WebApplication` → loads Enaml views → registers routes/events.
- **Static Render**: `view.render()` → Core Engine invokes Component API → LXML Implementation builds DOM → HTML output written to disk.
- **Interactive Flow**:
1. **Initial Request**: Browser GET → WebFramework Adapter → `WebApplication` → `view.render()` → HTML+JS → Browser.
2. **Client Events**: User clicks/types → Client-Side Script captures → sends JSON “modified” event via WebSocket.
3. **Server Update**: Adapter receives event → `WebApplication` applies change to server-side LXML tree → triggers handlers.
4. **Diff Generation**: Core Engine diffs old vs. new DOM → produces patch messages.
5. **Client Patch**: Patch sent back via WebSocket → Client-Side Script applies to live DOM.

##### Architectural Patterns & Principles
- **Component-Based**: Each UI element is an Enaml component class.
- **Server-Side DOM**: Maintains authoritative view state, enables two-way data binding.
- **Template Inheritance**: `Block` nodes allow extension and override of base templates.
- **Layered Design**: API → Core Engine → Implementation → Integration.
- **Extension Points**:
- New components under `web/components/`
- Provide custom LXML renderers under `web/impl/`
- Swap out WebFramework adapter

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Developer Layer
    subgraph "Developer Layer"
        direction TB
        Enaml1["index.enaml"]:::user
        Enaml2["examples/dataframe_viewer/viewer.enaml"]:::user
        Enaml3["examples/plotly/index.enaml"]:::user
        Enaml4["examples/simple_site/views.enaml"]:::user
        Enaml5["examples/static_site/index.enaml"]:::user
        Enaml6["tests/pages.enaml"]:::user
        Py1["examples/dataframe_viewer/app.py"]:::user
        Py2["examples/plotly/main.py"]:::user
        Py3["examples/simple_site/main.py"]:::user
        Py4["examples/static_site/main.py"]:::user
    end

    %% Framework Layer
    subgraph "Framework Layer"
        direction TB
        subgraph "Component API" 
            direction TB
            API1["api.py"]:::lib
            API2["html.py"]:::lib
            API3["raw.py"]:::lib
            API4["md.py"]:::lib
            API5["code.py"]:::lib
            API6["ipynb.py"]:::lib
        end
        subgraph "Core Engine"
            direction TB
            App["WebApplication\n(app.py)"]:::lib
            Block["Block\n(block.py)"]:::lib
            View["API & View\n(api.py)"]:::lib
        end
    end

    %% Implementation Layer
    subgraph "Implementation Layer"
        direction TB
        subgraph "LXML Back-end Renderers"
            direction TB
            Impl1["lxml_components.py"]:::impl
            Impl2["lxml_raw.py"]:::impl
            Impl3["lxml_md.py"]:::impl
            Impl4["lxml_code.py"]:::impl
            Impl5["lxml_ipynb.py"]:::impl
            Impl6["lxml_toolkit_object.py"]:::impl
        end
        CExt["speedups.c"]:::impl
    end

    %% Integration & Delivery
    subgraph "Integration & Delivery"
        direction TB
        Adapter["Web Framework Adapter\n(Flask/Tornado)"]:::ext
        Client["Client-Side Script\n(app.js)"]:::user
        Browser["Browser"]:::ext
    end

    %% Supporting Infrastructure
    subgraph "Supporting Infrastructure"
        direction TB
        Examples["examples/"]:::infra
        Tests["tests/"]:::infra
        CI[".github/workflows/ci.yml"]:::infra
        Docs["docs/ & README.md"]:::infra
    end

    %% Relations - Static Flow
    App -->|"render() → calls Component API"| API1
    API1 --> API2
    API1 --> API3
    API1 --> API4
    API1 --> API5
    API1 --> API6
    API1 -->|"to LXML Impl"| Impl1
    Impl1 --> Impl2
    Impl1 --> Impl3
    Impl1 --> Impl4
    Impl1 --> Impl5
    Impl1 --> Impl6
    Impl1 -->|"optional C speedups"| CExt
    Impl6 -->|"HTML output"| Enaml5

    %% Relations - Interactive Flow
    Browser -->|"GET /"| Adapter
    Adapter -->|"route → WebApplication"| App
    App -->|"initial render() → HTML+JS"| Browser
    Browser -->|"start WebSocket"| Adapter
    Browser -->|"user events"| Client
    Client -->|"modified event"| Adapter
    Adapter -->|"apply change"| App
    App -->|"diff old vs new"| Impl1
    Impl1 -->|"patch"| Client
    Client -->|"apply patch"| Browser

    %% Developer to Framework
    Enaml1 --> App
    Enaml2 --> App
    Enaml3 --> App
    Enaml4 --> App
    Enaml5 --> App
    Enaml6 --> App
    Py1 --> App
    Py2 --> App
    Py3 --> App
    Py4 --> App

    %% Supporting links
    Examples --> Enaml2
    Examples --> Py1
    Tests --> Enaml6
    CI --> Examples
    Docs --> Examples

    %% Click Events
    click Enaml2 "https://github.com/codelv/enaml-web/blob/master/examples/dataframe_viewer/viewer.enaml"
    click Enaml3 "https://github.com/codelv/enaml-web/blob/master/examples/plotly/index.enaml"
    click Enaml4 "https://github.com/codelv/enaml-web/blob/master/examples/simple_site/views.enaml"
    click Enaml5 "https://github.com/codelv/enaml-web/blob/master/examples/static_site/index.enaml"
    click Enaml6 "https://github.com/codelv/enaml-web/blob/master/tests/pages.enaml"
    click Py1 "https://github.com/codelv/enaml-web/blob/master/examples/dataframe_viewer/app.py"
    click Py2 "https://github.com/codelv/enaml-web/blob/master/examples/plotly/main.py"
    click Py3 "https://github.com/codelv/enaml-web/blob/master/examples/simple_site/main.py"
    click Py4 "https://github.com/codelv/enaml-web/blob/master/examples/static_site/main.py"
    click API1 "https://github.com/codelv/enaml-web/blob/master/web/components/api.py"
    click API2 "https://github.com/codelv/enaml-web/blob/master/web/components/html.py"
    click API3 "https://github.com/codelv/enaml-web/blob/master/web/components/raw.py"
    click API4 "https://github.com/codelv/enaml-web/blob/master/web/components/md.py"
    click API5 "https://github.com/codelv/enaml-web/blob/master/web/components/code.py"
    click API6 "https://github.com/codelv/enaml-web/blob/master/web/components/ipynb.py"
    click App "https://github.com/codelv/enaml-web/blob/master/web/core/app.py"
    click Block "https://github.com/codelv/enaml-web/blob/master/web/core/block.py"
    click View "https://github.com/codelv/enaml-web/blob/master/web/core/api.py"
    click Impl1 "https://github.com/codelv/enaml-web/blob/master/web/impl/lxml_components.py"
    click Impl2 "https://github.com/codelv/enaml-web/blob/master/web/impl/lxml_raw.py"
    click Impl3 "https://github.com/codelv/enaml-web/blob/master/web/impl/lxml_md.py"
    click Impl4 "https://github.com/codelv/enaml-web/blob/master/web/impl/lxml_code.py"
    click Impl5 "https://github.com/codelv/enaml-web/blob/master/web/impl/lxml_ipynb.py"
    click Impl6 "https://github.com/codelv/enaml-web/blob/master/web/impl/lxml_toolkit_object.py"
    click CExt "https://github.com/codelv/enaml-web/blob/master/src/speedups.c"
    click Client "https://github.com/codelv/enaml-web/blob/master/examples/dataframe_viewer/app.js"
    click Browser "https://github.com/codelv/enaml-web/blob/master/examples/plotly/static/app.js"
    click Examples "https://github.com/codelv/enaml-web/tree/master/examples/"
    click Tests "https://github.com/codelv/enaml-web/blob/master/tests/conftest.py"
    click CI "https://github.com/codelv/enaml-web/blob/master/.github/workflows/ci.yml"
    click Docs "https://github.com/codelv/enaml-web/tree/master/docs/"

    %% Styles
    classDef user fill:#e0ffe0,stroke:#006600
    classDef lib fill:#e0e0ff,stroke:#000080
    classDef impl fill:#e0f0f0,stroke:#006060
    classDef ext fill:#f0f0f0,stroke:#666666
    classDef infra fill:#fff0e0,stroke:#804000
```
