# gowtham-m-2005/spring-authify architecture

> Architecture diagram of the GitHub repository gowtham-m-2005/spring-authify, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/gowtham-m-2005/spring-authify
- Repository: https://github.com/gowtham-m-2005/spring-authify

## Overview

1. **System shape**
   - Authify is a **Spring Boot 4 backend** that exposes a **versioned REST API** under `/api/v1.0`.
   - It is a **stateless authentication service**: clients log in, receive a JWT, and then use that token to call protected endpoints.

2. **Application bootstrap and configuration**
   - `AuthifyApplication` is the entry point.
   - `application.yml` wires the main infrastructure: **PostgreSQL**, **Spring Mail/SMTP**, **JWT secret**, and the servlet context path.
   - The repository is built with **Maven** and targets **Java 21**.

3. **Security boundary**
   - `SecurityConfig` is the central gatekeeper for request authorization.
   - `JwtRequestFilter` sits in the Spring Security filter chain and validates incoming JWTs before controller execution.
   - `CustomAuthenticationEntryPoint` handles unauthenticated/unauthorized access paths.
   - The README indicates the token is handled securely, including **HTTP-only cookies**.

4. **Authentication API**
   - `AuthController` is the main API surface for:
     - login
     - authentication status checks
     - sending password-reset OTPs
     - resetting passwords
   - Request/response payloads are isolated in the `io` package, mainly through `AuthRequest`, `AuthResponse`, and `ResetPasswordRequest`.

5. **User identity and token generation**
   - `AppUserDetailsService` bridges the persistence model into Spring Security’s user lookup mechanism.
   - `JwtUtil` is responsible for creating and validating JWTs.
   - These two classes form the core of the “authenticate user → issue token → validate token later” flow.

6. **Profile management subsystem**
   - `ProfileController` exposes protected profile operations.
   - `ProfileService` and `ProfileServiceImpl` contain the business logic for reading and updating profile data.
   - `ProfileRequest` and `ProfileResponse` keep API contracts separate from internal persistence models.

7. **Persistence layer**
   - `UserEntity` is the JPA-backed domain object stored in **PostgreSQL**.
   - `UserDao` is the data-access boundary for user records.
   - The architecture follows a standard controller → service → DAO → database flow.

8. **Email subsystem**
   - `EmailService` handles outbound email delivery through **SMTP**.
   - The `templates` folder contains the email bodies for:
     - verification
     - welcome
     - password reset
   - This is a separate outbound integration boundary from the REST API and database layers.

9. **Password reset flow**
   - The readme describes an **OTP-based recovery flow**.
   - The typical path is: request OTP → email sent → user submits OTP plus new password → backend verifies and updates credentials.
   - This flow crosses the auth controller, email service, and user persistence layer.

10. **Package-level separation**
   - `config` = security and framework configuration
   - `controller` = HTTP API endpoints
   - `service` = business logic
   - `dao` = database access
   - `model` = JPA entities
   - `io` = API DTOs
   - `filter` and `util` = cross-cutting security/token support

11. **External dependencies that matter architecturally**
   - **Spring Security** defines the authentication model and filter chain.
   - **Spring Data JPA + PostgreSQL** provide persistence.
   - **Spring Mail** provides outbound email delivery.
   - **JJWT** provides token handling.
   - **Lombok** reduces boilerplate, but doesn’t change the runtime architecture.

12. **Testing and packaging**
   - There is a small test footprint visible (`AuthifyApplicationTests`), so the repo appears to rely mostly on integration-style Spring Boot wiring rather than a large standalone test harness.
   - The project is packaged as a deployable Spring Boot service, with optional Docker support described in the README.

Main entry points: [`src/main/java/com/frostyfox/authify/controller/AuthController.java`](https://github.com/gowtham-m-2005/spring-authify/blob/main/src/main/java/com/frostyfox/authify/controller/AuthController.java) (Auth API), [`src/main/java/com/frostyfox/authify/controller/ProfileController.java`](https://github.com/gowtham-m-2005/spring-authify/blob/main/src/main/java/com/frostyfox/authify/controller/ProfileController.java) (Profile API), [`src/main/java/com/frostyfox/authify/dao/UserDao.java`](https://github.com/gowtham-m-2005/spring-authify/blob/main/src/main/java/com/frostyfox/authify/dao/UserDao.java) (User DAO), [`src/main/java/com/frostyfox/authify/config/SecurityConfig.java`](https://github.com/gowtham-m-2005/spring-authify/blob/main/src/main/java/com/frostyfox/authify/config/SecurityConfig.java) (Security config)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_bootstrap["Bootstrap"]
  node_app(("Authify<br/>Spring Boot app"))
end

subgraph group_security["Security"]
  node_security_config["Security config"]
  node_jwt_filter["JWT filter<br/>Security filter"]
  node_auth_entrypoint["Auth entrypoint<br/>Security handler"]
  node_jwt_util["JWT util<br/>Token utility<br/>[JwtUtil.java]"]
  node_user_details["User details<br/>Spring Security bridge"]
end

subgraph group_api["API"]
  node_auth_controller["Auth API<br/>REST controller"]
  node_profile_controller["Profile API<br/>REST controller"]
  node_auth_request["Auth request<br/>DTO<br/>[AuthRequest.java]"]
  node_auth_response["Auth response<br/>DTO<br/>[AuthResponse.java]"]
  node_reset_request["Reset request<br/>DTO"]
  node_profile_request["Profile request<br/>DTO"]
  node_profile_response["Profile response<br/>DTO"]
end

subgraph group_service["Services"]
  node_profile_service["Profile service<br/>Service interface"]
  node_profile_impl["Profile impl<br/>Profile service"]
  node_email_service["Email service<br/>SMTP service<br/>[EmailService.java]"]
end

subgraph group_persistence["Persistence"]
  node_user_entity[("User entity<br/>JPA entity<br/>[UserEntity.java]")]
  node_user_dao["User DAO<br/>[UserDao.java]"]
end

subgraph group_infra["Infrastructure"]
  node_application_yml["App config<br/>YAML config<br/>[application.yml]"]
  node_templates["Email templates<br/>HTML templates"]
end

node_app -->|"loads security"| node_security_config
node_app -->|"reads config"| node_application_yml
node_security_config -->|"installs"| node_jwt_filter
node_security_config -->|"configures"| node_auth_entrypoint
node_jwt_filter -->|"validates token"| node_jwt_util
node_jwt_filter -->|"loads user"| node_user_details
node_user_details -->|"queries"| node_user_dao
node_user_dao -->|"maps"| node_user_entity
node_auth_controller -->|"accepts"| node_auth_request
node_auth_controller -->|"returns"| node_auth_response
node_auth_controller -->|"accepts"| node_reset_request
node_auth_controller -->|"authenticates via"| node_user_details
node_auth_controller -->|"issues token"| node_jwt_util
node_auth_controller -->|"sends otp"| node_email_service
node_profile_controller -->|"uses"| node_profile_service
node_profile_service -->|"implemented by"| node_profile_impl
node_profile_impl -->|"reads/writes"| node_user_dao
node_profile_controller -->|"accepts"| node_profile_request
node_profile_controller -->|"returns"| node_profile_response
node_email_service -->|"renders"| node_templates
node_email_service -->|"updates user"| node_user_dao
node_auth_controller -.->|"shares auth boundary"| node_profile_controller

click node_app "https://github.com/gowtham-m-2005/spring-authify/blob/main/src/main/java/com/frostyfox/authify/AuthifyApplication.java"
click node_security_config "https://github.com/gowtham-m-2005/spring-authify/blob/main/src/main/java/com/frostyfox/authify/config/SecurityConfig.java"
click node_jwt_filter "https://github.com/gowtham-m-2005/spring-authify/blob/main/src/main/java/com/frostyfox/authify/filter/JwtRequestFilter.java"
click node_auth_entrypoint "https://github.com/gowtham-m-2005/spring-authify/blob/main/src/main/java/com/frostyfox/authify/config/CustomAuthenticationEntryPoint.java"
click node_jwt_util "https://github.com/gowtham-m-2005/spring-authify/blob/main/src/main/java/com/frostyfox/authify/util/JwtUtil.java"
click node_user_details "https://github.com/gowtham-m-2005/spring-authify/blob/main/src/main/java/com/frostyfox/authify/service/AppUserDetailsService.java"
click node_auth_controller "https://github.com/gowtham-m-2005/spring-authify/blob/main/src/main/java/com/frostyfox/authify/controller/AuthController.java"
click node_profile_controller "https://github.com/gowtham-m-2005/spring-authify/blob/main/src/main/java/com/frostyfox/authify/controller/ProfileController.java"
click node_auth_request "https://github.com/gowtham-m-2005/spring-authify/blob/main/src/main/java/com/frostyfox/authify/io/AuthRequest.java"
click node_auth_response "https://github.com/gowtham-m-2005/spring-authify/blob/main/src/main/java/com/frostyfox/authify/io/AuthResponse.java"
click node_reset_request "https://github.com/gowtham-m-2005/spring-authify/blob/main/src/main/java/com/frostyfox/authify/io/ResetPasswordRequest.java"
click node_profile_request "https://github.com/gowtham-m-2005/spring-authify/blob/main/src/main/java/com/frostyfox/authify/io/ProfileRequest.java"
click node_profile_response "https://github.com/gowtham-m-2005/spring-authify/blob/main/src/main/java/com/frostyfox/authify/io/ProfileResponse.java"
click node_profile_service "https://github.com/gowtham-m-2005/spring-authify/blob/main/src/main/java/com/frostyfox/authify/service/ProfileService.java"
click node_profile_impl "https://github.com/gowtham-m-2005/spring-authify/blob/main/src/main/java/com/frostyfox/authify/service/ProfileServiceImpl.java"
click node_email_service "https://github.com/gowtham-m-2005/spring-authify/blob/main/src/main/java/com/frostyfox/authify/service/EmailService.java"
click node_user_entity "https://github.com/gowtham-m-2005/spring-authify/blob/main/src/main/java/com/frostyfox/authify/model/UserEntity.java"
click node_user_dao "https://github.com/gowtham-m-2005/spring-authify/blob/main/src/main/java/com/frostyfox/authify/dao/UserDao.java"
click node_application_yml "https://github.com/gowtham-m-2005/spring-authify/blob/main/src/main/resources/application.yml"
click node_templates "https://github.com/gowtham-m-2005/spring-authify/tree/main/src/main/resources/templates"

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_app toneBlue
class node_security_config,node_jwt_filter,node_auth_entrypoint,node_jwt_util,node_user_details toneAmber
class node_auth_controller,node_profile_controller,node_auth_request,node_auth_response,node_reset_request,node_profile_request,node_profile_response toneMint
class node_profile_service,node_profile_impl,node_email_service toneRose
class node_user_entity,node_user_dao toneIndigo
class node_application_yml,node_templates toneTeal
```

## Components

### Bootstrap

Application entrypoint and runtime wiring

- [Authify](https://github.com/gowtham-m-2005/spring-authify/blob/main/src/main/java/com/frostyfox/authify/AuthifyApplication.java): Spring Boot app · Application entry point · `src/main/java/com/frostyfox/authify/AuthifyApplication.java`

### Security

Authentication and request protection

- [Security config](https://github.com/gowtham-m-2005/spring-authify/blob/main/src/main/java/com/frostyfox/authify/config/SecurityConfig.java): Spring Security config · Configures authentication and authorization · `src/main/java/com/frostyfox/authify/config/SecurityConfig.java`
- [JWT filter](https://github.com/gowtham-m-2005/spring-authify/blob/main/src/main/java/com/frostyfox/authify/filter/JwtRequestFilter.java): Security filter · Validates bearer token on requests · `src/main/java/com/frostyfox/authify/filter/JwtRequestFilter.java`
- [Auth entrypoint](https://github.com/gowtham-m-2005/spring-authify/blob/main/src/main/java/com/frostyfox/authify/config/CustomAuthenticationEntryPoint.java): Security handler · Handles unauthenticated and unauthorized access · `src/main/java/com/frostyfox/authify/config/CustomAuthenticationEntryPoint.java`
- [JWT util](https://github.com/gowtham-m-2005/spring-authify/blob/main/src/main/java/com/frostyfox/authify/util/JwtUtil.java): Token utility · Creates and validates JWTs · `src/main/java/com/frostyfox/authify/util/JwtUtil.java`
- [User details](https://github.com/gowtham-m-2005/spring-authify/blob/main/src/main/java/com/frostyfox/authify/service/AppUserDetailsService.java): Spring Security bridge · Loads users for authentication · `src/main/java/com/frostyfox/authify/service/AppUserDetailsService.java`

### API

REST controllers and request/response contracts

- [Auth API](https://github.com/gowtham-m-2005/spring-authify/blob/main/src/main/java/com/frostyfox/authify/controller/AuthController.java): REST controller · Login, status, OTP, and password reset endpoints · `src/main/java/com/frostyfox/authify/controller/AuthController.java`
- [Profile API](https://github.com/gowtham-m-2005/spring-authify/blob/main/src/main/java/com/frostyfox/authify/controller/ProfileController.java): REST controller · Protected profile operations · `src/main/java/com/frostyfox/authify/controller/ProfileController.java`
- [Auth request](https://github.com/gowtham-m-2005/spring-authify/blob/main/src/main/java/com/frostyfox/authify/io/AuthRequest.java): DTO · Login and auth payloads · `src/main/java/com/frostyfox/authify/io/AuthRequest.java`
- [Auth response](https://github.com/gowtham-m-2005/spring-authify/blob/main/src/main/java/com/frostyfox/authify/io/AuthResponse.java): DTO · Authentication result payload · `src/main/java/com/frostyfox/authify/io/AuthResponse.java`
- [Reset request](https://github.com/gowtham-m-2005/spring-authify/blob/main/src/main/java/com/frostyfox/authify/io/ResetPasswordRequest.java): DTO · Password reset submission payload · `src/main/java/com/frostyfox/authify/io/ResetPasswordRequest.java`
- [Profile request](https://github.com/gowtham-m-2005/spring-authify/blob/main/src/main/java/com/frostyfox/authify/io/ProfileRequest.java): DTO · Profile update payload · `src/main/java/com/frostyfox/authify/io/ProfileRequest.java`
- [Profile response](https://github.com/gowtham-m-2005/spring-authify/blob/main/src/main/java/com/frostyfox/authify/io/ProfileResponse.java): DTO · Profile output payload · `src/main/java/com/frostyfox/authify/io/ProfileResponse.java`

### Services

Business logic and outbound integrations

- [Profile service](https://github.com/gowtham-m-2005/spring-authify/blob/main/src/main/java/com/frostyfox/authify/service/ProfileService.java): Service interface · Profile business boundary · `src/main/java/com/frostyfox/authify/service/ProfileService.java`
- [Profile impl](https://github.com/gowtham-m-2005/spring-authify/blob/main/src/main/java/com/frostyfox/authify/service/ProfileServiceImpl.java): Profile service · Reads and updates profile data · `src/main/java/com/frostyfox/authify/service/ProfileServiceImpl.java`
- [Email service](https://github.com/gowtham-m-2005/spring-authify/blob/main/src/main/java/com/frostyfox/authify/service/EmailService.java): SMTP service · Sends verification, welcome, and reset emails · `src/main/java/com/frostyfox/authify/service/EmailService.java`

### Persistence

Entity and data-access layer

- [User entity](https://github.com/gowtham-m-2005/spring-authify/blob/main/src/main/java/com/frostyfox/authify/model/UserEntity.java): JPA entity · Persisted user record · `src/main/java/com/frostyfox/authify/model/UserEntity.java`
- [User DAO](https://github.com/gowtham-m-2005/spring-authify/blob/main/src/main/java/com/frostyfox/authify/dao/UserDao.java): Repository · Database access boundary for users · `src/main/java/com/frostyfox/authify/dao/UserDao.java`

### Infrastructure

Build, config, and runtime resources

- [App config](https://github.com/gowtham-m-2005/spring-authify/blob/main/src/main/resources/application.yml): YAML config · Database, mail, JWT, and context settings · `src/main/resources/application.yml`
- [Email templates](https://github.com/gowtham-m-2005/spring-authify/tree/main/src/main/resources/templates): HTML templates · Welcome, verification, and password reset mail bodies · `src/main/resources/templates`

## Connections

- Authify → Security config: loads security · Bootstraps the security boundary
- Authify → App config: reads config · Loads runtime settings
- Security config → JWT filter: installs · Adds JWT validation to the filter chain
- Security config → Auth entrypoint: configures · Sets unauthorized access handling
- JWT filter → JWT util: validates token · Parses and checks JWTs
- JWT filter → User details: loads user · Resolves authenticated identity
- User details → User DAO: queries · Looks up user records
- User DAO → User entity: maps · Persists and reads user data
- Auth API → Auth request: accepts · Consumes login payloads
- Auth API → Auth response: returns · Emits authentication results
- Auth API → Reset request: accepts · Consumes password reset payloads
- Auth API → User details: authenticates via · Delegates identity lookup
- Auth API → JWT util: issues token · Creates JWT after successful login
- Auth API → Email service: sends otp · Triggers recovery email delivery
- Profile API → Profile service: uses · Delegates profile operations
- Profile service → Profile impl: implemented by · Concrete profile business logic
- Profile impl → User DAO: reads/writes · Persists profile changes
- Profile API → Profile request: accepts · Consumes profile updates
- Profile API → Profile response: returns · Emits profile data
- Email service → Email templates: renders · Uses HTML email bodies
- Email service → User DAO: updates user · Supports verification and reset flows
- Auth API → Profile API: shares auth boundary · Both operate behind JWT-protected access