# abdheshnayak/gohtmlx architecture

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

- Interactive diagram: https://gitdiagram.com/abdheshnayak/gohtmlx
- Repository: https://github.com/abdheshnayak/gohtmlx

## Overview

##### Main Components
- CLI/Entry Point: At the top level you have main.go (and even an example/main.go) which handles the application startup and accepts parameters (for example, --src and --dist).
- Input Component / File Handler: Components in pkg/utils (e.g., files-finder.go) and possibly others that scan the source directory to locate HTML component definitions.
- HTML Component Parser: Modules in pkg/element (element.go, html.go, utils.go) that are responsible for parsing the HTML templates with the component definitions (and “+ define” syntax) and extracting the metadata (props, HTML structure).
- Transpiler / Code Generator: Found in pkg/gocode where the actual transpilation process occurs. This component transforms the parsed HTML components into structured Go code.
- Utility Components: The pkg/utils package holds helper functions (like fns.go and html-accumulator.go) that support file handling, HTML accumulation, and other miscellaneous operations.
- (Optional) Development/Example Runner: The “example” folder provides sample usage, configuration (Taskfile.yml, tailwind.config.js), and a demonstration of the generated component consumption.

##### Relationships and Interactions
- The CLI (main.go) accepts arguments specifying the source (HTML components) and destination directories. It then triggers the processing pipeline.
- The Input Handler traverses the source directory to identify HTML files containing component definitions.
- The Parser (in pkg/element) processes the component definitions, splitting them into their “props” and “html” sections.
- The Transpiler (in pkg/gocode) takes the output from the Parser and converts it into valid Go code, creating Go structures/functions for each component.
- Utility functions (from pkg/utils) support various ancillary tasks (such as file operations and HTML string accumulation).
- Finally, the generated Go code is used by a sample main function (as seen in the example) for rendering the final dynamic HTML.

##### Architectural Patterns and Design Principles
- Modularity: The separation into different packages (element, gocode, and utils) demonstrates a clean modular design, where each package handles a specific responsibility.
- Declarative to Imperative Transformation: The project uses a declarative HTML-like syntax that is transpiled into imperative Go code.
- Server-Side Rendering Focus: Unlike client-side libraries like React or JSX, this tool is designed for server-side dynamic HTML generation.

##### Relevant Technologies and Frameworks
- The project is written in Go, with standard Go module management (go.mod, go.sum).
- The tooling includes Taskfile for development automation and Tailwind configuration in the example (often for styling the example UI).
- The usage scenarios and example indicate that the generated Go code is consumed in standard Go applications.

##### Specific Elements
- CLI/Entry Point (main.go)
- Input Component / File Scanner (pkg/utils/files-finder.go)
- HTML & Component Parser (pkg/element/*)
- Transpiler / Code Generator (pkg/gocode/main.go)
- Utility/Helper Functions (pkg/utils/*)
- Example/Usage (example/main.go) to show how output is rendered.
- Any dependencies, such as external configuration (Taskfile.yml, Tailwind config) that help in the development cycle.

##### Detail
- Core pipeline: from component definition in HTML to rendering dynamic HTML via generated Go code.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Entry Layer
    cliEntry["CLI Entry (main.go)"]:::cli

    %% File Handling Layer
    fileHandler["Input Handler (files-finder.go)"]:::input

    %% Parsing Layer
    subgraph "HTML Component Parser"
        parserElement["Element Parser (element.go)"]:::parser
        parserHTML["HTML Parser (html.go)"]:::parser
        parserUtils["Parser Utils (utils.go)"]:::parser
    end

    %% Transpilation Layer
    transpiler["Transpiler/Code Generator (main.go)"]:::transpiler

    %% Output Layer
    subgraph "Rendered Output"
        exampleRunner["Example Runner (example/main.go)"]:::example
    end

    %% Development Config Subgraph
    subgraph "Development Config"
        taskfile["Taskfile (Taskfile.yml)"]:::config
        tailwind["Tailwind Config (tailwind.config.js)"]:::config
        exampleSrc["Example Src (src)"]:::config
    end

    %% Utility Functions Subgraph
    subgraph "Utility Functions"
        fileFns["File Functions (fns.go)"]:::util
        htmlAcc["HTML Accumulator (html-accumulator.go)"]:::util
    end

    %% Pipeline Flow
    cliEntry --> fileHandler
    fileHandler --> parserElement
    fileHandler --> parserHTML
    fileHandler --> parserUtils
    parserElement --> transpiler
    parserHTML --> transpiler
    parserUtils --> transpiler
    transpiler --> exampleRunner
    taskfile --> exampleRunner
    tailwind --> exampleRunner
    exampleSrc --> exampleRunner

    %% Utility Support (dotted connections)
    fileFns -.-> fileHandler
    fileFns -.-> parserElement
    fileFns -.-> transpiler
    htmlAcc -.-> parserHTML
    htmlAcc -.-> transpiler

    %% Click Events
    click cliEntry "https://github.com/abdheshnayak/gohtmlx/blob/main/main.go"
    click fileHandler "https://github.com/abdheshnayak/gohtmlx/blob/main/pkg/utils/files-finder.go"
    click parserElement "https://github.com/abdheshnayak/gohtmlx/blob/main/pkg/element/element.go"
    click parserHTML "https://github.com/abdheshnayak/gohtmlx/blob/main/pkg/element/html.go"
    click parserUtils "https://github.com/abdheshnayak/gohtmlx/blob/main/pkg/element/utils.go"
    click transpiler "https://github.com/abdheshnayak/gohtmlx/blob/main/pkg/gocode/main.go"
    click fileFns "https://github.com/abdheshnayak/gohtmlx/blob/main/pkg/utils/fns.go"
    click htmlAcc "https://github.com/abdheshnayak/gohtmlx/blob/main/pkg/utils/html-accumulator.go"
    click exampleRunner "https://github.com/abdheshnayak/gohtmlx/blob/main/example/main.go"
    click taskfile "https://github.com/abdheshnayak/gohtmlx/blob/main/example/Taskfile.yml"
    click tailwind "https://github.com/abdheshnayak/gohtmlx/blob/main/example/tailwind.config.js"
    click exampleSrc "https://github.com/abdheshnayak/gohtmlx/tree/main/example/src"

    %% Styles
    classDef cli fill:#D6E9C6,stroke:#3C763D,stroke-width:2px;
    classDef input fill:#F2DEDE,stroke:#A94442,stroke-width:2px;
    classDef parser fill:#FCF8E3,stroke:#8A6D3B,stroke-width:2px;
    classDef transpiler fill:#D9EDF7,stroke:#31708F,stroke-width:2px;
    classDef example fill:#EBDEF0,stroke:#8E44AD,stroke-width:2px;
    classDef config fill:#F0E68C,stroke:#B8860B,stroke-width:2px;
    classDef util fill:#E8F8F5,stroke:#1ABC9C,stroke-width:2px;
```
