# arizona-framework/arizona architecture

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

- Interactive diagram: https://gitdiagram.com/arizona-framework/arizona
- Repository: https://github.com/arizona-framework/arizona

## Overview

Based on our analysis, Arizona is a web framework for Erlang. It provides a full-stack solution to serve dynamic HTML (with dynamic Erlang code embedded) via views, templates, and layouts, while also handling client interactions (e.g., via WebSocket and HTTP routes) and serving static assets. The project structure indicates that it is not only the framework itself (with many Erlang modules in the src folder, test suites, and configuration files) but also an example application (with assets, client-side JS, and specific view/component modules) that shows how to use the framework.

##### Main components
– arizona_config, arizona_diff, arizona_parser, arizona_renderer, etc.
– View and layout modules (e.g., arizona_view, arizona_layout, arizona_view_handler) indicate a rendering mechanism for HTML templates.
– Specialized modules to handle static assets, JavaScript communication (arizona_js), and WebSocket (arizona_websocket).
- Template Engine & Templating System:
– Shows how HTML-level templates include embedded Erlang code (using curly braces). This is central to how the framework dynamically constructs views.
- Web Server & HTTP Routes:
– Arizona integrates with Cowboy for HTTP serving. In the generated config (sys.config) routes are defined:
- Static file routes for assets, such as “/assets/[...]” served as static content.
- Dynamic routes – for views via arizona_view_handler.
- WebSocket & Real-time Updates:
– Interaction letting client events (e.g., button click) to be handled in modules like arizona_example_counter and arizona:handle_event/4.
– Use of morphdom for efficient DOM patching is a key runtime process.
- Client-side Assets and JS:
– The assets folder (and its subdirectories in both assets and priv/static) contains JavaScript modules that include connection initialization (arizona.connect()) and patches for dynamic behaviors.
- Build and Development Infrastructure:
– Files like rebar.config, rebar.lock, and various configuration files (esbuild, babel, eslint, prettier) show the integration of build tools ensuring the project is maintainable and standards-compliant.
- Testing Infrastructure:
– Test suites written in Erlang (in test/) to validate view logic, parsing, rendering, etc.

##### Relationships and Interactions
– A client HTTP request hitting a Cowboy route (defined in the sys.config) which dispatches the request to a specific view handler.
– The view handler processing the request using Arizona’s rendering modules, eventually producing rendered HTML (using the layout and view templates).
– If dynamic interactions occur (e.g., a button triggers an event), the client JavaScript sends a WebSocket event to modules like arizona_example_counter, which in turn trigger arizona:handle_event/4 to update state and produce a small payload that is sent back to the client.
- An additional pathway shows how static assets (such as JS files) are served by the server from the priv/ directory.

##### Architectural Patterns and Design Principles
- MVC-like Separation of Concerns:
– Although not explicitly labeled MVC, the separation between view templates, layout files, and the business logic (in the Erlang backend) mimics that pattern.
- Component-Based Rendering:
– Modules like arizona_example_components show a component setup where small reusable UI elements (in this case, a button) are defined and dynamically embedded.
- Event-driven and Real-time Data Flow:
– Use of WebSocket and event-driven functions (handle_event/4 in various modules) emphasize reactive design.
- Development Pipelines and Automation:
– GitHub workflows and build configurations (e.g., esbuild, babel, eslint, rebar) indicate standard CI/CD practices.

##### Relevant Technologies, Frameworks, or Libraries
- Erlang for back-end processing.
- rebar/rebar3 as build/dependency management tools.
- Cowboy as the HTTP/WebSocket server.
- morphdom (via included JS library) for efficient DOM patching.
- JavaScript modules (ESM) for client-side behavior and asset management.
- Config files (e.g., babel, eslint, prettier) indicate adherence to modern JavaScript development practices.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client"
        C1("Client (Browser)"):::client
    end

    %% HTTP Server Layer (Cowboy)
    subgraph "HTTP Server Layer (Cowboy)"
        S1("Cowboy HTTP Server"):::server
    end

    %% Arizona Core Engine
    subgraph "Arizona Core Engine"
        E1("arizona_config"):::erlang
        E2("arizona_diff"):::erlang
        E3("arizona_parser"):::erlang
        E4("arizona_renderer"):::erlang
        E5("arizona_view"):::erlang
        E6("arizona_view_handler"):::erlang
        E7("arizona_websocket"):::erlang
        E8("arizona_static"):::erlang
    end

    %% Template & View Components
    subgraph "Template & View Components"
        T1("arizona_example_template"):::template
        T2("arizona_example_template_new_id"):::template
    end

    %% WebSocket & Event Processing
    subgraph "WebSocket & Event Processing"
        W1("arizona_example_counter"):::ws
    end

    %% Static Assets (Client-side JS & Static Files)
    subgraph "Static Assets"
        A1("arizona.mjs"):::js
        A2("arizona-patch.mjs"):::js
        A3("arizona-worker.mjs"):::js
        A4("arizona-patch.test.js"):::js
        A5("Static Assets (priv/static/assets/js)"):::js
    end

    %% Build and Development Infrastructure
    subgraph "Build & CI/CD"
        B1("rebar.config"):::build
        B2("rebar.lock"):::build
        B3("package.json"):::build
        B4("babel.config.json"):::build
        B5("esbuild.config.mjs"):::build
        B6("eslint.config.mjs"):::build
        B7("prettier.config.mjs"):::build
        B8("CI/CD Workflows (.github/workflows)"):::build
    end

    %% Testing Infrastructure
    subgraph "Testing Infrastructure"
        TST1("Test Suites (test)"):::test
    end

    %% Data Flow Connections
    C1 -->|"HTTP_request"| S1
    S1 -->|"Route_to_ViewHandler"| E6
    E6 -->|"Invoke_Renderer"| E4
    E4 -->|"Rendered_HTML"| S1
    S1 -->|"HTTP_response"| C1
    S1 -->|"Serve_Static"| A5
    A5 -->|"Static_Content"| C1
    C1 ---|"Loads_JS"| A1
    C1 --- A2
    C1 --- A3
    C1 --- A4

    %% Template Rendering Flow
    E6 -->|"Render_View"| T1
    T1 -->|"Template_Output"| E4
    E6 -->|"Also_uses_View"| E5

    %% WebSocket Flow
    C1 ---|"WS_Connection"| E7
    E7 -->|"Process_Event"| W1
    W1 -->|"Update_State"| E7
    E7 ---|"WS_Response"| C1

    %% Build and Testing Relationships (Development Pipeline)
    B8 ---|"Deploys"| E1
    TST1 ---|"Validates"| E1

    %% Styles
    classDef client fill:#FAD02E,stroke:#333,stroke-width:2px;
    classDef server fill:#FB8C00,stroke:#333,stroke-width:2px;
    classDef erlang fill:#90CAF9,stroke:#1E88E5,stroke-width:2px;
    classDef template fill:#FFF59D,stroke:#FBC02D,stroke-width:2px;
    classDef ws fill:#A5D6A7,stroke:#43A047,stroke-width:2px;
    classDef js fill:#CE93D8,stroke:#8E24AA,stroke-width:2px;
    classDef build fill:#B0BEC5,stroke:#607D8B,stroke-width:2px;
    classDef test fill:#FFAB91,stroke:#EF5350,stroke-width:2px;

    %% Click Events for Core Erlang Modules
    click E1 "https://github.com/arizona-framework/arizona/blob/main/src/arizona_config.erl"
    click E2 "https://github.com/arizona-framework/arizona/blob/main/src/arizona_diff.erl"
    click E3 "https://github.com/arizona-framework/arizona/blob/main/src/arizona_parser.erl"
    click E4 "https://github.com/arizona-framework/arizona/blob/main/src/arizona_renderer.erl"
    click E5 "https://github.com/arizona-framework/arizona/blob/main/src/arizona_view.erl"
    click E6 "https://github.com/arizona-framework/arizona/blob/main/src/arizona_view_handler.erl"
    click E7 "https://github.com/arizona-framework/arizona/blob/main/src/arizona_websocket.erl"
    click E8 "https://github.com/arizona-framework/arizona/blob/main/src/arizona_static.erl"

    %% Click Events for Template Engine & Templating System
    click T1 "https://github.com/arizona-framework/arizona/blob/main/test/support/arizona_example_template.erl"
    click T2 "https://github.com/arizona-framework/arizona/blob/main/test/support/arizona_example_template_new_id.erl"

    %% Click Events for Web Server & HTTP Routes
    click S1 "https://github.com/arizona-framework/arizona/blob/main/src/arizona.app.src"

    %% Click Events for WebSocket & Real-time Updates
    click W1 "https://github.com/arizona-framework/arizona/blob/main/test/support/arizona_example_counter.erl"

    %% Click Events for Client-side Assets and JavaScript
    click A1 "https://github.com/arizona-framework/arizona/blob/main/assets/js/arizona.mjs"
    click A2 "https://github.com/arizona-framework/arizona/blob/main/assets/js/arizona-patch.mjs"
    click A3 "https://github.com/arizona-framework/arizona/blob/main/assets/js/arizona-worker.mjs"
    click A4 "https://github.com/arizona-framework/arizona/blob/main/assets/js/arizona-patch.test.js"
    click A5 "https://github.com/arizona-framework/arizona/tree/main/priv/static/assets/js"

    %% Click Events for Build and Development Infrastructure
    click B1 "https://github.com/arizona-framework/arizona/blob/main/rebar.config"
    click B2 "https://github.com/arizona-framework/arizona/blob/main/rebar.lock"
    click B3 "https://github.com/arizona-framework/arizona/blob/main/package.json"
    click B4 "https://github.com/arizona-framework/arizona/blob/main/babel.config.json"
    click B5 "https://github.com/arizona-framework/arizona/blob/main/esbuild.config.mjs"
    click B6 "https://github.com/arizona-framework/arizona/blob/main/eslint.config.mjs"
    click B7 "https://github.com/arizona-framework/arizona/blob/main/prettier.config.mjs"
    click B8 "https://github.com/arizona-framework/arizona/tree/main/.github/workflows"

    %% Click Event for Testing Infrastructure
    click TST1 "https://github.com/arizona-framework/arizona/tree/main/test"
```
