# khinya-khinev/auth-service architecture

> Architecture diagram of the GitHub repository khinya-khinev/auth-service, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/khinya-khinev/auth-service
- Repository: https://github.com/khinya-khinev/auth-service

## Overview

Auth-Service is a Spring-based OAuth2/OpenID Connect authorization server for WMS employees. The main account workflow is an administrator submitting a registration request, which the API delegates to the user service to encode credentials, create a role-bearing user, and persist it; the server also authenticates users and issues tokens. The README documents PostgreSQL and token capabilities, while sampled code and the source index substantiate the registration and security wiring. Some persistence and token-runtime links are shown as unverified where source excerpts do not establish the connection.

Main entry points: [`src/main/java/com/waregang/auth_service/auth_server_config/AuthServerConfiguration.java`](https://github.com/khinya-khinev/auth-service/blob/main/src/main/java/com/waregang/auth_service/auth_server_config/AuthServerConfiguration.java) (Authorization server), [`src/main/java/com/waregang/auth_service/user/application/CustomUserDetailsService.java`](https://github.com/khinya-khinev/auth-service/blob/main/src/main/java/com/waregang/auth_service/user/application/CustomUserDetailsService.java) (User service), [`src/main/java/com/waregang/auth_service/user/domain/User.java`](https://github.com/khinya-khinev/auth-service/blob/main/src/main/java/com/waregang/auth_service/user/domain/User.java) (User and roles), [`src/main/java/com/waregang/auth_service/auth_server_config/SecurityFilterChainConfiguration.java`](https://github.com/khinya-khinev/auth-service/blob/main/src/main/java/com/waregang/auth_service/auth_server_config/SecurityFilterChainConfiguration.java) (Security filter chain)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_accounts["Account management"]
  node_user_api["User API"]
  node_registration_request["Registration request"]
  node_user_service["User service"]
  node_user_entity["User and roles<br/>[User.java]"]
  node_auth_dto["Authentication DTOs"]
  node_user_details["User details adapter<br/>[UserPrincipal.java]"]
end

subgraph group_authorization["OAuth authorization"]
  node_auth_server["Authorization server"]
  node_tokens["Access and identity tokens"]
end

subgraph group_security["Security and configuration"]
  node_security_chain["Security filter chain"]
  node_security_settings["Security settings"]
  node_auth_properties["Auth properties"]
  node_gateway_properties["Gateway properties"]
  node_jwt_properties["JWT properties<br/>[JwtProperties.java]"]
  node_access_denied["Access denied handler"]
  node_auth_entry["Authentication entry point"]
end

subgraph group_support["Persistence and errors"]
  node_user_repository["User repository"]
  node_postgres[("PostgreSQL")]
  node_schema["Database migrations"]
  node_exception_translation["Database error translation"]
  node_error_codes["Error codes<br/>[ErrorCode.java]"]
  node_app_exception["Application exceptions<br/>[AppException.java]"]
  node_exception_handler["Global error handler"]
  node_id_generator["ID generation<br/>[IdGenerator.java]"]
end

node_administrator(("Administrator"))
node_employee(("Employee or client"))

node_administrator -->|"registers accounts"| node_user_api
node_user_api -->|"accepts request"| node_registration_request
node_user_api -->|"delegates registration"| node_user_service
node_user_service -->|"saves and looks up"| node_user_repository
node_user_service -->|"creates users"| node_user_entity
node_user_service -->|"reads registration data"| node_registration_request
node_user_service -->|"translates database errors"| node_exception_translation
node_user_entity -->|"generates identifier"| node_id_generator
node_user_repository -->|"persists users"| node_user_entity
node_user_repository -.->|"stores records"| node_postgres
node_schema -.->|"defines schema"| node_postgres
node_employee -->|"authenticates"| node_auth_server
node_auth_server -->|"issues tokens"| node_tokens
node_auth_server -->|"uses settings"| node_auth_properties
node_auth_server -->|"uses settings"| node_gateway_properties
node_auth_server -->|"uses settings"| node_jwt_properties
node_auth_server -->|"uses user identity"| node_user_entity
node_auth_server -.->|"adapts user details"| node_user_details
node_employee -.->|"submits credentials"| node_auth_dto
node_security_chain -->|"configures handler"| node_access_denied
node_security_chain -->|"configures handler"| node_auth_entry
node_security_chain -.->|"applies settings"| node_security_settings
node_exception_translation -->|"selects codes"| node_error_codes
node_exception_translation -->|"creates exceptions"| node_app_exception
node_exception_handler -->|"handles exceptions"| node_app_exception

click node_user_api "https://github.com/khinya-khinev/auth-service/blob/main/src/main/java/com/waregang/auth_service/user/api/UserController.java"
click node_registration_request "https://github.com/khinya-khinev/auth-service/blob/main/src/main/java/com/waregang/auth_service/user/api/dto/RegisterUserRequest.java"
click node_user_service "https://github.com/khinya-khinev/auth-service/blob/main/src/main/java/com/waregang/auth_service/user/application/CustomUserDetailsService.java"
click node_user_entity "https://github.com/khinya-khinev/auth-service/blob/main/src/main/java/com/waregang/auth_service/user/domain/User.java"
click node_auth_dto "https://github.com/khinya-khinev/auth-service/blob/main/src/main/java/com/waregang/auth_service/user/api/dto/AuthenticationRequest.java"
click node_user_details "https://github.com/khinya-khinev/auth-service/blob/main/src/main/java/com/waregang/auth_service/auth_server_config/UserPrincipal.java"
click node_auth_server "https://github.com/khinya-khinev/auth-service/blob/main/src/main/java/com/waregang/auth_service/auth_server_config/AuthServerConfiguration.java"
click node_tokens "https://github.com/khinya-khinev/auth-service/blob/main/src/main/java/com/waregang/auth_service/auth_server_config/AuthServerConfiguration.java"
click node_security_chain "https://github.com/khinya-khinev/auth-service/blob/main/src/main/java/com/waregang/auth_service/auth_server_config/SecurityFilterChainConfiguration.java"
click node_security_settings "https://github.com/khinya-khinev/auth-service/blob/main/src/main/java/com/waregang/auth_service/auth_server_config/SecurityConfig.java"
click node_auth_properties "https://github.com/khinya-khinev/auth-service/blob/main/src/main/java/com/waregang/auth_service/auth_server_config/properties/AuthProperties.java"
click node_gateway_properties "https://github.com/khinya-khinev/auth-service/blob/main/src/main/java/com/waregang/auth_service/auth_server_config/properties/GatewayProperties.java"
click node_jwt_properties "https://github.com/khinya-khinev/auth-service/blob/main/src/main/java/com/waregang/auth_service/auth_server_config/properties/JwtProperties.java"
click node_access_denied "https://github.com/khinya-khinev/auth-service/blob/main/src/main/java/com/waregang/auth_service/auth_server_config/CustomAccessDeniedHandler.java"
click node_auth_entry "https://github.com/khinya-khinev/auth-service/blob/main/src/main/java/com/waregang/auth_service/auth_server_config/CustomAuthenticationEntryPoint.java"
click node_user_repository "https://github.com/khinya-khinev/auth-service/blob/main/src/main/java/com/waregang/auth_service/user/repository/UserRepository.java"
click node_schema "https://github.com/khinya-khinev/auth-service/blob/main/src/main/resources/db/migration/V1__init_schema.sql"
click node_exception_translation "https://github.com/khinya-khinev/auth-service/blob/main/src/main/java/com/waregang/auth_service/common/exception_handling/DatabaseExceptionTranslator.java"
click node_error_codes "https://github.com/khinya-khinev/auth-service/blob/main/src/main/java/com/waregang/auth_service/common/exception_handling/error_code/ErrorCode.java"
click node_app_exception "https://github.com/khinya-khinev/auth-service/blob/main/src/main/java/com/waregang/auth_service/common/exception_handling/AppException.java"
click node_exception_handler "https://github.com/khinya-khinev/auth-service/blob/main/src/main/java/com/waregang/auth_service/common/exception_handling/GlobalExceptionHandler.java"
click node_id_generator "https://github.com/khinya-khinev/auth-service/blob/main/src/main/java/com/waregang/auth_service/common/uuid/IdGenerator.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_user_api,node_registration_request,node_user_service,node_user_entity,node_auth_dto,node_user_details,node_employee toneBlue
class node_auth_server,node_tokens toneAmber
class node_security_chain,node_security_settings,node_auth_properties,node_gateway_properties,node_jwt_properties,node_access_denied,node_auth_entry toneMint
class node_user_repository,node_postgres,node_schema,node_exception_translation,node_error_codes,node_app_exception,node_exception_handler,node_id_generator toneRose
class node_administrator toneIndigo
```

## Components

### Account management

- [User API](https://github.com/khinya-khinev/auth-service/blob/main/src/main/java/com/waregang/auth_service/user/api/UserController.java): `src/main/java/com/waregang/auth_service/user/api/UserController.java`
- [Registration request](https://github.com/khinya-khinev/auth-service/blob/main/src/main/java/com/waregang/auth_service/user/api/dto/RegisterUserRequest.java): `src/main/java/com/waregang/auth_service/user/api/dto/RegisterUserRequest.java`
- [User service](https://github.com/khinya-khinev/auth-service/blob/main/src/main/java/com/waregang/auth_service/user/application/CustomUserDetailsService.java): `src/main/java/com/waregang/auth_service/user/application/CustomUserDetailsService.java`
- [User and roles](https://github.com/khinya-khinev/auth-service/blob/main/src/main/java/com/waregang/auth_service/user/domain/User.java): `src/main/java/com/waregang/auth_service/user/domain/User.java`
- [Authentication DTOs](https://github.com/khinya-khinev/auth-service/blob/main/src/main/java/com/waregang/auth_service/user/api/dto/AuthenticationRequest.java): `src/main/java/com/waregang/auth_service/user/api/dto/AuthenticationRequest.java`
- [User details adapter](https://github.com/khinya-khinev/auth-service/blob/main/src/main/java/com/waregang/auth_service/auth_server_config/UserPrincipal.java): `src/main/java/com/waregang/auth_service/auth_server_config/UserPrincipal.java`

### OAuth authorization

- [Authorization server](https://github.com/khinya-khinev/auth-service/blob/main/src/main/java/com/waregang/auth_service/auth_server_config/AuthServerConfiguration.java): `src/main/java/com/waregang/auth_service/auth_server_config/AuthServerConfiguration.java`
- [Access and identity tokens](https://github.com/khinya-khinev/auth-service/blob/main/src/main/java/com/waregang/auth_service/auth_server_config/AuthServerConfiguration.java): `src/main/java/com/waregang/auth_service/auth_server_config/AuthServerConfiguration.java`

### Security and configuration

- [Security filter chain](https://github.com/khinya-khinev/auth-service/blob/main/src/main/java/com/waregang/auth_service/auth_server_config/SecurityFilterChainConfiguration.java): `src/main/java/com/waregang/auth_service/auth_server_config/SecurityFilterChainConfiguration.java`
- [Security settings](https://github.com/khinya-khinev/auth-service/blob/main/src/main/java/com/waregang/auth_service/auth_server_config/SecurityConfig.java): `src/main/java/com/waregang/auth_service/auth_server_config/SecurityConfig.java`
- [Auth properties](https://github.com/khinya-khinev/auth-service/blob/main/src/main/java/com/waregang/auth_service/auth_server_config/properties/AuthProperties.java): `src/main/java/com/waregang/auth_service/auth_server_config/properties/AuthProperties.java`
- [Gateway properties](https://github.com/khinya-khinev/auth-service/blob/main/src/main/java/com/waregang/auth_service/auth_server_config/properties/GatewayProperties.java): `src/main/java/com/waregang/auth_service/auth_server_config/properties/GatewayProperties.java`
- [JWT properties](https://github.com/khinya-khinev/auth-service/blob/main/src/main/java/com/waregang/auth_service/auth_server_config/properties/JwtProperties.java): `src/main/java/com/waregang/auth_service/auth_server_config/properties/JwtProperties.java`
- [Access denied handler](https://github.com/khinya-khinev/auth-service/blob/main/src/main/java/com/waregang/auth_service/auth_server_config/CustomAccessDeniedHandler.java): `src/main/java/com/waregang/auth_service/auth_server_config/CustomAccessDeniedHandler.java`
- [Authentication entry point](https://github.com/khinya-khinev/auth-service/blob/main/src/main/java/com/waregang/auth_service/auth_server_config/CustomAuthenticationEntryPoint.java): `src/main/java/com/waregang/auth_service/auth_server_config/CustomAuthenticationEntryPoint.java`

### Persistence and errors

- [User repository](https://github.com/khinya-khinev/auth-service/blob/main/src/main/java/com/waregang/auth_service/user/repository/UserRepository.java): `src/main/java/com/waregang/auth_service/user/repository/UserRepository.java`
- **PostgreSQL**
- [Database migrations](https://github.com/khinya-khinev/auth-service/blob/main/src/main/resources/db/migration/V1__init_schema.sql): `src/main/resources/db/migration/V1__init_schema.sql`
- [Database error translation](https://github.com/khinya-khinev/auth-service/blob/main/src/main/java/com/waregang/auth_service/common/exception_handling/DatabaseExceptionTranslator.java): `src/main/java/com/waregang/auth_service/common/exception_handling/DatabaseExceptionTranslator.java`
- [Error codes](https://github.com/khinya-khinev/auth-service/blob/main/src/main/java/com/waregang/auth_service/common/exception_handling/error_code/ErrorCode.java): `src/main/java/com/waregang/auth_service/common/exception_handling/error_code/ErrorCode.java`
- [Application exceptions](https://github.com/khinya-khinev/auth-service/blob/main/src/main/java/com/waregang/auth_service/common/exception_handling/AppException.java): `src/main/java/com/waregang/auth_service/common/exception_handling/AppException.java`
- [Global error handler](https://github.com/khinya-khinev/auth-service/blob/main/src/main/java/com/waregang/auth_service/common/exception_handling/GlobalExceptionHandler.java): `src/main/java/com/waregang/auth_service/common/exception_handling/GlobalExceptionHandler.java`
- [ID generation](https://github.com/khinya-khinev/auth-service/blob/main/src/main/java/com/waregang/auth_service/common/uuid/IdGenerator.java): `src/main/java/com/waregang/auth_service/common/uuid/IdGenerator.java`

### Other components

- **Administrator**
- **Employee or client**

## Connections

- Administrator → User API: registers accounts (evidence: `src/main/java/com/waregang/auth_service/user/api/UserController.java`)
- User API → Registration request: accepts request (evidence: `src/main/java/com/waregang/auth_service/user/api/UserController.java`)
- User API → User service: delegates registration (evidence: `src/main/java/com/waregang/auth_service/user/api/UserController.java`)
- User service → User repository: saves and looks up (evidence: `src/main/java/com/waregang/auth_service/user/application/CustomUserDetailsService.java`)
- User service → User and roles: creates users (evidence: `src/main/java/com/waregang/auth_service/user/application/CustomUserDetailsService.java`)
- User service → Registration request: reads registration data (evidence: `src/main/java/com/waregang/auth_service/user/application/CustomUserDetailsService.java`)
- User service → Database error translation: translates database errors (evidence: `src/main/java/com/waregang/auth_service/user/application/CustomUserDetailsService.java`)
- User and roles → ID generation: generates identifier (evidence: `src/main/java/com/waregang/auth_service/user/domain/User.java`)
- User repository → User and roles: persists users (evidence: `src/main/java/com/waregang/auth_service/user/repository/UserRepository.java`)
- User repository → PostgreSQL: stores records
- Database migrations → PostgreSQL: defines schema
- Employee or client → Authorization server: authenticates (evidence: `README.md`)
- Authorization server → Access and identity tokens: issues tokens (evidence: `README.md`)
- Authorization server → Auth properties: uses settings (evidence: `src/main/java/com/waregang/auth_service/auth_server_config/AuthServerConfiguration.java`)
- Authorization server → Gateway properties: uses settings (evidence: `src/main/java/com/waregang/auth_service/auth_server_config/AuthServerConfiguration.java`)
- Authorization server → JWT properties: uses settings (evidence: `src/main/java/com/waregang/auth_service/auth_server_config/AuthServerConfiguration.java`)
- Authorization server → User and roles: uses user identity (evidence: `src/main/java/com/waregang/auth_service/auth_server_config/AuthServerConfiguration.java`)
- Authorization server → User details adapter: adapts user details
- Employee or client → Authentication DTOs: submits credentials
- Security filter chain → Access denied handler: configures handler (evidence: `src/main/java/com/waregang/auth_service/auth_server_config/SecurityFilterChainConfiguration.java`)
- Security filter chain → Authentication entry point: configures handler (evidence: `src/main/java/com/waregang/auth_service/auth_server_config/SecurityFilterChainConfiguration.java`)
- Security filter chain → Security settings: applies settings
- Database error translation → Error codes: selects codes (evidence: `src/main/java/com/waregang/auth_service/common/exception_handling/DatabaseExceptionTranslator.java`)
- Database error translation → Application exceptions: creates exceptions (evidence: `src/main/java/com/waregang/auth_service/common/exception_handling/DatabaseExceptionTranslator.java`)
- Global error handler → Application exceptions: handles exceptions (evidence: `src/main/java/com/waregang/auth_service/common/exception_handling/GlobalExceptionHandler.java`)
