# cristianandresherrmann/sigelic architecture

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

- Interactive diagram: https://gitdiagram.com/cristianandresherrmann/sigelic
- Repository: https://github.com/cristianandresherrmann/sigelic

## Overview

##### Project type and purpose
- SIGELIC is a full-stack, monolithic web application for automating the end-to-end issuance and renewal of driver’s licenses for a municipality.
- The README confirms: Java 21 + Spring Boot backend, Vaadin 24 UI, MySQL database, Flyway for migrations, and H2 for testing.

##### File structure
- Top-level build and config: pom.xml, Maven wrapper, .env example, Flyway scripts under src/main/resources/db/migration.
- Frontend: Vaadin UI is written in Java under src/main/java/.../views and served by the Spring Boot application. The generated client artifacts appear in src/main/frontend/generated.
- Backend layers under src/main/java/com/example/sigelic:
- config: security and bootstrap
- controller: REST endpoints / Vaadin view controllers
- service: business logic
- repository: Spring Data JPA interfaces
- model: JPA entities
- dto: request/response objects
- mapper: conversion between entities and DTOs
- util: helper classes
- exception: error handling
- Resources: application.properties, static assets (CSS), Flyway SQL migration files.
- Tests: integration and unit tests under src/test and HTTP API tests under tests/.

##### Key insights from README
- How Vaadin interacts with the Spring Boot backend rather than a separate SPA.

a. Main components
- Client Browser
- Vaadin UI layer (server-side rendering)
- Spring MVC / REST Controllers
- Service layer (business rules, transaction management)
- Data layer (Spring Data JPA repositories)
- Database (MySQL in production, H2 in test profile)
- Flyway migrations (runs at startup)
- Spring Security (authN/authZ)
b. Relationships and interactions
1. Browser sends HTTP(S) requests → Vaadin UI endpoints
2. Vaadin invokes Controller methods → Service layer
3. Service layer calls Repository interfaces → Database
4. Flyway executes migration scripts on application startup
5. Spring Security intercepts incoming requests for authentication and authorization
6. Maven builds the entire artifact (packaging frontend resources into the Spring Boot JAR)
c. Architectural patterns and design principles
- Layered (Presentation → Controller → Service → Repository → Database)
- MVC-ish with Vaadin doing the view and controller in Java
- DTOs and Mappers to decouple persistence models from external API
- Exception handling via a GlobalExceptionHandler
- Database versioning with Flyway ensures schema evolution
d. Technologies & frameworks
- Java 21, Spring Boot 3.3.2, Spring Data JPA, Spring Security, Flyway, Lombok
- Vaadin 24 for UI
- MySQL 8.x (H2 for tests)
- Maven for build and dependency management

##### Elements
Browser → Vaadin UI → Controller → Service → Repository → Database
- Business logic (services) in another
- Data access in a third
- External systems (DB, Flyway, Maven build) in a fourth
- Related classes/modules by package layers to show package boundaries.
- Important cross-cutting concerns:
- Authentication & Authorization via Spring Security
- Data validation in DTOs and error handling in GlobalExceptionHandler

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Client Side"
        Browser["Client Browser"]:::external
        StaticAssets["Frontend Assets"]:::external
    end

    subgraph "Server Side"
        SigelicApp["Spring Boot App\nSigelicApplication"]:::app
        Flyway["Flyway Migrations"]:::infra
        Database["Database\nMySQL / H2"]:::db

        subgraph "Configuration"
            ConfigBootstrap["Application Initializer"]:::config
            SecurityConfig["Security Config"]:::security
        end

        subgraph "Presentation Layer"
            VaadinUI["Vaadin UI Layer"]:::ui
            Controllers["Controllers"]:::controller
            ExceptionHandler["Global Exception Handler"]:::exception
        end

        subgraph "Business Layer"
            Services["Service Layer"]:::service
            Mappers["Mappers"]:::service
            DTOs["DTOs"]:::service
            Utils["Utility Classes"]:::utility
        end

        subgraph "Data Layer"
            Repos["Repositories"]:::data
            Entities["JPA Entities"]:::data
        end
    end

    Browser --> StaticAssets
    Browser -->|"HTTP Requests"| SigelicApp
    SigelicApp --> ConfigBootstrap
    SigelicApp --> SecurityConfig
    SigelicApp --> Flyway
    SigelicApp --> VaadinUI
    SigelicApp --> Controllers
    SigelicApp --> Utils
    Flyway --> Database
    VaadinUI --> Controllers
    SecurityConfig --> Controllers
    Controllers --> Services
    Controllers --> ExceptionHandler
    Services --> Repos
    Services --> Mappers
    Services --> ExceptionHandler
    Mappers --> Entities
    Repos --> Entities
    Repos --> Database

    click StaticAssets "https://github.com/cristianandresherrmann/sigelic/tree/master/src/main/frontend"
    click VaadinUI "https://github.com/cristianandresherrmann/sigelic/tree/master/src/main/java/com/example/sigelic/views"
    click SigelicApp "https://github.com/cristianandresherrmann/sigelic/blob/master/src/main/java/com/example/sigelic/SigelicApplication.java"
    click ConfigBootstrap "https://github.com/cristianandresherrmann/sigelic/blob/master/src/main/java/com/example/sigelic/config/ApplicationInitializer.java"
    click SecurityConfig "https://github.com/cristianandresherrmann/sigelic/blob/master/src/main/java/com/example/sigelic/config/SecurityConfig.java"
    click Controllers "https://github.com/cristianandresherrmann/sigelic/tree/master/src/main/java/com/example/sigelic/controller"
    click Services "https://github.com/cristianandresherrmann/sigelic/tree/master/src/main/java/com/example/sigelic/service"
    click Repos "https://github.com/cristianandresherrmann/sigelic/tree/master/src/main/java/com/example/sigelic/repository"
    click Entities "https://github.com/cristianandresherrmann/sigelic/tree/master/src/main/java/com/example/sigelic/model"
    click DTOs "https://github.com/cristianandresherrmann/sigelic/tree/master/src/main/java/com/example/sigelic/dto"
    click Mappers "https://github.com/cristianandresherrmann/sigelic/tree/master/src/main/java/com/example/sigelic/mapper"
    click ExceptionHandler "https://github.com/cristianandresherrmann/sigelic/blob/master/src/main/java/com/example/sigelic/exception/GlobalExceptionHandler.java"
    click Utils "https://github.com/cristianandresherrmann/sigelic/tree/master/src/main/java/com/example/sigelic/util"
    click Flyway "https://github.com/cristianandresherrmann/sigelic/tree/master/src/main/resources/db/migration"

    classDef external fill:#f9f,stroke:#333,stroke-width:1px;
    classDef app fill:#bbf,stroke:#333,stroke-width:1px;
    classDef infra fill:#ffc,stroke:#333,stroke-width:1px;
    classDef db fill:#cfc,stroke:#333,stroke-width:1px;
    classDef config fill:#def,stroke:#333,stroke-width:1px;
    classDef security fill:#fdd,stroke:#333,stroke-width:1px;
    classDef ui fill:#ddf,stroke:#333,stroke-width:1px;
    classDef controller fill:#ffd,stroke:#333,stroke-width:1px;
    classDef service fill:#dfe,stroke:#333,stroke-width:1px;
    classDef data fill:#fed,stroke:#333,stroke-width:1px;
    classDef exception fill:#fdb,stroke:#333,stroke-width:1px;
    classDef utility fill:#eef,stroke:#333,stroke-width:1px;
```
