# yogendra-27/spring-security-jwt architecture

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

- Interactive diagram: https://gitdiagram.com/yogendra-27/spring-security-jwt
- Repository: https://github.com/yogendra-27/spring-security-jwt

## Overview

This repository is a Spring Boot backend centered on JWT-based authentication and authorization.

#### High-level architecture

The app is organized into a few clear layers:

1. **Bootstrap layer**
   - `SecurityappApplication` is the Spring Boot entry point.

2. **HTTP/API layer**
   - Controllers expose the REST endpoints:
     - `HelloController`
     - `StudentController`
     - `UserController`

3. **Security layer**
   - `SecurityConfig` defines the Spring Security setup.
   - `JwtFilter` intercepts requests to extract and validate JWTs before the request reaches controllers.
   - `JWTService` is the token utility/service responsible for generating and validating JWTs.

4. **User/authentication layer**
   - `MyUserDeatilsService` implements Spring Security’s `UserDetailsService` contract.
   - `UserPrincipal` adapts the application’s user model into Spring Security’s `UserDetails`.
   - `UserService` appears to contain user-related business logic, likely including registration and login support.

5. **Persistence layer**
   - `UserRepository` provides database access for user records.
   - `Users` is the persistent domain/entity model backing authentication data.

6. **Configuration and runtime**
   - `application.yml` holds runtime configuration, likely including server, security, and datasource/JWT settings.

#### Main request flow

##### 1. Application startup
Spring Boot starts from `SecurityappApplication`, loads the security configuration, and wires the controller, service, and repository beans.

##### 2. Authentication flow
A client sends credentials to an authentication-related endpoint, most likely in `UserController`.

- `UserController` delegates to `UserService`.
- `UserService` likely validates the credentials using Spring Security components.
- `MyUserDeatilsService` loads the user from `UserRepository`.
- The returned `Users` record is wrapped by `UserPrincipal` so Spring Security can work with it.
- `JWTService` creates a JWT after successful authentication.
- The token is returned to the client.

##### 3. Authorized request flow
For later requests, the client includes the JWT in the request header.

- `JwtFilter` runs before controller execution.
- It extracts the token, validates it via `JWTService`, and establishes the authenticated security context.
- If the token is valid, the request continues to the controller.
- If invalid or missing on a protected route, Spring Security denies access.

#### Important boundaries

##### Public vs protected API boundary
This project is built around the distinction between:
- endpoints that are open, likely for login or registration
- endpoints that require a valid JWT

`SecurityConfig` is the boundary that decides which routes are public and which require authentication.

##### Application user model vs Spring Security model
There is a clear adapter boundary between:
- `Users` as the application/database representation
- `UserPrincipal` as the Spring Security representation

That separation is important for diagramming because it shows that the database entity is not used directly by the security framework.

##### Token logic vs request filtering
JWT responsibilities are split:
- `JWTService` handles token creation and validation logic
- `JwtFilter` handles request-time extraction and authentication setup

That separation is central to the architecture.

#### Role of the controllers

- `UserController` is the security-related entry point and likely owns auth flows such as signup/login.
- `HelloController` is probably a basic test or public/protected sample endpoint.
- `StudentController` suggests an additional domain endpoint used to demonstrate authorization behavior, likely with restricted access.

#### Data model and persistence

The only explicit persistent domain model in the tree is `Users`, accessed through `UserRepository`. That means user authentication state is backed by a datastore through Spring Data repository access.

`Student` appears under the controller package rather than a model package, so it is likely a simple request/response DTO or sample payload rather than a persisted entity.

#### Infrastructure and tooling

- The project uses **Maven** (`pom.xml`, `mvnw`, `.mvn/`).
- It is a **Spring Boot** application with **Spring Security** and **JWT**.
- The test tree contains only a basic application test, so the repo appears to be a small example or starter implementation rather than a large multi-module system.

#### What an architecture diagram should show

A good diagram for this repo should include:

- Client → REST controllers
- Security filter chain in front of all requests
- `JwtFilter` calling `JWTService`
- `UserController` and `UserService` handling auth actions
- `MyUserDeatilsService` loading users from `UserRepository`
- `UserPrincipal` bridging `Users` into Spring Security
- `SecurityConfig` controlling which endpoints are open or protected
- `application.yml` as the configuration source
- `SecurityappApplication` as the bootstrap entry point

In short, this is a layered Spring Security JWT application where authentication is user-store-backed, JWTs are the stateless session mechanism, and the security filter chain mediates access to the REST controllers.

Main entry points: [`src/main/java/com/security/securityapp/controller/config/SecurityConfig.java`](https://github.com/yogendra-27/spring-security-jwt/blob/HEAD/src/main/java/com/security/securityapp/controller/config/SecurityConfig.java) (Security config), [`src/main/java/com/security/securityapp/SecurityappApplication.java`](https://github.com/yogendra-27/spring-security-jwt/blob/HEAD/src/main/java/com/security/securityapp/SecurityappApplication.java) (Security app), [`src/main/java/com/security/securityapp/controller/config/JwtFilter.java`](https://github.com/yogendra-27/spring-security-jwt/blob/HEAD/src/main/java/com/security/securityapp/controller/config/JwtFilter.java) (JWT filter), [`src/main/java/com/security/securityapp/service/UserService.java`](https://github.com/yogendra-27/spring-security-jwt/blob/HEAD/src/main/java/com/security/securityapp/service/UserService.java) (User service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph "Bootstrap"
  app(("Security app<br/>Spring Boot app"))
end

subgraph "HTTP API"
  hello_controller["Hello<br/>REST controller"]
  student_controller["Student<br/>REST controller"]
  user_controller["User<br/>REST controller"]
  student_dto["Student<br/>payload model<br/>[Student.java]"]
end

subgraph "Security"
  security_config["Security config"]
  jwt_filter["JWT filter<br/>request filter<br/>[JwtFilter.java]"]
  jwt_service["JWT service<br/>token service<br/>[JWTService.java]"]
end

subgraph "Auth domain"
  user_service["User service<br/>business service<br/>[UserService.java]"]
  user_details_service["User details<br/>UserDetailsService"]
  user_principal["User principal<br/>security adapter<br/>[UserPrincipal.java]"]
end

subgraph "Persistence"
  users_entity[("Users<br/>entity<br/>[Users.java]")]
  user_repository["User repo"]
end

subgraph "Runtime config"
  application_yml["App config<br/>YAML config<br/>[application.yml]"]
end

app -->|"loads"| security_config
app -->|"wires"| hello_controller
app -->|"wires"| student_controller
app -->|"wires"| user_controller
security_config -->|"adds"| jwt_filter
security_config -->|"opens"| user_controller
security_config -->|"guards"| hello_controller
security_config -->|"guards"| student_controller
jwt_filter -->|"validates"| jwt_service
jwt_filter -->|"participates"| security_config
user_controller -->|"delegates"| user_service
user_service -->|"loads"| user_details_service
user_service -->|"issues token"| jwt_service
user_details_service -->|"queries"| user_repository
user_details_service -->|"wraps"| user_principal
user_principal -->|"adapts"| users_entity
user_repository -->|"stores"| users_entity
security_config -->|"reads"| application_yml
jwt_service -->|"reads"| application_yml
user_repository -->|"uses"| application_yml
student_controller -->|"uses"| student_dto

click app "https://github.com/yogendra-27/spring-security-jwt/blob/master/src/main/java/com/security/securityapp/SecurityappApplication.java"
click hello_controller "https://github.com/yogendra-27/spring-security-jwt/blob/master/src/main/java/com/security/securityapp/controller/HelloController.java"
click student_controller "https://github.com/yogendra-27/spring-security-jwt/blob/master/src/main/java/com/security/securityapp/controller/StudentController.java"
click user_controller "https://github.com/yogendra-27/spring-security-jwt/blob/master/src/main/java/com/security/securityapp/controller/UserController.java"
click security_config "https://github.com/yogendra-27/spring-security-jwt/blob/master/src/main/java/com/security/securityapp/controller/config/SecurityConfig.java"
click jwt_filter "https://github.com/yogendra-27/spring-security-jwt/blob/master/src/main/java/com/security/securityapp/controller/config/JwtFilter.java"
click jwt_service "https://github.com/yogendra-27/spring-security-jwt/blob/master/src/main/java/com/security/securityapp/service/JWTService.java"
click user_service "https://github.com/yogendra-27/spring-security-jwt/blob/master/src/main/java/com/security/securityapp/service/UserService.java"
click user_details_service "https://github.com/yogendra-27/spring-security-jwt/blob/master/src/main/java/com/security/securityapp/service/MyUserDeatilsService.java"
click user_principal "https://github.com/yogendra-27/spring-security-jwt/blob/master/src/main/java/com/security/securityapp/model/UserPrincipal.java"
click users_entity "https://github.com/yogendra-27/spring-security-jwt/blob/master/src/main/java/com/security/securityapp/model/Users.java"
click user_repository "https://github.com/yogendra-27/spring-security-jwt/blob/master/src/main/java/com/security/securityapp/repository/UserRepository.java"
click student_dto "https://github.com/yogendra-27/spring-security-jwt/blob/master/src/main/java/com/security/securityapp/controller/Student.java"
click application_yml "https://github.com/yogendra-27/spring-security-jwt/blob/master/src/main/resources/application.yml"

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 app toneBlue
class hello_controller,student_controller,user_controller,student_dto toneAmber
class security_config,jwt_filter,jwt_service toneMint
class user_service,user_details_service,user_principal toneRose
class users_entity,user_repository toneIndigo
class application_yml toneTeal
```

## Components

### Bootstrap

Application entry point and startup wiring

- [Security app](https://github.com/yogendra-27/spring-security-jwt/blob/HEAD/src/main/java/com/security/securityapp/SecurityappApplication.java): Spring Boot app · Application entry point · `src/main/java/com/security/securityapp/SecurityappApplication.java`

### HTTP API

REST controllers exposed to clients

- [Hello](https://github.com/yogendra-27/spring-security-jwt/blob/HEAD/src/main/java/com/security/securityapp/controller/HelloController.java): REST controller · Simple endpoint controller · `src/main/java/com/security/securityapp/controller/HelloController.java`
- [Student](https://github.com/yogendra-27/spring-security-jwt/blob/HEAD/src/main/java/com/security/securityapp/controller/StudentController.java): REST controller · Sample or protected endpoint controller · `src/main/java/com/security/securityapp/controller/StudentController.java`
- [User](https://github.com/yogendra-27/spring-security-jwt/blob/HEAD/src/main/java/com/security/securityapp/controller/UserController.java): REST controller · Auth-related API entry point · `src/main/java/com/security/securityapp/controller/UserController.java`
- [Student](https://github.com/yogendra-27/spring-security-jwt/blob/HEAD/src/main/java/com/security/securityapp/controller/Student.java): payload model · Controller-side student payload or DTO · `src/main/java/com/security/securityapp/controller/Student.java`

### Security

Spring Security configuration and JWT request handling

- [Security config](https://github.com/yogendra-27/spring-security-jwt/blob/HEAD/src/main/java/com/security/securityapp/controller/config/SecurityConfig.java): Spring Security config · Defines protected and public routes · `src/main/java/com/security/securityapp/controller/config/SecurityConfig.java`
- [JWT filter](https://github.com/yogendra-27/spring-security-jwt/blob/HEAD/src/main/java/com/security/securityapp/controller/config/JwtFilter.java): request filter · Extracts and validates bearer tokens · `src/main/java/com/security/securityapp/controller/config/JwtFilter.java`
- [JWT service](https://github.com/yogendra-27/spring-security-jwt/blob/HEAD/src/main/java/com/security/securityapp/service/JWTService.java): token service · Creates and validates JWTs · `src/main/java/com/security/securityapp/service/JWTService.java`

### Auth domain

User details, principals, and auth business logic

- [User service](https://github.com/yogendra-27/spring-security-jwt/blob/HEAD/src/main/java/com/security/securityapp/service/UserService.java): business service · Coordinates auth and user logic · `src/main/java/com/security/securityapp/service/UserService.java`
- [User details](https://github.com/yogendra-27/spring-security-jwt/blob/HEAD/src/main/java/com/security/securityapp/service/MyUserDeatilsService.java): UserDetailsService · Loads users for Spring Security · `src/main/java/com/security/securityapp/service/MyUserDeatilsService.java`
- [User principal](https://github.com/yogendra-27/spring-security-jwt/blob/HEAD/src/main/java/com/security/securityapp/model/UserPrincipal.java): security adapter · Adapts Users to Spring Security principal · `src/main/java/com/security/securityapp/model/UserPrincipal.java`

### Persistence

User entity and repository access

- [Users](https://github.com/yogendra-27/spring-security-jwt/blob/HEAD/src/main/java/com/security/securityapp/model/Users.java): entity · Persistent user account model · `src/main/java/com/security/securityapp/model/Users.java`
- [User repo](https://github.com/yogendra-27/spring-security-jwt/blob/HEAD/src/main/java/com/security/securityapp/repository/UserRepository.java): repository · Database access for users · `src/main/java/com/security/securityapp/repository/UserRepository.java`

### Runtime config

Application runtime settings

- [App config](https://github.com/yogendra-27/spring-security-jwt/blob/HEAD/src/main/resources/application.yml): YAML config · Runtime configuration source · `src/main/resources/application.yml`

## Connections

- Security app → Security config: loads · Bootstraps the security setup
- Security app → Hello: wires · Registers REST controllers
- Security app → Student: wires · Registers REST controllers
- Security app → User: wires · Registers REST controllers
- Security config → JWT filter: adds · Places JWT filter in the security chain
- Security config → User: opens · Configures auth-related routes
- Security config → Hello: guards · Applies access rules to endpoints
- Security config → Student: guards · Applies access rules to endpoints
- JWT filter → JWT service: validates · Delegates token parsing and verification
- JWT filter → Security config: participates · Runs as part of the configured filter chain
- User → User service: delegates · Hands off login or registration logic
- User service → User details: loads · Looks up users through security-aware lookup
- User service → JWT service: issues token · Creates JWT after successful authentication
- User details → User repo: queries · Loads user records from persistence
- User details → User principal: wraps · Converts entity into security principal
- User principal → Users: adapts · Represents the application user as Spring Security user
- User repo → Users: stores · Persists user account records
- Security config → App config: reads · Uses runtime properties and secrets
- JWT service → App config: reads · Uses JWT-related configuration
- User repo → App config: uses · Relies on datasource/runtime settings
- Student → Student: uses · Consumes or returns student payloads
