# vimal1464/spring-boot-spring-security-jwt-authentication architecture

> Architecture diagram of the GitHub repository vimal1464/spring-boot-spring-security-jwt-authentication, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/vimal1464/spring-boot-spring-security-jwt-authentication
- Repository: https://github.com/vimal1464/spring-boot-spring-security-jwt-authentication

## Overview

1. **What this repo is**
   - This is a **Spring Boot 3.2 / Java 17 REST API** focused on **JWT-based authentication** rather than a full ToDo domain.
   - The core runtime stack is **Spring Web + Spring Security + Spring Data JPA + MySQL**, with JWT support via `jjwt`.

2. **Top-level architecture**
   - The code is organized into clear layers:
     - **HTTP/API layer**: controllers
     - **Security layer**: JWT filter, entry point, security config
     - **Application/service layer**: user service interface + implementation
     - **Persistence layer**: JPA entity + Spring Data repository
     - **DTO/error layer**: request/response models and auth exceptions

3. **Request entry point and app bootstrap**
   - `ToDoAppApplication.java` is the Spring Boot bootstrap class.
   - `application.properties` provides runtime configuration, especially for the database and likely JWT/security settings.
   - `pom.xml` defines the Maven build and pulls in the Spring Boot, Security, JPA, MySQL, and JWT dependencies.

4. **Security boundary**
   - `SecurityConfig.java` and `AuthConfig.java` are the central security setup classes.
   - `JwtAuthenticationFilter.java` sits in the request pipeline and validates bearer tokens before protected endpoints are reached.
   - `JWTAuthenticationEntryPoint.java` handles unauthenticated access attempts and returns the security failure response.
   - `JwtHelper.java` is the token utility component for generating/parsing/validating JWTs.

5. **Authentication flow**
   - `AuthController.java` is the login/auth endpoint.
   - It consumes `JwtRequest` and returns `JwtResponse`.
   - The usual flow is: client submits credentials → authentication succeeds → server generates JWT → client reuses JWT on later requests.
   - This is the main boundary between **anonymous access** and **authenticated access**.

6. **User management flow**
   - `UserController.java` exposes user-related endpoints, likely for registration and/or user retrieval.
   - `UserService.java` defines the business contract, and `service/imp/UserImp.java` contains the implementation.
   - Validation and business rules such as duplicate-user handling appear to live here, backed by `UserAlreadyExistsException`.

7. **Persistence layer**
   - `UserRepo.java` is the Spring Data JPA repository.
   - `UserEnitiy.java` is the persisted user model mapped to MySQL.
   - `TodoEnitiy.java` is present under `config`, but based on the repository structure the main persistence concern is still user/auth data; the file name looks like a typo or misplacement.
   - The database is externalized through MySQL, so the app depends on an external relational store rather than embedded storage.

8. **DTO boundary**
   - `dto/req` and `dto/resp` separate API contracts from internal entities.
   - `JwtRequest` / `JwtResponse` carry authentication payloads.
   - `UserRequestDto` / `UserResponseDto` keep user-facing API models distinct from `UserEnitiy`.
   - This indicates the API is designed to avoid exposing persistence entities directly.

9. **Error handling**
   - `AuthError.java` and `UserAlreadyExistsException.java` represent domain/security failure cases.
   - These likely map to HTTP error responses, especially around authentication and duplicate registration.
   - Combined with the security entry point, the repo has a split between **authorization failures** and **business-rule failures**.

10. **Main data flow for a protected request**
   - Client sends a request with a JWT.
   - `JwtAuthenticationFilter` validates the token using `JwtHelper`.
   - If valid, the request proceeds to a controller and then the service layer.
   - If invalid or missing, `JWTAuthenticationEntryPoint` short-circuits the request with an unauthorized response.

11. **Main data flow for user creation/auth**
   - Client calls an auth/user endpoint with a request DTO.
   - Controller delegates to `UserImp` or auth logic.
   - Service uses `UserRepo` to read/write `UserEnitiy` in MySQL.
   - On success, auth endpoints issue a signed JWT back to the client.

12. **Tooling and verification**
   - Maven wrapper files are included, so the project is intended to be built consistently across machines.
   - `src/test/java/.../ToDoAppApplicationTests.java` suggests at least a baseline Spring Boot context test exists.
   - There is no evidence of a frontend, message queue, or external microservice integration; the architecture is a single Spring Boot service backed by MySQL.

Main entry points: [`src/main/java/com/vimal/code/ToDo/service/imp/UserImp.java`](https://github.com/vimal1464/spring-boot-spring-security-jwt-authentication/blob/master/src/main/java/com/vimal/code/ToDo/service/imp/UserImp.java) (User service impl), [`src/main/java/com/vimal/code/ToDo/controllers/AuthController.java`](https://github.com/vimal1464/spring-boot-spring-security-jwt-authentication/blob/master/src/main/java/com/vimal/code/ToDo/controllers/AuthController.java) (Auth controller), [`src/main/java/com/vimal/code/ToDo/config/SecurityConfig.java`](https://github.com/vimal1464/spring-boot-spring-security-jwt-authentication/blob/master/src/main/java/com/vimal/code/ToDo/config/SecurityConfig.java) (Security config), [`src/main/java/com/vimal/code/ToDo/controllers/UserController.java`](https://github.com/vimal1464/spring-boot-spring-security-jwt-authentication/blob/master/src/main/java/com/vimal/code/ToDo/controllers/UserController.java) (User controller)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_build["Build & runtime"]
  node_pom["Maven build<br/>build config<br/>[pom.xml]"]
  node_app(("Boot app<br/>spring boot entry"))
  node_props["App config<br/>runtime config"]
end

subgraph group_api["HTTP API"]
  node_authctl["Auth controller<br/>rest controller"]
  node_userctl["User controller<br/>rest controller"]
  node_homectl["Home controller<br/>rest controller"]
end

subgraph group_security["Security"]
  node_secconfig["Security config"]
  node_authconfig["Auth config<br/>security wiring<br/>[AuthConfig.java]"]
  node_jwtfilter{{"JWT filter<br/>security filter"}}
  node_entrypoint{{"Auth entrypoint<br/>security handler"}}
  node_jwthelper{{"JWT helper<br/>token utility<br/>[JwtHelper.java]"}}
end

subgraph group_service["Application service"]
  node_usersvc["User service<br/>service interface<br/>[UserService.java]"]
  node_userimp["User service impl<br/>[UserImp.java]"]
end

subgraph group_persistence["Persistence"]
  node_userrepo[("User repo<br/>jpa repository<br/>[UserRepo.java]")]
  node_userentity[("User entity<br/>jpa entity<br/>[UserEnitiy.java]")]
  node_todoentity[("Todo entity<br/>entity config<br/>[TodoEnitiy.java]")]
end

subgraph group_contracts["DTOs & errors"]
  node_jwtreq["JWT request<br/>request dto<br/>[JwtRequest.java]"]
  node_jwtresp["JWT response<br/>response dto<br/>[JwtResponse.java]"]
  node_userreq["User request<br/>request dto"]
  node_userresp["User response<br/>response dto"]
  node_autherror{{"Auth error<br/>security error<br/>[AuthError.java]"}}
  node_dupuser{{"Dup user<br/>domain exception"}}
end

node_pom -->|"builds"| node_app
node_app -->|"loads"| node_props
node_app -->|"wires"| node_secconfig
node_secconfig -->|"uses"| node_authconfig
node_secconfig -->|"installs"| node_jwtfilter
node_secconfig -->|"delegates"| node_entrypoint
node_authconfig -->|"uses"| node_jwthelper
node_authctl -->|"consumes"| node_jwtreq
node_authctl -->|"returns"| node_jwtresp
node_authctl -->|"authenticates via"| node_usersvc
node_userctl -->|"consumes"| node_userreq
node_userctl -->|"returns"| node_userresp
node_userctl -->|"delegates"| node_usersvc
node_usersvc -->|"implemented by"| node_userimp
node_userimp -->|"persists via"| node_userrepo
node_userrepo -->|"maps"| node_userentity
node_userimp -->|"throws"| node_dupuser
node_jwtfilter -->|"validates with"| node_jwthelper
node_jwtfilter -->|"fails to"| node_entrypoint
node_userimp -->|"maps to"| node_userresp
node_userimp -->|"accepts"| node_userreq
node_authctl -->|"emits"| node_autherror
node_todoentity -.->|"related"| node_userentity

click node_pom "https://github.com/vimal1464/spring-boot-spring-security-jwt-authentication/blob/master/pom.xml"
click node_app "https://github.com/vimal1464/spring-boot-spring-security-jwt-authentication/blob/master/src/main/java/com/vimal/code/ToDo/ToDoAppApplication.java"
click node_props "https://github.com/vimal1464/spring-boot-spring-security-jwt-authentication/blob/master/src/main/resources/application.properties"
click node_authctl "https://github.com/vimal1464/spring-boot-spring-security-jwt-authentication/blob/master/src/main/java/com/vimal/code/ToDo/controllers/AuthController.java"
click node_userctl "https://github.com/vimal1464/spring-boot-spring-security-jwt-authentication/blob/master/src/main/java/com/vimal/code/ToDo/controllers/UserController.java"
click node_homectl "https://github.com/vimal1464/spring-boot-spring-security-jwt-authentication/blob/master/src/main/java/com/vimal/code/ToDo/controllers/HomeController.java"
click node_secconfig "https://github.com/vimal1464/spring-boot-spring-security-jwt-authentication/blob/master/src/main/java/com/vimal/code/ToDo/config/SecurityConfig.java"
click node_authconfig "https://github.com/vimal1464/spring-boot-spring-security-jwt-authentication/blob/master/src/main/java/com/vimal/code/ToDo/config/AuthConfig.java"
click node_jwtfilter "https://github.com/vimal1464/spring-boot-spring-security-jwt-authentication/blob/master/src/main/java/com/vimal/code/ToDo/Auth/JwtAuthenticationFilter.java"
click node_entrypoint "https://github.com/vimal1464/spring-boot-spring-security-jwt-authentication/blob/master/src/main/java/com/vimal/code/ToDo/Auth/JWTAuthenticationEntryPoint.java"
click node_jwthelper "https://github.com/vimal1464/spring-boot-spring-security-jwt-authentication/blob/master/src/main/java/com/vimal/code/ToDo/Auth/JwtHelper.java"
click node_usersvc "https://github.com/vimal1464/spring-boot-spring-security-jwt-authentication/blob/master/src/main/java/com/vimal/code/ToDo/service/UserService.java"
click node_userimp "https://github.com/vimal1464/spring-boot-spring-security-jwt-authentication/blob/master/src/main/java/com/vimal/code/ToDo/service/imp/UserImp.java"
click node_userrepo "https://github.com/vimal1464/spring-boot-spring-security-jwt-authentication/blob/master/src/main/java/com/vimal/code/ToDo/repo/UserRepo.java"
click node_userentity "https://github.com/vimal1464/spring-boot-spring-security-jwt-authentication/blob/master/src/main/java/com/vimal/code/ToDo/enitiy/UserEnitiy.java"
click node_todoentity "https://github.com/vimal1464/spring-boot-spring-security-jwt-authentication/blob/master/src/main/java/com/vimal/code/ToDo/config/TodoEnitiy.java"
click node_jwtreq "https://github.com/vimal1464/spring-boot-spring-security-jwt-authentication/blob/master/src/main/java/com/vimal/code/ToDo/dto/req/JwtRequest.java"
click node_jwtresp "https://github.com/vimal1464/spring-boot-spring-security-jwt-authentication/blob/master/src/main/java/com/vimal/code/ToDo/dto/resp/JwtResponse.java"
click node_userreq "https://github.com/vimal1464/spring-boot-spring-security-jwt-authentication/blob/master/src/main/java/com/vimal/code/ToDo/dto/req/UserRequestDto.java"
click node_userresp "https://github.com/vimal1464/spring-boot-spring-security-jwt-authentication/blob/master/src/main/java/com/vimal/code/ToDo/dto/resp/UserResponseDto.java"
click node_autherror "https://github.com/vimal1464/spring-boot-spring-security-jwt-authentication/blob/master/src/main/java/com/vimal/code/ToDo/exp/AuthError.java"
click node_dupuser "https://github.com/vimal1464/spring-boot-spring-security-jwt-authentication/blob/master/src/main/java/com/vimal/code/ToDo/exp/UserAlreadyExistsException.java"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_pom,node_app,node_props toneBlue
class node_authctl,node_userctl,node_homectl toneAmber
class node_secconfig,node_authconfig,node_jwtfilter,node_entrypoint,node_jwthelper toneMint
class node_usersvc,node_userimp toneRose
class node_userrepo,node_userentity,node_todoentity toneIndigo
class node_jwtreq,node_jwtresp,node_userreq,node_userresp,node_autherror,node_dupuser toneTeal
```

## Components

### Build & runtime

Project bootstrap and runtime configuration

- [Maven build](https://github.com/vimal1464/spring-boot-spring-security-jwt-authentication/blob/master/pom.xml): build config · Spring Boot, security, JPA, MySQL, and JWT dependencies · `pom.xml`
- [Boot app](https://github.com/vimal1464/spring-boot-spring-security-jwt-authentication/blob/master/src/main/java/com/vimal/code/ToDo/ToDoAppApplication.java): spring boot entry · Application startup and component scan root · `src/main/java/com/vimal/code/ToDo/ToDoAppApplication.java`
- [App config](https://github.com/vimal1464/spring-boot-spring-security-jwt-authentication/blob/master/src/main/resources/application.properties): runtime config · Externalized application settings for database and security · `src/main/resources/application.properties`

### HTTP API

Controllers and request entry points

- [Auth controller](https://github.com/vimal1464/spring-boot-spring-security-jwt-authentication/blob/master/src/main/java/com/vimal/code/ToDo/controllers/AuthController.java): rest controller · Authentication endpoint for login and token issuance · `src/main/java/com/vimal/code/ToDo/controllers/AuthController.java`
- [User controller](https://github.com/vimal1464/spring-boot-spring-security-jwt-authentication/blob/master/src/main/java/com/vimal/code/ToDo/controllers/UserController.java): rest controller · User-facing endpoints for registration and/or retrieval · `src/main/java/com/vimal/code/ToDo/controllers/UserController.java`
- [Home controller](https://github.com/vimal1464/spring-boot-spring-security-jwt-authentication/blob/master/src/main/java/com/vimal/code/ToDo/controllers/HomeController.java): rest controller · Simple non-auth or landing endpoint · `src/main/java/com/vimal/code/ToDo/controllers/HomeController.java`

### Security

JWT authentication and Spring Security boundary

- [Security config](https://github.com/vimal1464/spring-boot-spring-security-jwt-authentication/blob/master/src/main/java/com/vimal/code/ToDo/config/SecurityConfig.java): security config · Main Spring Security policy and filter-chain setup · `src/main/java/com/vimal/code/ToDo/config/SecurityConfig.java`
- [Auth config](https://github.com/vimal1464/spring-boot-spring-security-jwt-authentication/blob/master/src/main/java/com/vimal/code/ToDo/config/AuthConfig.java): security wiring · Authentication-related wiring and security beans · `src/main/java/com/vimal/code/ToDo/config/AuthConfig.java`
- [JWT filter](https://github.com/vimal1464/spring-boot-spring-security-jwt-authentication/blob/master/src/main/java/com/vimal/code/ToDo/Auth/JwtAuthenticationFilter.java): security filter · Validates bearer tokens on incoming requests · `src/main/java/com/vimal/code/ToDo/Auth/JwtAuthenticationFilter.java`
- [Auth entrypoint](https://github.com/vimal1464/spring-boot-spring-security-jwt-authentication/blob/master/src/main/java/com/vimal/code/ToDo/Auth/JWTAuthenticationEntryPoint.java): security handler · Returns unauthorized responses for missing or invalid authentication · `src/main/java/com/vimal/code/ToDo/Auth/JWTAuthenticationEntryPoint.java`
- [JWT helper](https://github.com/vimal1464/spring-boot-spring-security-jwt-authentication/blob/master/src/main/java/com/vimal/code/ToDo/Auth/JwtHelper.java): token utility · Creates, parses, and validates JWTs · `src/main/java/com/vimal/code/ToDo/Auth/JwtHelper.java`

### Application service

Business logic and orchestration

- [User service](https://github.com/vimal1464/spring-boot-spring-security-jwt-authentication/blob/master/src/main/java/com/vimal/code/ToDo/service/UserService.java): service interface · Business contract for user and auth-related operations · `src/main/java/com/vimal/code/ToDo/service/UserService.java`
- [User service impl](https://github.com/vimal1464/spring-boot-spring-security-jwt-authentication/blob/master/src/main/java/com/vimal/code/ToDo/service/imp/UserImp.java): service impl · Implements user workflows and business rules · `src/main/java/com/vimal/code/ToDo/service/imp/UserImp.java`

### Persistence

JPA entities and repository access

- [User repo](https://github.com/vimal1464/spring-boot-spring-security-jwt-authentication/blob/master/src/main/java/com/vimal/code/ToDo/repo/UserRepo.java): jpa repository · Spring Data access to persisted users · `src/main/java/com/vimal/code/ToDo/repo/UserRepo.java`
- [User entity](https://github.com/vimal1464/spring-boot-spring-security-jwt-authentication/blob/master/src/main/java/com/vimal/code/ToDo/enitiy/UserEnitiy.java): jpa entity · Persisted user model mapped to MySQL · `src/main/java/com/vimal/code/ToDo/enitiy/UserEnitiy.java`
- [Todo entity](https://github.com/vimal1464/spring-boot-spring-security-jwt-authentication/blob/master/src/main/java/com/vimal/code/ToDo/config/TodoEnitiy.java): entity config · Additional mapped entity present in config package · `src/main/java/com/vimal/code/ToDo/config/TodoEnitiy.java`

### DTOs & errors

API contracts and failure types

- [JWT request](https://github.com/vimal1464/spring-boot-spring-security-jwt-authentication/blob/master/src/main/java/com/vimal/code/ToDo/dto/req/JwtRequest.java): request dto · Credentials payload for authentication · `src/main/java/com/vimal/code/ToDo/dto/req/JwtRequest.java`
- [JWT response](https://github.com/vimal1464/spring-boot-spring-security-jwt-authentication/blob/master/src/main/java/com/vimal/code/ToDo/dto/resp/JwtResponse.java): response dto · Token and auth response payload · `src/main/java/com/vimal/code/ToDo/dto/resp/JwtResponse.java`
- [User request](https://github.com/vimal1464/spring-boot-spring-security-jwt-authentication/blob/master/src/main/java/com/vimal/code/ToDo/dto/req/UserRequestDto.java): request dto · User registration or update payload · `src/main/java/com/vimal/code/ToDo/dto/req/UserRequestDto.java`
- [User response](https://github.com/vimal1464/spring-boot-spring-security-jwt-authentication/blob/master/src/main/java/com/vimal/code/ToDo/dto/resp/UserResponseDto.java): response dto · Public user-facing response model · `src/main/java/com/vimal/code/ToDo/dto/resp/UserResponseDto.java`
- [Auth error](https://github.com/vimal1464/spring-boot-spring-security-jwt-authentication/blob/master/src/main/java/com/vimal/code/ToDo/exp/AuthError.java): security error · Authentication and authorization failure model · `src/main/java/com/vimal/code/ToDo/exp/AuthError.java`
- [Dup user](https://github.com/vimal1464/spring-boot-spring-security-jwt-authentication/blob/master/src/main/java/com/vimal/code/ToDo/exp/UserAlreadyExistsException.java): domain exception · Raised when a user already exists · `src/main/java/com/vimal/code/ToDo/exp/UserAlreadyExistsException.java`

## Connections

- Maven build → Boot app: builds · Maven builds and packages the Spring Boot application
- Boot app → App config: loads · Application startup consumes externalized configuration
- Boot app → Security config: wires · Bootstraps security configuration and application beans
- Security config → Auth config: uses · Security setup relies on authentication wiring
- Security config → JWT filter: installs · Adds JWT validation into the request pipeline
- Security config → Auth entrypoint: delegates · Routes unauthenticated failures to the entry point
- Auth config → JWT helper: uses · Authentication flow depends on JWT utilities
- Auth controller → JWT request: consumes · Login requests are mapped from JWT request DTOs
- Auth controller → JWT response: returns · Successful authentication returns JWT response DTOs
- Auth controller → User service: authenticates via · Controller delegates credential checks and token issuance to service logic
- User controller → User request: consumes · User APIs accept user request DTOs
- User controller → User response: returns · User APIs expose response DTOs instead of entities
- User controller → User service: delegates · Controller hands off user operations to the service layer
- User service → User service impl: implemented by · Service contract is fulfilled by the concrete service implementation
- User service impl → User repo: persists via · Business logic reads and writes users through the repository
- User repo → User entity: maps · Repository manages persisted user entities
- User service impl → Dup user: throws · Duplicate registration is surfaced as a domain exception
- JWT filter → JWT helper: validates with · Filter uses helper to inspect and verify bearer tokens
- JWT filter → Auth entrypoint: fails to · Invalid or missing tokens are short-circuited as unauthorized
- User service impl → User response: maps to · Service converts persistence state into API responses
- User service impl → User request: accepts · Service consumes user request data from controllers
- Auth controller → Auth error: emits · Authentication failures are represented through auth error handling
- Todo entity → User entity: related · Additional entity exists alongside the main user persistence model
