# hyperfiddle/electric architecture

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

- Interactive diagram: https://gitdiagram.com/hyperfiddle/electric
- Repository: https://github.com/hyperfiddle/electric

## Overview

##### Main Components

a) Compiler Layer:
- Electric Compiler component that performs graph analysis
- Key compiler modules (visible in src/hyperfiddle/electric/impl/):
- lang3 (language implementation)
- runtime3 (runtime system)
- cljs_analyzer2 (ClojureScript analysis)

b) Runtime Layer:
- Differential dataflow engine
- Network boundary inference system

c) Integration Layer:
- Adapters (electric_httpkit_adapter3, electric_ring_adapter3)
- DOM integration (electric_dom3)
- Form handling (electric_forms3)

##### Relationships and Data Flow

- Compile-time flow: Source code → Compiler → Generated client/server code
- Runtime flow: Client ↔ Server differential dataflow
- DOM updates: Runtime → Browser DOM

##### Specific Implementation Details

- Reactive primitives (from src/hyperfiddle/electric3.cljc)
- Incremental sequence handling (src/hyperfiddle/incseq/)
- Development tooling (debug3, trace3)

**[Source Code]**
- ↓
**[Electric Compiler]**
- ↓
**[Generated Code]**
- ↙     ↘
**[Client] ↔ [Server]**
- ↓
**[Browser DOM]**

##### Important Notes

- A note about the differential dataflow nature
- Network transparency feature
- Reactive programming model
- Where custom adapters can be plugged in

##### Technical Details to Highlight

- ClojureScript/Clojure interop
- Missionary integration for concurrency
- DOM manipulation system
- Network protocol (referenced in docs/electric-protocol.md)

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph Compiler
        SourceCode[Source Code]
        CompilerCore["Electric Compiler Core"]:::compiler
        CLJSAnalyzer["ClojureScript Analyzer"]:::compiler
        RuntimeSystem["Runtime System"]:::runtime
    end

    subgraph Runtime
        ClientRuntime["Client Runtime"]:::runtime
        ServerRuntime["Server Runtime"]:::runtime
        DiffEngine["Differential Dataflow Engine"]:::runtime
    end

    subgraph Integration
        HTTPKit["HTTP Kit Adapter"]:::adapter
        RingAdapter["Ring Adapter"]:::adapter
        DOMIntegration["DOM Integration"]:::ui
        FormHandling["Form Handling"]:::ui
        DOMEvents["DOM Event Handler"]:::ui
        DOMProps["DOM Properties"]:::ui
    end

    subgraph Core
        ReactPrimitives["Reactive Primitives"]:::core
        IncSeq["Incremental Sequence Handler"]:::core
    end

    subgraph Development
        Debug["Debug Tools"]:::dev
        Trace["Trace System"]:::dev
        NetProtocol["Network Protocol"]:::dev
    end

    SourceCode --> CompilerCore
    CompilerCore --> CLJSAnalyzer
    CLJSAnalyzer --> RuntimeSystem
    RuntimeSystem --> ClientRuntime
    RuntimeSystem --> ServerRuntime
    
    ClientRuntime <--> ServerRuntime
    DiffEngine --- ClientRuntime
    DiffEngine --- ServerRuntime
    
    ClientRuntime --> DOMIntegration
    DOMIntegration --> DOMEvents
    DOMIntegration --> DOMProps
    
    ServerRuntime --> HTTPKit
    ServerRuntime --> RingAdapter
    
    ReactPrimitives --> RuntimeSystem
    IncSeq --> RuntimeSystem
    
    FormHandling --> DOMIntegration
    
    Debug --- ClientRuntime
    Debug --- ServerRuntime
    Trace --- RuntimeSystem
    NetProtocol --- RuntimeSystem

    %% Click events for component mapping
    click CompilerCore "https://github.com/hyperfiddle/electric/blob/master/src/hyperfiddle/electric/impl/lang3.clj"
    click CLJSAnalyzer "https://github.com/hyperfiddle/electric/blob/master/src/hyperfiddle/electric/impl/cljs_analyzer2.clj"
    click RuntimeSystem "https://github.com/hyperfiddle/electric/blob/master/src/hyperfiddle/electric/impl/runtime3.cljc"
    click ClientRuntime "https://github.com/hyperfiddle/electric/blob/master/src/hyperfiddle/electric_client3.cljs"
    click HTTPKit "https://github.com/hyperfiddle/electric/blob/master/src/hyperfiddle/electric_httpkit_adapter3.clj"
    click RingAdapter "https://github.com/hyperfiddle/electric/blob/master/src/hyperfiddle/electric_ring_adapter3.clj"
    click DOMIntegration "https://github.com/hyperfiddle/electric/blob/master/src/hyperfiddle/electric_dom3.cljc"
    click FormHandling "https://github.com/hyperfiddle/electric/blob/master/src/hyperfiddle/electric_forms3.cljc"
    click IncSeq "https://github.com/hyperfiddle/electric/tree/master/src/hyperfiddle/incseq/"
    click Debug "https://github.com/hyperfiddle/electric/blob/master/src/hyperfiddle/electric/debug3.cljc"
    click NetProtocol "https://github.com/hyperfiddle/electric/blob/master/docs/electric-protocol.md"
    click DOMEvents "https://github.com/hyperfiddle/electric/blob/master/src/hyperfiddle/electric_dom3_events.cljc"
    click DOMProps "https://github.com/hyperfiddle/electric/blob/master/src/hyperfiddle/electric_dom3_props.cljc"
    click ReactPrimitives "https://github.com/hyperfiddle/electric/blob/master/src/hyperfiddle/electric3.cljc"
    click Trace "https://github.com/hyperfiddle/electric/blob/master/src/contrib/trace3.cljc"

    %% Styling
    classDef compiler fill:#a8d1f0
    classDef runtime fill:#90EE90
    classDef adapter fill:#FFB347
    classDef ui fill:#FFD700
    classDef core fill:#DDA0DD
    classDef dev fill:#D3D3D3

    %% Legend
    subgraph Legend
        L1["Compiler Components"]:::compiler
        L2["Runtime Components"]:::runtime
        L3["Adapters"]:::adapter
        L4["UI Components"]:::ui
        L5["Core Features"]:::core
        L6["Development Tools"]:::dev
    end
```
