# mcollovati/quarkus-hilla architecture

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

- Interactive diagram: https://gitdiagram.com/mcollovati/quarkus-hilla
- Repository: https://github.com/mcollovati/quarkus-hilla

## Overview

##### Project type and purpose
- This is an **open-source Quarkus extension** (“quarkus-hilla”) that integrates the Hilla full-stack framework into the Quarkus ecosystem.
- It’s **not** a standalone application; it’s a **tool/library** providing build-time processors and runtime components for Hilla features (Endpoints, Reactive Endpoints, Security, Live Reload, codestarts).

##### Top-level module structure
- **commons/**
- deployment/ — build-time Quarkus extension code (processors, ASM visitors, BuildItems)
- runtime/    — runtime support (recorders, servlets, endpoint controllers, security, hot-reload)
- **lit/** and **react/**
- deployment/ — framework-specific build-time integration for Lit or React frontends
- runtime/    — codestarts and runtime metadata for starter projects
- **integration-tests/** — dozens of end-to-end Quarkus + frontend sample apps exercising features
- **etc/**, **.github/**, **pom.xml** — meta/configuration, CI, release scripts

##### Key architectural patterns
- **Quarkus extension model**: separation of *deployment* (build-time code-generation, registration) vs *runtime* (injection, recorder logic).
- **Maven multi-module**: each module produces one Quarkus artifact (extension or codestart templates).
- **Codestarts**: template projects under lit/runtime/src/main/codestarts and react/runtime/src/main/codestarts generate user starter apps.
- **Integration tests**: dynamic sample applications spun up by Selenide, verifying plugin functionality end-to-end.

##### Main components
A. **Maven Reactor** (top-level pom)
B. **Modules**
1. commons-deployment
2. commons-runtime
3. lit-deployment
4. lit-runtime (codestarts)
5. react-deployment
6. react-runtime (codestarts)
7. integration-tests (many child modules)
C. **Quarkus Build Pipeline**
- Quarkus Maven plugin → invokes deployment modules → emits BuildItems, generates Typescript client code → packages extension jar
D. **Quarkus Runtime**
- Extension jar loaded → CDI startup → recorders configure servlets, endpoints, security, hot-reload watchers
E. **Frontend codestarts**
- lit/runtime and react/runtime codestart templates → user “quarkus create app” → generates starter project structure (frontend + backend)

##### Relationships and data flow
1. **Developer builds**: `mvn install` on top-level → phases:
- compile & process commons-deployment → register build-time processors
- compile & process lit-deployment / react-deployment → framework-specific code gen
- compile commons/runtime → runtime classes
- compile lit-runtime / react-runtime → codestart artifacts
2. **Application creation**: Quarkus codestart generator uses codestart templates → produces starter app with `Application.java`, TS frontend, `connect-client.ts`, themes, views.
3. **Runtime launch**: Quarkus bootstrap loads extension → deployment build items already processed → runtime recorders spin up HTTP endpoints, security filters, Atmosphere-based push, live-reload watchers.
4. **Integration tests**: each sample under integration-tests is built and run; Selenide opens browser → verifies generated frontend connects to Quarkus endpoints, security flows, push, CRUD, signals.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Top-level reactor
    Pom["Top-level POM"]:::reactor
    click Pom "https://github.com/mcollovati/quarkus-hilla/blob/main/pom.xml"

    %% Modules clusters
    subgraph "Deployment Modules"
        direction TB
        CD["commons-deployment"]:::build
        click CD "https://github.com/mcollovati/quarkus-hilla/blob/main/commons/deployment/pom.xml"
        LD["lit-deployment"]:::build
        click LD "https://github.com/mcollovati/quarkus-hilla/blob/main/lit/deployment/pom.xml"
        RD["react-deployment"]:::build
        click RD "https://github.com/mcollovati/quarkus-hilla/blob/main/react/deployment/pom.xml"
    end

    subgraph "Runtime Modules"
        direction TB
        CR["commons-runtime"]:::runtime
        click CR "https://github.com/mcollovati/quarkus-hilla/blob/main/commons/runtime/pom.xml"
        LR["lit-runtime"]:::runtime
        click LR "https://github.com/mcollovati/quarkus-hilla/blob/main/lit/runtime/pom.xml"
        RR["react-runtime"]:::runtime
        click RR "https://github.com/mcollovati/quarkus-hilla/blob/main/react/runtime/pom.xml"
    end

    subgraph "Codestarts Templates"
        direction TB
        LCT["Lit Codestarts"]:::codestart
        click LCT "https://github.com/mcollovati/quarkus-hilla/tree/main/lit/runtime/src/main/codestarts"
        RCT["React Codestarts"]:::codestart
        click RCT "https://github.com/mcollovati/quarkus-hilla/tree/main/react/runtime/src/main/codestarts"
    end

    subgraph "Integration Tests"
        direction TB
        IT["integration-tests"]:::test
        click IT "https://github.com/mcollovati/quarkus-hilla/blob/main/integration-tests/pom.xml"
    end

    %% Build pipeline
    Pom -->|"mvn install"| CD
    Pom -->|"mvn install"| LD
    Pom -->|"mvn install"| RD
    Pom -->|"mvn install"| CR
    Pom -->|"mvn install"| LR
    Pom -->|"mvn install"| RR
    CD -->|"build-time processors"| QBP["Quarkus Build Pipeline"]:::pipeline
    LD -->|"framework code-gen"| QBP
    RD -->|"framework code-gen"| QBP
    QBP -->|"generates extension JAR"| ExtJar["Extension JAR"]:::artifact

    %% Deployment internals click events
    click CD "https://github.com/mcollovati/quarkus-hilla/blob/main/commons/deployment/pom.xml"
    click CD_TC "https://github.com/mcollovati/quarkus-hilla/blob/main/commons/deployment/src/main/java/com/github/mcollovati/quarkus/hilla/deployment/TypescriptClientCodeGenProvider.java"
    click CD_EP "https://github.com/mcollovati/quarkus-hilla/blob/main/commons/deployment/src/main/java/com/github/mcollovati/quarkus/hilla/deployment/QuarkusHillaExtensionProcessor.java"
    click CD_NP "https://github.com/mcollovati/quarkus-hilla/blob/main/commons/deployment/src/main/java/com/github/mcollovati/quarkus/hilla/deployment/QuarkusHillaNativeProcessor.java"
    click CD_DU "https://github.com/mcollovati/quarkus-hilla/blob/main/commons/deployment/src/main/java/com/github/mcollovati/quarkus/hilla/deployment/devui/QuarkusHillaDevUICommonsProcessor.java"
    click CD_SP "https://github.com/mcollovati/quarkus-hilla/blob/main/commons/deployment/src/main/java/com/github/mcollovati/quarkus/hilla/deployment/security/QuarkusHillaSecurityProcessor.java"

    %% Runtime internals click events
    click CR_RH "https://github.com/mcollovati/quarkus-hilla/blob/main/commons/runtime/src/main/java/com/github/mcollovati/quarkus/hilla/BodyHandlerRecorder.java"
    click CR_LR "https://github.com/mcollovati/quarkus-hilla/blob/main/commons/runtime/src/main/java/com/github/mcollovati/quarkus/hilla/reload/HillaLiveReloadRecorder.java"
    click CR_SR "https://github.com/mcollovati/quarkus-hilla/blob/main/commons/runtime/src/main/java/com/github/mcollovati/quarkus/hilla/security/HillaSecurityRecorder.java"
    click CR_YAML "https://github.com/mcollovati/quarkus-hilla/blob/main/commons/runtime/src/main/resources/META-INF/quarkus-extension.yaml"

    %% Runtime flow
    ExtJar -->|"Quarkus bootstrap"| QB["Quarkus Bootstrap"]:::runtime
    QB -->|"CDI startup"| CDI["CDI Container"]:::runtime
    CDI -->|"run recorders"| RS["Runtime Recorders"]:::runtime
    RS -->|"configure endpoints, security, reload"| Endpoints["HTTP Endpoints & Hot-Reload"]:::runtime

    %% Codestart flow
    LCT -->|"quarkus create app"| UA["User Starter App"]:::userapp
    RCT -->|"quarkus create app"| UA

    %% Integration tests flow
    IT -->|"build & run sample apps"| SA["Sample Apps"]:::test
    SA -->|"Selenide tests"| Browser["Browser Verification"]:::test
    Browser -->|"calls endpoints"| Endpoints

    %% Styles
    classDef reactor fill:#f2f2f2,stroke:#333,stroke-width:1px;
    classDef build fill:#cce5ff,stroke:#4da3ff,stroke-width:1px;
    classDef runtime fill:#d4edda,stroke:#3cba54,stroke-width:1px;
    classDef codestart fill:#fff3cd,stroke:#ffdd57,stroke-width:1px;
    classDef test fill:#e2e3e5,stroke:#6c757d,stroke-width:1px;
    classDef pipeline fill:#ffe6e6,stroke:#ff8080,stroke-width:1px;
    classDef artifact fill:#e6f7ff,stroke:#80d4ff,stroke-width:1px;
    classDef userapp fill:#e8eaf6,stroke:#5c6bc0,stroke-width:1px;
```
