# bartblast/hologram architecture

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

- Interactive diagram: https://gitdiagram.com/bartblast/hologram
- Repository: https://github.com/bartblast/hologram

## Overview

##### Main Components

A. Compiler System
- Source Code Processing (Elixir)
- AST Transformation
- JavaScript Transpilation
- Asset Management

B. Runtime System
- Client-side Runtime
- Server-side Runtime
- Component System
- Router
- Template Engine

C. Development Tools
- Live Reload System
- Mix Tasks
- Testing Infrastructure

**┌─────────────────────────────────────────────────────────┐**
- Development Layer                       │
- [Mix Tasks] ←→ [Live Reload] ←→ [Testing Framework]    │
- ┤
- Compilation Layer                       │

- [Elixir Source] → [AST] → [IR] → [JavaScript Output]   │
- ↑                                               │
- [Asset Pipeline]                                     │
- ┤
- Runtime Layer                          │

- Server-Side:                                           │
- [Router] ←→ [Controllers] ←→ [Components]              │
- ↕           ↕               ↕                       │
- [Templates] ←→ [Sockets] ←→ [State Management]         │

- Client-Side:                                           │
- [JS Runtime] ←→ [Virtual DOM] ←→ [Event System]        │
- ┘

##### Key Relationships to Highlight

a. Compilation Flow:
- How Elixir code flows through the compiler pipeline
- Asset processing and bundling
- Generation of JavaScript output

b. Runtime Communication:
- Server-client communication through sockets
- Component lifecycle and state management
- Event handling and DOM updates

c. Development Workflow:
- Live reload system interaction
- Testing infrastructure integration
- Mix task integration

##### Important Subsystems

- Template Engine (lib/hologram/template/*)
- Router System (lib/hologram/router/*)
- Component System (lib/hologram/component.ex)
- Socket Communication (lib/hologram/socket/*)
- Asset Management (lib/hologram/assets/*)

##### Implementation Details

- Elixir-to-JavaScript transpilation process
- Component lifecycle management
- State synchronization between server and client
- Asset compilation and delivery
- Template rendering pipeline

##### External Dependencies

Integration points with:

- Phoenix framework (if used)
- Browser runtime
- Asset pipeline
- Development tools

Use standardized symbols:
- Rectangles: Modules/Components
- Diamonds: Decision Points
- Clouds: External Services

Remember to maintain a balance between detail and clarity, focusing on the architectural relationships while avoiding overwhelming technical specifics.

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph Development
        MixTasks["Mix Tasks"]:::dev
        LiveReload["Live Reload"]:::dev
        Testing["Testing Framework"]:::dev
        
        MixTasks <--> LiveReload
        LiveReload <--> Testing
    end

    subgraph Compilation
        ElixirSource["Elixir Source"]:::compiler
        AST["AST Transformer"]:::compiler
        IR["Intermediate Rep"]:::compiler
        JSOutput["JavaScript Output"]:::compiler
        AssetPipeline["Asset Pipeline"]:::compiler
        
        ElixirSource --> AST
        AST --> IR
        IR --> JSOutput
        AssetPipeline --> ElixirSource
    end

    subgraph "Server Runtime"
        Router["Router"]:::server
        Controllers["Controllers"]:::server
        Components["Components"]:::server
        Templates["Templates"]:::server
        Sockets["Sockets"]:::server
        StateManagement["State Management"]:::server
        
        Router <--> Controllers
        Controllers <--> Components
        Components <--> Templates
        Templates <--> Sockets
        Sockets <--> StateManagement
    end

    subgraph "Client Runtime"
        JSRuntime["JS Runtime"]:::client
        VirtualDOM["Virtual DOM"]:::client
        EventSystem["Event System"]:::client
        ComponentRegistry["Component Registry"]:::client
        
        JSRuntime <--> VirtualDOM
        VirtualDOM <--> EventSystem
        EventSystem <--> ComponentRegistry
    end

    Development --> Compilation
    Compilation --> |"Transpiled Code"| JSRuntime
    Sockets <--> |"WebSocket"| JSRuntime

    classDef dev fill:#4a9eff,stroke:#333,stroke-width:2px
    classDef compiler fill:#50c878,stroke:#333,stroke-width:2px
    classDef server fill:#ffa500,stroke:#333,stroke-width:2px
    classDef client fill:#9370db,stroke:#333,stroke-width:2px

    click MixTasks "https://github.com/bartblast/hologram/blob/master/lib/mix/tasks/compile/hologram.ex"
    click LiveReload "https://github.com/bartblast/hologram/blob/master/lib/hologram/live_reload.ex"
    click AST "https://github.com/bartblast/hologram/blob/master/lib/hologram/compiler/transformer.ex"
    click JSOutput "https://github.com/bartblast/hologram/blob/master/lib/hologram/compiler/encoder.ex"
    click AssetPipeline "https://github.com/bartblast/hologram/blob/master/lib/hologram/assets/manifest_cache.ex"
    click Router "https://github.com/bartblast/hologram/blob/master/lib/hologram/router.ex"
    click Controllers "https://github.com/bartblast/hologram/blob/master/lib/hologram/controller.ex"
    click Components "https://github.com/bartblast/hologram/blob/master/lib/hologram/component.ex"
    click Templates "https://github.com/bartblast/hologram/blob/master/lib/hologram/template.ex"
    click Sockets "https://github.com/bartblast/hologram/blob/master/lib/hologram/socket.ex"
    click JSRuntime "https://github.com/bartblast/hologram/blob/master/assets/js/client.mjs"
    click VirtualDOM "https://github.com/bartblast/hologram/blob/master/assets/js/vdom.mjs"
    click ComponentRegistry "https://github.com/bartblast/hologram/blob/master/assets/js/component_registry.mjs"
```
