# leocamachocr/spring-boot-base-app architecture

> Architecture diagram of the GitHub repository leocamachocr/spring-boot-base-app, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/leocamachocr/spring-boot-base-app
- Repository: https://github.com/leocamachocr/spring-boot-base-app

## Overview

##### Project Type and Purpose
- Monolithic, server-side Spring Boot application
- Exposes REST API endpoints
- Stores data in an in-memory H2 database (managed via Liquibase changelogs)
- Applies CQRS: separate write (commands) and read (queries) flows
- Implements JWT-based security and CORS configuration

##### Main Architectural Layers and Components
A. External Clients
– REST clients (e.g., Postman, Swagger UI or any frontend)
B. Web/API Layer
– Spring MVC REST Controllers
- LoginUserController
- RegisterUserController
- UserQueriesController
– Exception Handling
- ExceptionManagerController
C. Security Layer
– CorsConfig (CORS rules)
– WebSecurityConfig (HTTP security rules)
– JwtRequestFilter (extracts & validates JWT)
– AuthenticationErrorHandlingEntryPoint
– JwtProvider (token creation & validation)
– UserAuthenticationQuery (loads user for auth context)
– Session & SessionContextHolder (stores auth info in thread context)
D. Application (Business) Layer – CQRS Handlers
– Command Handlers
- RegisterUserHandler → EncodePasswordHandler → UserRepository.save
- LoginUserHandler → JwtProvider → generate token
– Query Handlers
- GetCurrentUserQuery → UserRepository.findById → map to UserResponse
E. Persistence Layer
– JPA Entities & Repositories
- UserEntity
- UserRepository (Spring Data JPA)
– Liquibase changelogs (DB migrations)
– H2 in-memory database
F. Shared/API Types
– Request/Response DTOs (LoginUserRequest, RegisterUserRequest, LoginResponse, UserResponse, ErrorResponse)
G. Test Suite
– Cucumber API tests (features, steps, runners)
– Unit tests for handlers, validators, structure (ArchUnit)

##### Relationships & Data Flows
1. Client → REST Controller
2. Controller → Security Filter Chain (JwtRequestFilter + WebSecurityConfig)
3. Controller → (via dependency injection) → appropriate Command or Query Handler
4a. Command Handler → EncodePasswordHandler (if required) → UserRepository → H2 DB
4b. Query Handler → UserRepository → H2 DB
5. Repository responses → Handler → Controller → HTTP Response
6. Liquibase applies on startup: XML changelog → H2 schema/data

##### Architectural Patterns
- Layered architecture (API, Security, Application, Persistence)
- CQRS: separate command vs query handlers
- Single Responsibility Principle: one handler per use case; one controller per resource
- Dependency Injection via Spring Boot
- Security filter chain for JWT auth

##### Elements
- Clear labels (component names + package paths if needed)

## Diagram (Mermaid)

```mermaid
graph TB
    %% External Clients
    Client(["External Clients"]):::external

    %% Security Layer
    subgraph "Security Layer"
        CorsConfig["CorsConfig"]:::security
        WebSecurityConfig["WebSecurityConfig"]:::security
        JwtRequestFilter["JwtRequestFilter"]:::security
        AuthenticationErrorHandlingEntryPoint["AuthenticationErrorHandlingEntryPoint"]:::security
        JwtProvider["JwtProvider"]:::security
        UserAuthenticationQuery["UserAuthenticationQuery"]:::security
        Session["Session"]:::security
        SessionContextHolder["SessionContextHolder"]:::security
    end

    %% API/Web Layer
    subgraph "API/Web Layer"
        LoginUserController["LoginUserController"]:::api
        RegisterUserController["RegisterUserController"]:::api
        UserQueriesController["UserQueriesController"]:::api
        ExceptionManagerController["ExceptionManagerController"]:::api
    end

    %% Business Layer (CQRS)
    subgraph "Business Layer (CQRS)"
        RegisterUserHandler["RegisterUserHandler"]:::business
        EncodePasswordHandler["EncodePasswordHandler"]:::business
        LoginUserHandler["LoginUserHandler"]:::business
        GetCurrentUserQuery["GetCurrentUserQuery"]:::business
    end

    %% Persistence Layer
    subgraph "Persistence Layer"
        UserRepository["UserRepository"]:::persistence
        UserEntity["UserEntity"]:::persistence
        Liquibase["Liquibase Changelogs"]:::persistence
        H2["H2 In-Memory DB"]:::persistence
    end

    %% Data Flows
    Client -->|requests| CorsConfig
    CorsConfig -->|CORS check| JwtRequestFilter
    JwtRequestFilter -->|auth filter| LoginUserController
    JwtRequestFilter -->|auth filter| RegisterUserController
    JwtRequestFilter -->|auth filter| UserQueriesController

    LoginUserController -->|execute login| LoginUserHandler
    LoginUserHandler -->|generate token| JwtProvider
    JwtProvider -->|token| LoginUserController
    LoginUserController -->|response| Client

    RegisterUserController -->|execute register| RegisterUserHandler
    RegisterUserHandler -->|encode password| EncodePasswordHandler
    EncodePasswordHandler -->|save user| UserRepository
    UserRepository -->|persist| H2
    RegisterUserHandler -->|acknowledge| RegisterUserController
    RegisterUserController -->|response| Client

    UserQueriesController -->|execute query| GetCurrentUserQuery
    GetCurrentUserQuery -->|fetch| UserRepository
    UserRepository -->|read| H2
    GetCurrentUserQuery -->|map to DTO| UserQueriesController
    UserQueriesController -->|response| Client

    %% Exception Handling
    LoginUserController ---|errors to| ExceptionManagerController
    RegisterUserController ---|errors to| ExceptionManagerController
    UserQueriesController ---|errors to| ExceptionManagerController

    %% Startup Process
    Liquibase -->|migrations| H2

    %% Click Events
    click LoginUserController "https://github.com/leocamachocr/spring-boot-base-app/blob/main/src/main/java/dev/leocamacho/demo/api/rests/LoginUserController.java"
    click RegisterUserController "https://github.com/leocamachocr/spring-boot-base-app/blob/main/src/main/java/dev/leocamacho/demo/api/rests/RegisterUserController.java"
    click UserQueriesController "https://github.com/leocamachocr/spring-boot-base-app/blob/main/src/main/java/dev/leocamacho/demo/api/rests/UserQueriesController.java"
    click ExceptionManagerController "https://github.com/leocamachocr/spring-boot-base-app/blob/main/src/main/java/dev/leocamacho/demo/api/exceptions/ExceptionManagerController.java"
    click CorsConfig "https://github.com/leocamachocr/spring-boot-base-app/blob/main/src/main/java/dev/leocamacho/demo/security/CorsConfig.java"
    click WebSecurityConfig "https://github.com/leocamachocr/spring-boot-base-app/blob/main/src/main/java/dev/leocamacho/demo/security/WebSecurityConfig.java"
    click JwtRequestFilter "https://github.com/leocamachocr/spring-boot-base-app/blob/main/src/main/java/dev/leocamacho/demo/security/JwtRequestFilter.java"
    click AuthenticationErrorHandlingEntryPoint "https://github.com/leocamachocr/spring-boot-base-app/blob/main/src/main/java/dev/leocamacho/demo/security/AuthenticationErrorHandlingEntryPoint.java"
    click JwtProvider "https://github.com/leocamachocr/spring-boot-base-app/blob/main/src/main/java/dev/leocamacho/demo/security/JwtProvider.java"
    click UserAuthenticationQuery "https://github.com/leocamachocr/spring-boot-base-app/blob/main/src/main/java/dev/leocamacho/demo/security/UserAuthenticationQuery.java"
    click Session "https://github.com/leocamachocr/spring-boot-base-app/blob/main/src/main/java/dev/leocamacho/demo/session/Session.java"
    click SessionContextHolder "https://github.com/leocamachocr/spring-boot-base-app/blob/main/src/main/java/dev/leocamacho/demo/session/SessionContextHolder.java"
    click RegisterUserHandler "https://github.com/leocamachocr/spring-boot-base-app/blob/main/src/main/java/dev/leocamacho/demo/handlers/commands/RegisterUserHandler.java"
    click EncodePasswordHandler "https://github.com/leocamachocr/spring-boot-base-app/blob/main/src/main/java/dev/leocamacho/demo/handlers/commands/EncodePasswordHandler.java"
    click LoginUserHandler "https://github.com/leocamachocr/spring-boot-base-app/blob/main/src/main/java/dev/leocamacho/demo/handlers/commands/LoginUserHandler.java"
    click RegisterUserHandlerImpl "https://github.com/leocamachocr/spring-boot-base-app/blob/main/src/main/java/dev/leocamacho/demo/handlers/commands/impl/RegisterUserHandlerImpl.java"
    click EncodePasswordHandlerImpl "https://github.com/leocamachocr/spring-boot-base-app/blob/main/src/main/java/dev/leocamacho/demo/handlers/commands/impl/EncodePasswordHandlerImpl.java"
    click LoginUserHandlerImpl "https://github.com/leocamachocr/spring-boot-base-app/blob/main/src/main/java/dev/leocamacho/demo/handlers/commands/impl/LoginUserHandlerImpl.java"
    click GetCurrentUserQuery "https://github.com/leocamachocr/spring-boot-base-app/blob/main/src/main/java/dev/leocamacho/demo/handlers/queries/GetCurrentUserQuery.java"
    click GetCurrentUserQueryImpl "https://github.com/leocamachocr/spring-boot-base-app/blob/main/src/main/java/dev/leocamacho/demo/handlers/queries/impl/GetCurrentUserQueryImpl.java"
    click UserEntity "https://github.com/leocamachocr/spring-boot-base-app/blob/main/src/main/java/dev/leocamacho/demo/jpa/entities/UserEntity.java"
    click UserRepository "https://github.com/leocamachocr/spring-boot-base-app/blob/main/src/main/java/dev/leocamacho/demo/jpa/repositories/UserRepository.java"
    click Liquibase "https://github.com/leocamachocr/spring-boot-base-app/blob/main/src/main/resources/db/changelog/db.changelog-master.xml"

    %% Styles
    classDef external fill:#f2f2f2,stroke:#333,stroke-width:1px;
    classDef api fill:#bbdefb,stroke:#1e88e5,stroke-width:2px,color:#0d47a1;
    classDef security fill:#ffcc80,stroke:#fb8c00,stroke-width:2px,color:#e65100;
    classDef business fill:#c8e6c9,stroke:#43a047,stroke-width:2px,color:#1b5e20;
    classDef persistence fill:#fff9c4,stroke:#fdd835,stroke-width:2px,color:#f57f17;
```
