gowtham-m-2005/spring-authify

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.