# bigskysoftware/idiomorph architecture

> Architecture diagram of the GitHub repository bigskysoftware/idiomorph, 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/bigskysoftware/idiomorph
- Repository: https://github.com/bigskysoftware/idiomorph

## Overview

##### Main Components

a) Core Components:
- Morphing Engine (src/idiomorph.js)
- ID Set Management System
- DOM Processing Layer
- Configuration Manager
- Integration Layer (src/idiomorph-htmx.js)

b) Supporting Components:
- Head Tag Management System
- Two-Pass Processing System
- Callback System
- Pantry Management (for two-pass mode)

**┌─ External Integrations Layer ─────────────────┐**
- HTMX Integration                           │
- Turbo Integration                          │
- ┬───────────────────────────┘
- ↓
**┌─ Public API Layer ───────────────────────────┐**
- morph() Method                             │
- Configuration Interface                    │
- ┬───────────────────────────┘
- ↓
**┌─ Core Processing Layer ────────────────────────┐**
- ┌─────────────────┐  ┌────────────────────┐   │
- ID Set        │  │  DOM Morphing      │   │
- Management    │←→│  Engine            │   │
- ┘  └────────────────────┘   │
- ┌─────────────────┐  ┌────────────────────┐   │
- Head Tag      │  │  Two-Pass          │   │
- Manager       │  │  Processor         │   │
- ┘  └────────────────────┘   │
- ┘

##### Data Flow Indicators

- Input flow: HTML/DOM nodes → ID Set Creation → Morphing Process
- Two-pass flow: Initial Morph → Pantry Storage → Final Placement
- Callback execution points
- Configuration application points

##### Implementation Details

Notes for:
- Browser API dependencies
- Performance considerations
- State preservation mechanisms
- Integration points with frameworks

##### Integration capabilities with HTMX and other frameworks

Keep the abstraction level focused on the architectural components while providing enough detail to understand the unique ID Set-based morphing approach that makes Idiomorph special.

## Diagram (Mermaid)

```mermaid
graph TB
    %% Styles
    classDef core fill:#2b6cb0,stroke:#1a4971,color:white
    classDef integration fill:#48bb78,stroke:#2f855a,color:white
    classDef testing fill:#ed8936,stroke:#c05621,color:white
    classDef config fill:#805ad5,stroke:#553c9a,color:white
    classDef build fill:#718096,stroke:#4a5568,color:white
    classDef demo fill:#f56565,stroke:#c53030,color:white

    %% External Integrations Layer
    subgraph IntegrationsLayer
        HTMX["HTMX Integration"]
        Turbo["Turbo Integration"]
    end

    %% Public API Layer
    subgraph APILayer
        MorphAPI["Morph() Method"]
        ConfigAPI["Configuration Interface"]
    end

    %% Core Processing Layer
    subgraph CoreLayer
        Engine["Core Morphing Engine"]:::core
        IDManager["ID Set Management"]:::core
        HeadManager["Head Tag Manager"]:::core
        TwoPass["Two-Pass Processor"]:::core
        Callbacks["Callback System"]:::core
        Pantry["Pantry Management"]:::core
    end

    %% Testing Components
    subgraph TestingLayer
        CoreTests["Core Tests"]:::testing
        HeadTests["Head Tests"]:::testing
        TwoPassTests["Two-Pass Tests"]:::testing
        HookTests["Hook Tests"]:::testing
        IntegrationTests["Integration Tests"]:::testing
        PerfTests["Performance Tests"]:::testing
        TestUtils["Test Utilities"]:::testing
        Fixtures["Test Fixtures"]:::testing
    end

    %% Build Outputs
    subgraph BuildLayer
        AMD["AMD Build"]:::build
        CommonJS["CommonJS Build"]:::build
        ESM["ESM Build"]:::build
        HTMXBuild["HTMX Integration Build"]:::build
    end

    %% Demo
    Demo["Demo Implementation"]:::demo

    %% Relationships
    HTMX --> MorphAPI
    Turbo --> MorphAPI
    MorphAPI --> Engine
    ConfigAPI --> Engine
    Engine <--> IDManager
    Engine <--> HeadManager
    Engine <--> TwoPass
    Engine <--> Callbacks
    TwoPass <--> Pantry

    %% Test Relationships
    Engine --> CoreTests
    HeadManager --> HeadTests
    TwoPass --> TwoPassTests
    Callbacks --> HookTests
    HTMX --> IntegrationTests
    Engine --> PerfTests
    TestUtils --> CoreTests
    Fixtures --> CoreTests

    %% Build Relationships
    Engine --> AMD
    Engine --> CommonJS
    Engine --> ESM
    HTMX --> HTMXBuild

    %% Click Events
    click Engine "https://github.com/bigskysoftware/idiomorph/blob/main/src/idiomorph.js"
    click HTMX "https://github.com/bigskysoftware/idiomorph/blob/main/src/idiomorph-htmx.js"
    click HeadManager "https://github.com/bigskysoftware/idiomorph/blob/main/test/head.js"
    click TwoPass "https://github.com/bigskysoftware/idiomorph/blob/main/test/two-pass.js"
    click Callbacks "https://github.com/bigskysoftware/idiomorph/blob/main/test/hooks.js"
    click CoreTests "https://github.com/bigskysoftware/idiomorph/blob/main/test/core.js"
    click IntegrationTests "https://github.com/bigskysoftware/idiomorph/blob/main/test/htmx-integration.js"
    click PerfTests "https://github.com/bigskysoftware/idiomorph/blob/main/test/perf.js"
    click Demo "https://github.com/bigskysoftware/idiomorph/blob/main/test/demo/demo.html"
    click AMD "https://github.com/bigskysoftware/idiomorph/blob/main/dist/idiomorph.amd.js"
    click CommonJS "https://github.com/bigskysoftware/idiomorph/blob/main/dist/idiomorph.cjs.js"
    click ESM "https://github.com/bigskysoftware/idiomorph/blob/main/dist/idiomorph.esm.js"
    click HTMXBuild "https://github.com/bigskysoftware/idiomorph/blob/main/dist/idiomorph-htmx.js"
    click TestUtils "https://github.com/bigskysoftware/idiomorph/blob/main/test/lib/utilities.js"
    click Fixtures "https://github.com/bigskysoftware/idiomorph/blob/main/test/lib/fixture.js"
```
