# vaadin/hilla-crm-tutorial architecture

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

- Interactive diagram: https://gitdiagram.com/vaadin/hilla-crm-tutorial
- Repository: https://github.com/vaadin/hilla-crm-tutorial

## Overview

##### Project Type and Purpose
- This is a full-stack CRM (Customer Relationship Management) application built with Hilla, combining a Spring Boot backend and a React/TypeScript frontend.
- The README confirms it is a tutorial/example app demonstrating Hilla’s integration of server-side Java services with a client-side React UI.

##### High-Level Architecture Components
a. Frontend
- TypeScript/React UI in src/main/frontend
- Vite development server (vite.config.ts) and tsconfig.json for bundling
- Themes and static assets under src/main/frontend/themes and src/main/resources/META-INF/resources
b. Backend
- Spring Boot application (Application.java)
- Hilla-powered endpoints auto-exposed to the client
- JPA entities and repositories (data package)
- Service layer (CRMService) containing business logic
c. Database
- In-memory or external relational database configured via application.properties
- Schema/data initialized from data.sql
d. Build & Deployment
- Maven wrapper (.mvn, mvnw) drives both Java and frontend build
- Production bundle in target/hilla-crm-1.0-SNAPSHOT.jar
- Static resources packaged into the JAR under META-INF/resources

##### Relationships and Data Flow
- User interacts with the browser UI (React/Hilla components).
- UI calls backend endpoints generated by Hilla (over HTTP/JSON, using the Connect library).
- Backend endpoints delegate to CRMService.
- CRMService uses JPA repositories (CompanyRepository, ContactRepository) to read/write the database.
- Results flow back through the same chain to update the UI.

##### Architectural Patterns & Design Principles
- Layered architecture (Controller/Endpoint → Service → Repository → Database)
- Convention-over-configuration via Spring Boot and Hilla
- Single-Page Application pattern on the frontend with routing under src/main/frontend/views
- Resource bundling: frontend assets compiled by Vite, then served from META-INF/resources

##### Key Technologies & Frameworks
- Java, Spring Boot, Spring Data JPA, Hilla (Vaadin Connect)
- React, TypeScript, Vite, Node.js (via package.json)
- Maven for multi-module build and packaging

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Frontend Layer
    subgraph "Frontend" 
        direction TB
        Browser["Browser UI<br/>(React/Hilla)"]:::frontend
        ViteConf["vite.config.ts"]:::frontend
        TSConf["tsconfig.json"]:::frontend
        Package["package.json<br/>package-lock.json"]:::frontend
        Views["Views (SPA Routes)"]:::frontend
        Themes["Themes"]:::frontend
        Assets["Static Assets"]:::frontend
    end

    %% Build & Deployment
    subgraph "Build & Deployment"
        direction TB
        Maven["Maven Wrapper & Build<br/>(.mvn/, mvnw)"]:::infra
        ProdBundle["Prod Frontend Bundle"]:::infra
    end

    %% Backend Layer
    subgraph "Backend"
        direction TB
        App["Spring Boot App<br/>(Application.java)"]:::backend
        Endpoints["Hilla Endpoints"]:::backend
        Service["CRMService"]:::backend
        subgraph "Data Layer"
            direction TB
            Entities["JPA Entities"]:::backend
            Repos["JPA Repositories"]:::backend
        end
        Config["application.properties"]:::infra
        DataSQL["data.sql"]:::infra
    end

    %% Database
    Database["Relational Database"]:::db

    %% Data Flow
    Browser -->|calls API| Endpoints
    Endpoints -->|delegates| Service
    Service -->|uses| Repos
    Repos -->|CRUD| Database
    Database -->|returned data| Repos
    Repos -->|returns| Service
    Service -->|responds| Endpoints
    Endpoints -->|updates UI| Browser

    %% Build Flow
    Maven -->|runs Vite build| ViteConf
    Maven -->|bundles TS| TSConf
    Maven -->|installs deps| Package
    ViteConf --> ProdBundle
    TSConf --> ProdBundle
    Package --> ProdBundle
    ProdBundle -->|packaged into| App
    Assets -->|served from| App

    %% Click Events
    click Browser "https://github.com/vaadin/hilla-crm-tutorial/tree/v24/src/main/frontend"
    click ViteConf "https://github.com/vaadin/hilla-crm-tutorial/blob/v24/vite.config.ts"
    click TSConf "https://github.com/vaadin/hilla-crm-tutorial/blob/v24/tsconfig.json"
    click Package "https://github.com/vaadin/hilla-crm-tutorial/blob/v24/package.json"
    click Views "https://github.com/vaadin/hilla-crm-tutorial/tree/v24/src/main/frontend/views"
    click Themes "https://github.com/vaadin/hilla-crm-tutorial/tree/v24/src/main/frontend/themes/hilla-crm"
    click Assets "https://github.com/vaadin/hilla-crm-tutorial/tree/v24/src/main/resources/META-INF/resources"
    click App "https://github.com/vaadin/hilla-crm-tutorial/blob/v24/src/main/java/com/example/application/Application.java"
    click Service "https://github.com/vaadin/hilla-crm-tutorial/blob/v24/src/main/java/com/example/application/services/CRMService.java"
    click Entities "https://github.com/vaadin/hilla-crm-tutorial/blob/v24/src/main/java/com/example/application/data/AbstractEntity.java"
    click Repos "https://github.com/vaadin/hilla-crm-tutorial/blob/v24/src/main/java/com/example/application/data/CompanyRepository.java"
    click Config "https://github.com/vaadin/hilla-crm-tutorial/blob/v24/src/main/resources/application.properties"
    click DataSQL "https://github.com/vaadin/hilla-crm-tutorial/blob/v24/src/main/resources/data.sql"
    click Maven "https://github.com/vaadin/hilla-crm-tutorial/tree/v24/.mvn/"
    click Maven "https://github.com/vaadin/hilla-crm-tutorial/tree/v24/mvnw"
    click Maven "https://github.com/vaadin/hilla-crm-tutorial/blob/v24/pom.xml"
    click ProdBundle "https://github.com/vaadin/hilla-crm-tutorial/blob/v24/src/main/bundles/prod.bundle"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0366D6, color:#0366D6
    classDef backend fill:#D0F1D0,stroke:#2D9F2, color:#2D9F2
    classDef db fill:#FFE8D0,stroke:#DD6E31, color:#DD6E31
    classDef infra fill:#E0E0E0,stroke:#888888, color:#444444
```
