# aryaraj76438/authservice architecture

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

- Interactive diagram: https://gitdiagram.com/aryaraj76438/authservice
- Repository: https://github.com/aryaraj76438/authservice

## Overview

AuthService is a Spring authentication backend. The principal workflow is account registration, email verification, login, and session renewal or revocation; separate workflows support password reset and protected-request authentication. README documents PostgreSQL persistence, Redis security state, and asynchronous retryable email delivery. The tree and excerpts establish controller/service and several security interactions; unsampled service implementations are represented only at their existing enclosing directory, with wiring limited to documented behavior.

Main entry points: [`src/main/java/com/authservice/authservice/service/AuthService.java`](https://github.com/aryaraj76438/authservice/blob/main/src/main/java/com/authservice/authservice/service/AuthService.java) (Authentication workflows), [`src/main/java/com/authservice/authservice/controller/AuthController.java`](https://github.com/aryaraj76438/authservice/blob/main/src/main/java/com/authservice/authservice/controller/AuthController.java) (Auth endpoints), [`src/main/java/com/authservice/authservice/service/EmailService.java`](https://github.com/aryaraj76438/authservice/blob/main/src/main/java/com/authservice/authservice/service/EmailService.java) (Email composition), [`src/main/java/com/authservice/authservice/repository/UserRepository.java`](https://github.com/aryaraj76438/authservice/blob/main/src/main/java/com/authservice/authservice/repository/UserRepository.java) (User records)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and flow"]
  node_auth_controller["Auth endpoints"]
  node_auth_service["Authentication workflows<br/>[AuthService.java]"]
  node_password_reset["Password reset"]
  node_cookie_service["Refresh cookies<br/>[CookieService.java]"]
  node_exception_handler["Error responses"]
end

subgraph group_identity["Identity and tokens"]
  node_jwt_service["JWT issuance<br/>[JwtService.java]"]
  node_user_details["User lookup"]
end

subgraph group_security["Request security"]
  node_jwt_filter["JWT authentication filter"]
  node_rate_filter["Rate limit filter"]
  node_rate_service["Rate limit checks"]
end

subgraph group_messaging["Email delivery"]
  node_email_service["Email composition<br/>[EmailService.java]"]
  node_outbox_service["Outbox queueing"]
  node_outbox_processor["Outbox retries"]
end

subgraph group_state["Persistence and state"]
  node_user_repository["User records"]
  node_verification_repository["Verification tokens"]
  node_refresh_repository["Refresh sessions"]
  node_outbox_repository["Outbox records"]
  node_redis_service["Redis access<br/>[RedisService.java]"]
end

node_client(("Client"))
node_postgres[("PostgreSQL")]
node_redis[("Redis")]
node_smtp(("SMTP provider"))

node_client -->|"sends requests"| node_auth_controller
node_auth_controller -->|"invokes auth"| node_auth_service
node_auth_controller -->|"invokes reset"| node_password_reset
node_auth_controller -->|"handles cookies"| node_cookie_service
node_auth_service -->|"reads/writes users"| node_user_repository
node_auth_service -->|"manages verification"| node_verification_repository
node_auth_service -->|"manages sessions"| node_refresh_repository
node_auth_service -->|"checks login state"| node_redis_service
node_auth_service -->|"issues access token"| node_jwt_service
node_auth_service -->|"requests email"| node_email_service
node_password_reset -->|"requests reset email"| node_email_service
node_jwt_filter -->|"validates token"| node_jwt_service
node_jwt_filter -->|"loads identity"| node_user_details
node_user_details -->|"finds user"| node_user_repository
node_rate_filter -->|"checks quota"| node_rate_service
node_rate_service -->|"updates counters"| node_redis_service
node_email_service -->|"queues message"| node_outbox_service
node_outbox_service -->|"persists message"| node_outbox_repository
node_outbox_processor -->|"loads pending mail"| node_outbox_repository
node_outbox_processor -.->|"delivers email"| node_smtp
node_user_repository -->|"persists users"| node_postgres
node_verification_repository -->|"persists tokens"| node_postgres
node_refresh_repository -->|"persists sessions"| node_postgres
node_outbox_repository -->|"persists queue"| node_postgres
node_redis_service -->|"reads/writes state"| node_redis
node_auth_controller -->|"errors handled by"| node_exception_handler

click node_auth_controller "https://github.com/aryaraj76438/authservice/blob/main/src/main/java/com/authservice/authservice/controller/AuthController.java"
click node_auth_service "https://github.com/aryaraj76438/authservice/blob/main/src/main/java/com/authservice/authservice/service/AuthService.java"
click node_password_reset "https://github.com/aryaraj76438/authservice/tree/main/src/main/java/com/authservice/authservice/service"
click node_cookie_service "https://github.com/aryaraj76438/authservice/blob/main/src/main/java/com/authservice/authservice/service/CookieService.java"
click node_exception_handler "https://github.com/aryaraj76438/authservice/blob/main/src/main/java/com/authservice/authservice/exception/GlobalExceptionHandler.java"
click node_jwt_service "https://github.com/aryaraj76438/authservice/blob/main/src/main/java/com/authservice/authservice/security/JwtService.java"
click node_user_details "https://github.com/aryaraj76438/authservice/blob/main/src/main/java/com/authservice/authservice/security/CustomUserDetailsService.java"
click node_jwt_filter "https://github.com/aryaraj76438/authservice/blob/main/src/main/java/com/authservice/authservice/security/JwtAuthenticationFilter.java"
click node_rate_filter "https://github.com/aryaraj76438/authservice/blob/main/src/main/java/com/authservice/authservice/security/RateLimitFilter.java"
click node_rate_service "https://github.com/aryaraj76438/authservice/blob/main/src/main/java/com/authservice/authservice/service/RateLimitService.java"
click node_email_service "https://github.com/aryaraj76438/authservice/blob/main/src/main/java/com/authservice/authservice/service/EmailService.java"
click node_outbox_service "https://github.com/aryaraj76438/authservice/blob/main/src/main/java/com/authservice/authservice/service/EmailOutboxService.java"
click node_outbox_processor "https://github.com/aryaraj76438/authservice/blob/main/src/main/java/com/authservice/authservice/service/EmailOutboxProcessor.java"
click node_user_repository "https://github.com/aryaraj76438/authservice/blob/main/src/main/java/com/authservice/authservice/repository/UserRepository.java"
click node_verification_repository "https://github.com/aryaraj76438/authservice/blob/main/src/main/java/com/authservice/authservice/repository/VerificationTokenRepository.java"
click node_refresh_repository "https://github.com/aryaraj76438/authservice/blob/main/src/main/java/com/authservice/authservice/repository/RefreshTokenRepository.java"
click node_outbox_repository "https://github.com/aryaraj76438/authservice/blob/main/src/main/java/com/authservice/authservice/repository/EmailOutboxRepository.java"
click node_redis_service "https://github.com/aryaraj76438/authservice/blob/main/src/main/java/com/authservice/authservice/service/RedisService.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_auth_controller,node_auth_service,node_password_reset,node_cookie_service,node_exception_handler,node_client toneBlue
class node_jwt_service,node_user_details,node_postgres,node_redis toneAmber
class node_jwt_filter,node_rate_filter,node_rate_service toneMint
class node_email_service,node_outbox_service,node_outbox_processor toneRose
class node_user_repository,node_verification_repository,node_refresh_repository,node_outbox_repository,node_redis_service,node_smtp toneIndigo
```

## Components

### API and flow

- [Auth endpoints](https://github.com/aryaraj76438/authservice/blob/main/src/main/java/com/authservice/authservice/controller/AuthController.java): `src/main/java/com/authservice/authservice/controller/AuthController.java`
- [Authentication workflows](https://github.com/aryaraj76438/authservice/blob/main/src/main/java/com/authservice/authservice/service/AuthService.java): `src/main/java/com/authservice/authservice/service/AuthService.java`
- [Password reset](https://github.com/aryaraj76438/authservice/tree/main/src/main/java/com/authservice/authservice/service): `src/main/java/com/authservice/authservice/service`
- [Refresh cookies](https://github.com/aryaraj76438/authservice/blob/main/src/main/java/com/authservice/authservice/service/CookieService.java): `src/main/java/com/authservice/authservice/service/CookieService.java`
- [Error responses](https://github.com/aryaraj76438/authservice/blob/main/src/main/java/com/authservice/authservice/exception/GlobalExceptionHandler.java): `src/main/java/com/authservice/authservice/exception/GlobalExceptionHandler.java`

### Identity and tokens

- [JWT issuance](https://github.com/aryaraj76438/authservice/blob/main/src/main/java/com/authservice/authservice/security/JwtService.java): `src/main/java/com/authservice/authservice/security/JwtService.java`
- [User lookup](https://github.com/aryaraj76438/authservice/blob/main/src/main/java/com/authservice/authservice/security/CustomUserDetailsService.java): `src/main/java/com/authservice/authservice/security/CustomUserDetailsService.java`

### Request security

- [JWT authentication filter](https://github.com/aryaraj76438/authservice/blob/main/src/main/java/com/authservice/authservice/security/JwtAuthenticationFilter.java): `src/main/java/com/authservice/authservice/security/JwtAuthenticationFilter.java`
- [Rate limit filter](https://github.com/aryaraj76438/authservice/blob/main/src/main/java/com/authservice/authservice/security/RateLimitFilter.java): `src/main/java/com/authservice/authservice/security/RateLimitFilter.java`
- [Rate limit checks](https://github.com/aryaraj76438/authservice/blob/main/src/main/java/com/authservice/authservice/service/RateLimitService.java): `src/main/java/com/authservice/authservice/service/RateLimitService.java`

### Email delivery

- [Email composition](https://github.com/aryaraj76438/authservice/blob/main/src/main/java/com/authservice/authservice/service/EmailService.java): `src/main/java/com/authservice/authservice/service/EmailService.java`
- [Outbox queueing](https://github.com/aryaraj76438/authservice/blob/main/src/main/java/com/authservice/authservice/service/EmailOutboxService.java): `src/main/java/com/authservice/authservice/service/EmailOutboxService.java`
- [Outbox retries](https://github.com/aryaraj76438/authservice/blob/main/src/main/java/com/authservice/authservice/service/EmailOutboxProcessor.java): `src/main/java/com/authservice/authservice/service/EmailOutboxProcessor.java`

### Persistence and state

- [User records](https://github.com/aryaraj76438/authservice/blob/main/src/main/java/com/authservice/authservice/repository/UserRepository.java): `src/main/java/com/authservice/authservice/repository/UserRepository.java`
- [Verification tokens](https://github.com/aryaraj76438/authservice/blob/main/src/main/java/com/authservice/authservice/repository/VerificationTokenRepository.java): `src/main/java/com/authservice/authservice/repository/VerificationTokenRepository.java`
- [Refresh sessions](https://github.com/aryaraj76438/authservice/blob/main/src/main/java/com/authservice/authservice/repository/RefreshTokenRepository.java): `src/main/java/com/authservice/authservice/repository/RefreshTokenRepository.java`
- [Outbox records](https://github.com/aryaraj76438/authservice/blob/main/src/main/java/com/authservice/authservice/repository/EmailOutboxRepository.java): `src/main/java/com/authservice/authservice/repository/EmailOutboxRepository.java`
- [Redis access](https://github.com/aryaraj76438/authservice/blob/main/src/main/java/com/authservice/authservice/service/RedisService.java): `src/main/java/com/authservice/authservice/service/RedisService.java`

### Other components

- **Client**
- **PostgreSQL**
- **Redis**
- **SMTP provider**

## Connections

- Client → Auth endpoints: sends requests
- Auth endpoints → Authentication workflows: invokes auth
- Auth endpoints → Password reset: invokes reset
- Auth endpoints → Refresh cookies: handles cookies
- Authentication workflows → User records: reads/writes users
- Authentication workflows → Verification tokens: manages verification
- Authentication workflows → Refresh sessions: manages sessions
- Authentication workflows → Redis access: checks login state
- Authentication workflows → JWT issuance: issues access token
- Authentication workflows → Email composition: requests email
- Password reset → Email composition: requests reset email
- JWT authentication filter → JWT issuance: validates token
- JWT authentication filter → User lookup: loads identity
- User lookup → User records: finds user
- Rate limit filter → Rate limit checks: checks quota
- Rate limit checks → Redis access: updates counters
- Email composition → Outbox queueing: queues message
- Outbox queueing → Outbox records: persists message
- Outbox retries → Outbox records: loads pending mail
- Outbox retries → SMTP provider: delivers email
- User records → PostgreSQL: persists users
- Verification tokens → PostgreSQL: persists tokens
- Refresh sessions → PostgreSQL: persists sessions
- Outbox records → PostgreSQL: persists queue
- Redis access → Redis: reads/writes state
- Auth endpoints → Error responses: errors handled by