# atharva759/authify architecture

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

- Interactive diagram: https://gitdiagram.com/atharva759/authify
- Repository: https://github.com/atharva759/authify

## Overview

1. This repo is a two-tier auth system: a Spring Boot backend (`Backend/`) and a React/Vite frontend (`Frontend/`). The backend is the system of record for users, authentication state, OTP verification, and JWT issuance; the frontend is a thin UI client.

2. The backend is organized into clear layers:
   - `Controller` exposes HTTP endpoints.
   - `Service` holds business logic.
   - `UserRepository` persists data through Spring Data JPA.
   - `Entity` defines the database model.
   - `dto` carries request/response payloads.
   - `Config` and `util` implement security and token handling.
   This structure is the main architectural boundary for backend diagrams.

3. `AuthController` is the API entry point for the auth workflow. Based on the README, the key endpoints are registration, login, OTP send/verify, and a protected “me” endpoint. These endpoints orchestrate service calls rather than doing direct persistence or token logic.

4. `UserEntity` is the central persisted domain object. The repository layer (`UserRepository`) likely stores user credentials and profile/verification state in PostgreSQL via JPA. The app is not using a separate identity provider; authentication is self-managed in the backend.

5. Authentication is JWT-based. `JwtUtil` creates and validates tokens, while `JwtAuthenticationFilter` reads the JWT from the request cookie, validates it, and populates Spring Security’s context. `SecurityConfig` defines the security policy, including CORS, CSRF/session behavior, and which routes are public versus protected.

6. The login flow is cookie-centric rather than header-centric. The backend sets an HttpOnly JWT cookie (`jwt` per README), and the frontend sends requests with credentials enabled. That makes the browser cookie the bridge between UI and backend-authenticated requests.

7. OTP verification is handled as a separate email-based step. `EmailService` sends the OTP through SMTP/JavaMail and manages its lifecycle/expiry. `ProfileService` and/or auth services likely coordinate OTP generation, persistence, and verification against the user record or transient state.

8. `AppUserDetailsService` adapts persisted users to Spring Security’s user model. This is the lookup boundary where the security layer resolves a login identity from the stored user data before JWT creation or authenticated requests.

9. Error handling is centralized. `GlobalExceptionHandler` and `ApiError` provide a consistent API error shape, which is important for frontend integration and for keeping the auth flows predictable when login, OTP, or validation fails.

10. The frontend is a small client application with `Register.jsx`, `Login.jsx`, and `Profile.jsx` as the main screens, wired together by `App.jsx` and bootstrapped in `main.jsx`. The API boundary is isolated in `src/api/api.js`, which is where the browser talks to the backend base URL.

11. The frontend’s architectural role is presentation plus session-aware API calls. It does not own auth state authority; it submits credentials/OTP, receives responses, and relies on the backend-set cookie for subsequent authenticated calls like `/auth/me`.

12. Infrastructure-wise, the backend depends on PostgreSQL, Java 21, Spring Security, JPA, BCrypt, and SMTP. Build/runtime is Maven (`pom.xml`, wrapper scripts). The frontend is Vite-based React with package-managed local development and a separate dev server, typically on port 5173, talking to the backend over HTTP.

13. The minimal test footprint (`AuthSystemApplicationTests`) suggests the repo is primarily organized around functional application code rather than a large automated test suite. For architecture diagrams, the important production path is frontend → backend controller → service → repository/email/JWT/security → PostgreSQL/SMTP → response/cookie back to frontend.

Main entry points: [`Backend/src/main/java/com/authsystem/authsystem/Controller/AuthController.java`](https://github.com/atharva759/authify/blob/main/Backend/src/main/java/com/authsystem/authsystem/Controller/AuthController.java) (Auth API), [`Frontend/src/api/api.js`](https://github.com/atharva759/authify/blob/main/Frontend/src/api/api.js) (API client), [`Frontend/src/App.jsx`](https://github.com/atharva759/authify/blob/main/Frontend/src/App.jsx) (App), [`Backend/src/main/java/com/authsystem/authsystem/Service/ProfileService.java`](https://github.com/atharva759/authify/blob/main/Backend/src/main/java/com/authsystem/authsystem/Service/ProfileService.java) (Profile svc)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_backend["Backend"]
  node_backend_controller["Auth API<br/>REST controller"]
  node_backend_profile["Profile svc<br/>business service"]
  node_backend_email["Email svc<br/>mail service<br/>[EmailService.java]"]
  node_backend_details["User details<br/>security adapter"]
  node_backend_repo[("User repo<br/>JPA repository")]
  node_backend_entity["User entity<br/>domain model<br/>[UserEntity.java]"]
  node_backend_jwt["JWT util<br/>token utility<br/>[JwtUtil.java]"]
  node_backend_filter["JWT filter<br/>security filter"]
  node_backend_security["Security config<br/>security policy"]
  node_backend_error["Errors<br/>error handling"]
  node_backend_apierror["API error<br/>error schema<br/>[ApiError.java]"]
  node_backend_dto["DTOs<br/>payload models<br/>[LoginRequest.java]"]
end

subgraph group_frontend["Frontend"]
  node_frontend_app["App<br/>React shell<br/>[App.jsx]"]
  node_frontend_register["Register<br/>screen<br/>[Register.jsx]"]
  node_frontend_login["Login<br/>screen<br/>[Login.jsx]"]
  node_frontend_profile["Profile<br/>screen<br/>[Profile.jsx]"]
  node_frontend_api["API client<br/>HTTP client<br/>[api.js]"]
end

node_frontend_app -->|"shows"| node_frontend_register
node_frontend_app -->|"shows"| node_frontend_login
node_frontend_app -->|"shows"| node_frontend_profile
node_frontend_register -->|"registers"| node_frontend_api
node_frontend_login -->|"logs in"| node_frontend_api
node_frontend_profile -->|"me request"| node_frontend_api
node_frontend_api -->|"HTTP"| node_backend_controller
node_backend_controller -->|"maps payloads"| node_backend_dto
node_backend_controller -->|"orchestrates"| node_backend_profile
node_backend_controller -->|"issues tokens"| node_backend_jwt
node_backend_controller -->|"fails via"| node_backend_error
node_backend_profile -->|"reads/writes"| node_backend_repo
node_backend_profile -->|"sends otp"| node_backend_email
node_backend_repo -->|"stores"| node_backend_entity
node_backend_details -->|"loads user"| node_backend_repo
node_backend_filter -->|"validates"| node_backend_jwt
node_backend_filter -->|"enforced by"| node_backend_security
node_backend_security -->|"protects routes"| node_backend_controller
node_backend_error -->|"emits"| node_backend_apierror

click node_frontend_app "https://github.com/atharva759/authify/blob/main/Frontend/src/App.jsx"
click node_frontend_register "https://github.com/atharva759/authify/blob/main/Frontend/src/Register.jsx"
click node_frontend_login "https://github.com/atharva759/authify/blob/main/Frontend/src/Login.jsx"
click node_frontend_profile "https://github.com/atharva759/authify/blob/main/Frontend/src/Profile.jsx"
click node_frontend_api "https://github.com/atharva759/authify/blob/main/Frontend/src/api/api.js"
click node_backend_controller "https://github.com/atharva759/authify/blob/main/Backend/src/main/java/com/authsystem/authsystem/Controller/AuthController.java"
click node_backend_profile "https://github.com/atharva759/authify/blob/main/Backend/src/main/java/com/authsystem/authsystem/Service/ProfileService.java"
click node_backend_email "https://github.com/atharva759/authify/blob/main/Backend/src/main/java/com/authsystem/authsystem/Service/EmailService.java"
click node_backend_details "https://github.com/atharva759/authify/blob/main/Backend/src/main/java/com/authsystem/authsystem/Service/AppUserDetailsService.java"
click node_backend_repo "https://github.com/atharva759/authify/blob/main/Backend/src/main/java/com/authsystem/authsystem/UserRepository/UserRepository.java"
click node_backend_entity "https://github.com/atharva759/authify/blob/main/Backend/src/main/java/com/authsystem/authsystem/Entity/UserEntity.java"
click node_backend_jwt "https://github.com/atharva759/authify/blob/main/Backend/src/main/java/com/authsystem/authsystem/util/JwtUtil.java"
click node_backend_filter "https://github.com/atharva759/authify/blob/main/Backend/src/main/java/com/authsystem/authsystem/Config/JwtAuthenticationFilter.java"
click node_backend_security "https://github.com/atharva759/authify/blob/main/Backend/src/main/java/com/authsystem/authsystem/Config/SecurityConfig.java"
click node_backend_error "https://github.com/atharva759/authify/blob/main/Backend/src/main/java/com/authsystem/authsystem/Exception/GlobalExceptionHandler.java"
click node_backend_apierror "https://github.com/atharva759/authify/blob/main/Backend/src/main/java/com/authsystem/authsystem/Exception/ApiError.java"
click node_backend_dto "https://github.com/atharva759/authify/blob/main/Backend/src/main/java/com/authsystem/authsystem/dto/LoginRequest.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_backend_controller,node_backend_profile,node_backend_email,node_backend_details,node_backend_repo,node_backend_entity,node_backend_jwt,node_backend_filter,node_backend_security,node_backend_error,node_backend_apierror,node_backend_dto toneBlue
class node_frontend_app,node_frontend_register,node_frontend_login,node_frontend_profile,node_frontend_api toneAmber
```

## Components

### Backend

Spring Boot auth API, security, persistence, and email flows.

- [Auth API](https://github.com/atharva759/authify/blob/main/Backend/src/main/java/com/authsystem/authsystem/Controller/AuthController.java): REST controller · HTTP entry point for register, login, OTP, and me flows. · `Backend/src/main/java/com/authsystem/authsystem/Controller/AuthController.java`
- [Profile svc](https://github.com/atharva759/authify/blob/main/Backend/src/main/java/com/authsystem/authsystem/Service/ProfileService.java): business service · Coordinates profile lookup and OTP-related user state. · `Backend/src/main/java/com/authsystem/authsystem/Service/ProfileService.java`
- [Email svc](https://github.com/atharva759/authify/blob/main/Backend/src/main/java/com/authsystem/authsystem/Service/EmailService.java): mail service · Sends OTP messages and manages delivery lifecycle. · `Backend/src/main/java/com/authsystem/authsystem/Service/EmailService.java`
- [User details](https://github.com/atharva759/authify/blob/main/Backend/src/main/java/com/authsystem/authsystem/Service/AppUserDetailsService.java): security adapter · Loads persisted users into Spring Security's user model. · `Backend/src/main/java/com/authsystem/authsystem/Service/AppUserDetailsService.java`
- [User repo](https://github.com/atharva759/authify/blob/main/Backend/src/main/java/com/authsystem/authsystem/UserRepository/UserRepository.java): JPA repository · Persistence gateway for user records. · `Backend/src/main/java/com/authsystem/authsystem/UserRepository/UserRepository.java`
- [User entity](https://github.com/atharva759/authify/blob/main/Backend/src/main/java/com/authsystem/authsystem/Entity/UserEntity.java): domain model · Persisted user state for credentials, profile, and verification. · `Backend/src/main/java/com/authsystem/authsystem/Entity/UserEntity.java`
- [JWT util](https://github.com/atharva759/authify/blob/main/Backend/src/main/java/com/authsystem/authsystem/util/JwtUtil.java): token utility · Creates and validates JWTs. · `Backend/src/main/java/com/authsystem/authsystem/util/JwtUtil.java`
- [JWT filter](https://github.com/atharva759/authify/blob/main/Backend/src/main/java/com/authsystem/authsystem/Config/JwtAuthenticationFilter.java): security filter · Reads the auth cookie, validates JWT, and populates context. · `Backend/src/main/java/com/authsystem/authsystem/Config/JwtAuthenticationFilter.java`
- [Security config](https://github.com/atharva759/authify/blob/main/Backend/src/main/java/com/authsystem/authsystem/Config/SecurityConfig.java): security policy · Defines route protection, CORS, and session/CSRF behavior. · `Backend/src/main/java/com/authsystem/authsystem/Config/SecurityConfig.java`
- [Errors](https://github.com/atharva759/authify/blob/main/Backend/src/main/java/com/authsystem/authsystem/Exception/GlobalExceptionHandler.java): error handling · Normalizes API failures into consistent responses. · `Backend/src/main/java/com/authsystem/authsystem/Exception/GlobalExceptionHandler.java`
- [API error](https://github.com/atharva759/authify/blob/main/Backend/src/main/java/com/authsystem/authsystem/Exception/ApiError.java): error schema · Shared error payload returned to clients. · `Backend/src/main/java/com/authsystem/authsystem/Exception/ApiError.java`
- [DTOs](https://github.com/atharva759/authify/blob/main/Backend/src/main/java/com/authsystem/authsystem/dto/LoginRequest.java): payload models · Request and response contracts for auth endpoints. · `Backend/src/main/java/com/authsystem/authsystem/dto/LoginRequest.java`

### Frontend

React/Vite client UI and API boundary.

- [App](https://github.com/atharva759/authify/blob/main/Frontend/src/App.jsx): React shell · Top-level client composition and routing. · `Frontend/src/App.jsx`
- [Register](https://github.com/atharva759/authify/blob/main/Frontend/src/Register.jsx): screen · Registration UI and OTP initiation. · `Frontend/src/Register.jsx`
- [Login](https://github.com/atharva759/authify/blob/main/Frontend/src/Login.jsx): screen · Login UI that submits credentials. · `Frontend/src/Login.jsx`
- [Profile](https://github.com/atharva759/authify/blob/main/Frontend/src/Profile.jsx): screen · Authenticated profile view backed by cookie auth. · `Frontend/src/Profile.jsx`
- [API client](https://github.com/atharva759/authify/blob/main/Frontend/src/api/api.js): HTTP client · Browser-to-backend request layer and base URL handling. · `Frontend/src/api/api.js`

## Connections

- App → Register: shows · App composes the registration screen.
- App → Login: shows · App composes the login screen.
- App → Profile: shows · App composes the profile screen.
- Register → API client: registers · Registration submits to backend endpoints via the API client.
- Login → API client: logs in · Login submits credentials through the API client.
- Profile → API client: me request · Profile fetches authenticated user data through cookie-backed requests.
- API client → Auth API: HTTP · Client calls the auth API over HTTP with credentials enabled.
- Auth API → DTOs: maps payloads · Controller binds request and response DTOs.
- Auth API → Profile svc: orchestrates · Controller delegates profile and OTP-related workflows.
- Auth API → JWT util: issues tokens · Login flow creates JWTs for authenticated sessions.
- Auth API → Errors: fails via · Controller errors are normalized by global handling.
- Profile svc → User repo: reads/writes · Profile service persists and retrieves user state.
- Profile svc → Email svc: sends otp · Profile or auth flow triggers OTP delivery.
- User repo → User entity: stores · Repository persists the user domain entity.
- User details → User repo: loads user · Security adapter resolves identities from stored users.
- JWT filter → JWT util: validates · Filter validates JWTs extracted from the cookie.
- JWT filter → Security config: enforced by · Security config installs the authentication filter.
- Security config → Auth API: protects routes · Security policy splits public and protected endpoints.
- Errors → API error: emits · Global handling returns a shared error shape.