atharva759/authify

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.