# michal-laskowski/wax architecture

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

- Interactive diagram: https://gitdiagram.com/michal-laskowski/wax
- Repository: https://github.com/michal-laskowski/wax

## Overview

##### Project Type & Purpose
- This project is a Go library designed to integrate JSX/TSX-based view rendering directly within Go applications. It is used to achieve server-side rendering (SSR) without a separate JavaScript runtime.
- The README emphasizes key features such as hot reloading, dynamic view compilation, TypeScript model generation, and integration with common Go web frameworks like net/http and Echo. This tells us that the library is essential for dynamic, component-based view rendering on the server side.

##### Analyzing the File Structure
- Top-Level Files: The key Go files (engine.go, jsx.go, viewResolver_fs.go, and writer.go) indicate a modular design where each file likely encapsulates a distinct responsibility.
- No separate directories for frontend or backend suggests that the library is a singular component with a few well-defined modules rather than segmented services.
- Accompanying build files (go.mod, go.sum) tell us the project is straightforward in structure.

##### Identifying Main System Components
- Renderer Engine (engine.go): The core service that coordinates view rendering.
- JSX/TSX Parser/Compiler (jsx.go): Responsible for dynamically compiling or interpreting JSX/TSX code within Go.
- View Resolver (viewResolver_fs.go): Handles file system lookups (or later embed.FS lookups) to locate view files by name.
- Output Writer (writer.go): Likely responsible for outputting the final HTML after rendering.
- Optional (external integration layer): Integration points with HTTP handlers (as shown in the README example using net/http and Echo).

- The HTTP Handler invokes the Renderer Engine.
- The Renderer Engine calls the View Resolver to locate the appropriate JSX/TSX view file. This resolver may have a fallback mechanism (e.g., caching, file system lookup).
- Once the view is located, the JSX/TSX Parser processes the view file, converting JSX syntax into rendered HTML.
- The Writer then takes the output from the renderer pipeline and sends the HTML back in the HTTP response.
- Optional flow: indicate that in development mode, a hot reload mechanism listens for file changes and prompts the view resolver (or caching mechanism) to refresh the view without a server restart.

##### Architectural Patterns & Design Principles
- Modular Design: The separation of different responsibilities (rendering, parsing, view resolution, and writing) highlights the single-responsibility principle.
- Dynamic Compilation & Caching: The system supports hot reloading (development) and embed.FS based delivery (production), suggesting a dynamic compilation strategy paired with caching.
- Integration with External Frameworks: Emphasize that the library’s design allows it to plug easily into various HTTP frameworks without enforcing a heavy architecture.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Integration Layer
    subgraph "External Integration"
        A["HTTP Handler"]:::external
    end

    %% Core SSR Pipeline
    subgraph "Core SSR Pipeline"
        B["Renderer Engine (engine.go)"]:::internal
        C["View Resolver (viewResolver_fs.go)"]:::internal
        D["JSX/TSX Parser/Compiler (jsx.go)"]:::internal
        E["Output Writer (writer.go)"]:::internal
    end

    %% Development Tools
    subgraph "Development Tools"
        F["Hot Reload Service"]:::dev
    end

    %% Connections
    A -->|"invokes"| B
    B -->|"calls"| C
    C -->|"retrieves"| D
    D -->|"renders"| E
    E -->|"streams_response"| A
    F -.->|"hot_reload"| C

    %% Click Events
    click B "https://github.com/michal-laskowski/wax/blob/master/engine.go"
    click C "https://github.com/michal-laskowski/wax/blob/master/viewResolver_fs.go"
    click D "https://github.com/michal-laskowski/wax/blob/master/jsx.go"
    click E "https://github.com/michal-laskowski/wax/blob/master/writer.go"

    %% Styles
    classDef external fill:#f9a,stroke:#333,stroke-width:2px;
    classDef internal fill:#bbf,stroke:#333,stroke-width:2px;
    classDef dev fill:#cfc,stroke:#333,stroke-width:2px,stroke-dasharray: 5 5;
```
