# raghul-r-0811/authorization-engine architecture

> Architecture diagram of the GitHub repository raghul-r-0811/authorization-engine, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/raghul-r-0811/authorization-engine
- Repository: https://github.com/raghul-r-0811/authorization-engine

## Overview

Authorization Engine is a Spring Boot backend for tenant-aware authentication and access management. The visible user flow accepts registration or login requests, delegates account work to services, persists users and role assignments, and returns API responses; JWT support is also present. Admin flows manage roles, permissions, and user-role assignments, with tenant scope checks and audit records. The README describes policy evaluation, custom voters, ABAC, and permission caching as goals or planned capabilities, not a complete implemented decision pipeline. Edges reflect excerpted calls, SOURCE INDEX references, or documented relationships; unsampled wiring is omitted.

Main entry points: [`auth_engine/src/main/java/org/raghul/auth_engine/service/UserService.java`](https://github.com/raghul-r-0811/authorization-engine/blob/main/auth_engine/src/main/java/org/raghul/auth_engine/service/UserService.java) (User lifecycle), [`auth_engine/src/main/java/org/raghul/auth_engine/service/UserRoleService.java`](https://github.com/raghul-r-0811/authorization-engine/blob/main/auth_engine/src/main/java/org/raghul/auth_engine/service/UserRoleService.java) (User-role assignment), [`auth_engine/src/main/java/org/raghul/auth_engine/controller/UserController.java`](https://github.com/raghul-r-0811/authorization-engine/blob/main/auth_engine/src/main/java/org/raghul/auth_engine/controller/UserController.java) (User management API), [`auth_engine/src/main/java/org/raghul/auth_engine/service/RoleService.java`](https://github.com/raghul-r-0811/authorization-engine/blob/main/auth_engine/src/main/java/org/raghul/auth_engine/service/RoleService.java) (Role permissions)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API entry points"]
  node_home["Auth endpoints"]
  node_user_controller["User management API"]
  node_admin_controller["Super-admin API"]
end

subgraph group_identity["Identity and tenants"]
  node_user_service["User lifecycle<br/>[UserService.java]"]
  node_login_details["User detail lookup"]
  node_jwt["JWT service<br/>[JwtService.java]"]
  node_jwt_filter["JWT filter<br/>[JwtAuthFilter.java]"]
  node_security_config["Security configuration"]
end

subgraph group_access["Roles and permissions"]
  node_user_roles["User-role assignment"]
  node_role_service["Role permissions<br/>[RoleService.java]"]
  node_tenant_policy["Tenant access policy"]
  node_superadmin_service["Tenant administration"]
  node_persistence[("JPA repositories")]
end

subgraph group_audit["Audit trail"]
  node_audit_service["Audit logging"]
  node_audit_repo[("Audit log repository<br/>[AuditLogRepo.java]")]
end

subgraph group_roadmap["Planned authorization"]
  node_policy_eval["Policy evaluation"]
  node_decision_voters["Decision voters"]
  node_permission_cache["Permission caching"]
end

node_client(("Backend client"))

node_client -->|"submits auth"| node_home
node_client -->|"manages users"| node_user_controller
node_home -->|"registers users"| node_user_service
node_home -->|"issues tokens"| node_jwt
node_login_details -->|"loads accounts"| node_persistence
node_jwt -->|"uses user details"| node_login_details
node_user_controller -->|"manages users"| node_user_service
node_user_controller -->|"manages roles"| node_role_service
node_user_controller -->|"assigns roles"| node_user_roles
node_user_service -->|"reads and writes"| node_persistence
node_user_service -->|"assigns role"| node_user_roles
node_user_service -->|"checks tenant"| node_tenant_policy
node_user_service -->|"records outcomes"| node_audit_service
node_user_roles -->|"reads and writes"| node_persistence
node_user_roles -->|"checks scope"| node_tenant_policy
node_user_roles -->|"records outcomes"| node_audit_service
node_role_service -->|"reads and writes"| node_persistence
node_role_service -->|"checks scope"| node_tenant_policy
node_role_service -->|"records outcomes"| node_audit_service
node_audit_service -->|"saves audit logs"| node_audit_repo
node_admin_controller -.->|"administers tenants"| node_superadmin_service

click node_home "https://github.com/raghul-r-0811/authorization-engine/blob/main/auth_engine/src/main/java/org/raghul/auth_engine/controller/Home_Controller.java"
click node_user_controller "https://github.com/raghul-r-0811/authorization-engine/blob/main/auth_engine/src/main/java/org/raghul/auth_engine/controller/UserController.java"
click node_admin_controller "https://github.com/raghul-r-0811/authorization-engine/blob/main/auth_engine/src/main/java/org/raghul/auth_engine/controller/SuperAdminController.java"
click node_user_service "https://github.com/raghul-r-0811/authorization-engine/blob/main/auth_engine/src/main/java/org/raghul/auth_engine/service/UserService.java"
click node_login_details "https://github.com/raghul-r-0811/authorization-engine/blob/main/auth_engine/src/main/java/org/raghul/auth_engine/security/CustomUserDetailService.java"
click node_jwt "https://github.com/raghul-r-0811/authorization-engine/blob/main/auth_engine/src/main/java/org/raghul/auth_engine/security/JwtService.java"
click node_jwt_filter "https://github.com/raghul-r-0811/authorization-engine/blob/main/auth_engine/src/main/java/org/raghul/auth_engine/security/JwtAuthFilter.java"
click node_security_config "https://github.com/raghul-r-0811/authorization-engine/blob/main/auth_engine/src/main/java/org/raghul/auth_engine/config/SecurityConfig.java"
click node_user_roles "https://github.com/raghul-r-0811/authorization-engine/blob/main/auth_engine/src/main/java/org/raghul/auth_engine/service/UserRoleService.java"
click node_role_service "https://github.com/raghul-r-0811/authorization-engine/blob/main/auth_engine/src/main/java/org/raghul/auth_engine/service/RoleService.java"
click node_tenant_policy "https://github.com/raghul-r-0811/authorization-engine/blob/main/auth_engine/src/main/java/org/raghul/auth_engine/service/TenantAccessPolicy.java"
click node_superadmin_service "https://github.com/raghul-r-0811/authorization-engine/blob/main/auth_engine/src/main/java/org/raghul/auth_engine/service/SuperAdminService.java"
click node_persistence "https://github.com/raghul-r-0811/authorization-engine/tree/main/auth_engine/src/main/java/org/raghul/auth_engine/repository"
click node_audit_service "https://github.com/raghul-r-0811/authorization-engine/blob/main/auth_engine/src/main/java/org/raghul/auth_engine/service/AuditLogService.java"
click node_audit_repo "https://github.com/raghul-r-0811/authorization-engine/blob/main/auth_engine/src/main/java/org/raghul/auth_engine/repository/AuditLogRepo.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_home,node_user_controller,node_admin_controller,node_client toneBlue
class node_user_service,node_login_details,node_jwt,node_jwt_filter,node_security_config toneAmber
class node_user_roles,node_role_service,node_tenant_policy,node_superadmin_service,node_persistence toneMint
class node_audit_service,node_audit_repo toneRose
class node_policy_eval,node_decision_voters,node_permission_cache toneIndigo
```

## Components

### API entry points

- [Auth endpoints](https://github.com/raghul-r-0811/authorization-engine/blob/main/auth_engine/src/main/java/org/raghul/auth_engine/controller/Home_Controller.java): `auth_engine/src/main/java/org/raghul/auth_engine/controller/Home_Controller.java`
- [User management API](https://github.com/raghul-r-0811/authorization-engine/blob/main/auth_engine/src/main/java/org/raghul/auth_engine/controller/UserController.java): `auth_engine/src/main/java/org/raghul/auth_engine/controller/UserController.java`
- [Super-admin API](https://github.com/raghul-r-0811/authorization-engine/blob/main/auth_engine/src/main/java/org/raghul/auth_engine/controller/SuperAdminController.java): `auth_engine/src/main/java/org/raghul/auth_engine/controller/SuperAdminController.java`

### Identity and tenants

- [User lifecycle](https://github.com/raghul-r-0811/authorization-engine/blob/main/auth_engine/src/main/java/org/raghul/auth_engine/service/UserService.java): `auth_engine/src/main/java/org/raghul/auth_engine/service/UserService.java`
- [User detail lookup](https://github.com/raghul-r-0811/authorization-engine/blob/main/auth_engine/src/main/java/org/raghul/auth_engine/security/CustomUserDetailService.java): `auth_engine/src/main/java/org/raghul/auth_engine/security/CustomUserDetailService.java`
- [JWT service](https://github.com/raghul-r-0811/authorization-engine/blob/main/auth_engine/src/main/java/org/raghul/auth_engine/security/JwtService.java): `auth_engine/src/main/java/org/raghul/auth_engine/security/JwtService.java`
- [JWT filter](https://github.com/raghul-r-0811/authorization-engine/blob/main/auth_engine/src/main/java/org/raghul/auth_engine/security/JwtAuthFilter.java): `auth_engine/src/main/java/org/raghul/auth_engine/security/JwtAuthFilter.java`
- [Security configuration](https://github.com/raghul-r-0811/authorization-engine/blob/main/auth_engine/src/main/java/org/raghul/auth_engine/config/SecurityConfig.java): `auth_engine/src/main/java/org/raghul/auth_engine/config/SecurityConfig.java`

### Roles and permissions

- [User-role assignment](https://github.com/raghul-r-0811/authorization-engine/blob/main/auth_engine/src/main/java/org/raghul/auth_engine/service/UserRoleService.java): `auth_engine/src/main/java/org/raghul/auth_engine/service/UserRoleService.java`
- [Role permissions](https://github.com/raghul-r-0811/authorization-engine/blob/main/auth_engine/src/main/java/org/raghul/auth_engine/service/RoleService.java): `auth_engine/src/main/java/org/raghul/auth_engine/service/RoleService.java`
- [Tenant access policy](https://github.com/raghul-r-0811/authorization-engine/blob/main/auth_engine/src/main/java/org/raghul/auth_engine/service/TenantAccessPolicy.java): `auth_engine/src/main/java/org/raghul/auth_engine/service/TenantAccessPolicy.java`
- [Tenant administration](https://github.com/raghul-r-0811/authorization-engine/blob/main/auth_engine/src/main/java/org/raghul/auth_engine/service/SuperAdminService.java): `auth_engine/src/main/java/org/raghul/auth_engine/service/SuperAdminService.java`
- [JPA repositories](https://github.com/raghul-r-0811/authorization-engine/tree/main/auth_engine/src/main/java/org/raghul/auth_engine/repository): `auth_engine/src/main/java/org/raghul/auth_engine/repository`

### Audit trail

- [Audit logging](https://github.com/raghul-r-0811/authorization-engine/blob/main/auth_engine/src/main/java/org/raghul/auth_engine/service/AuditLogService.java): `auth_engine/src/main/java/org/raghul/auth_engine/service/AuditLogService.java`
- [Audit log repository](https://github.com/raghul-r-0811/authorization-engine/blob/main/auth_engine/src/main/java/org/raghul/auth_engine/repository/AuditLogRepo.java): `auth_engine/src/main/java/org/raghul/auth_engine/repository/AuditLogRepo.java`

### Planned authorization

- **Policy evaluation**
- **Decision voters**
- **Permission caching**

### Other components

- **Backend client**

## Connections

- Backend client → Auth endpoints: submits auth (evidence: `auth_engine/src/main/java/org/raghul/auth_engine/controller/Home_Controller.java`)
- Backend client → User management API: manages users (evidence: `auth_engine/src/main/java/org/raghul/auth_engine/controller/UserController.java`)
- Auth endpoints → User lifecycle: registers users (evidence: `auth_engine/src/main/java/org/raghul/auth_engine/controller/Home_Controller.java`)
- Auth endpoints → JWT service: issues tokens (evidence: `auth_engine/src/main/java/org/raghul/auth_engine/controller/Home_Controller.java`)
- User detail lookup → JPA repositories: loads accounts (evidence: `auth_engine/src/main/java/org/raghul/auth_engine/security/CustomUserDetailService.java`)
- JWT service → User detail lookup: uses user details (evidence: `auth_engine/src/main/java/org/raghul/auth_engine/security/JwtService.java`)
- User management API → User lifecycle: manages users (evidence: `auth_engine/src/main/java/org/raghul/auth_engine/controller/UserController.java`)
- User management API → Role permissions: manages roles (evidence: `auth_engine/src/main/java/org/raghul/auth_engine/controller/UserController.java`)
- User management API → User-role assignment: assigns roles (evidence: `auth_engine/src/main/java/org/raghul/auth_engine/controller/UserController.java`)
- User lifecycle → JPA repositories: reads and writes (evidence: `auth_engine/src/main/java/org/raghul/auth_engine/service/UserService.java`)
- User lifecycle → User-role assignment: assigns role (evidence: `auth_engine/src/main/java/org/raghul/auth_engine/service/UserService.java`)
- User lifecycle → Tenant access policy: checks tenant (evidence: `auth_engine/src/main/java/org/raghul/auth_engine/service/UserService.java`)
- User lifecycle → Audit logging: records outcomes (evidence: `auth_engine/src/main/java/org/raghul/auth_engine/service/UserService.java`)
- User-role assignment → JPA repositories: reads and writes (evidence: `auth_engine/src/main/java/org/raghul/auth_engine/service/UserRoleService.java`)
- User-role assignment → Tenant access policy: checks scope (evidence: `auth_engine/src/main/java/org/raghul/auth_engine/service/UserRoleService.java`)
- User-role assignment → Audit logging: records outcomes (evidence: `auth_engine/src/main/java/org/raghul/auth_engine/service/UserRoleService.java`)
- Role permissions → JPA repositories: reads and writes (evidence: `auth_engine/src/main/java/org/raghul/auth_engine/service/RoleService.java`)
- Role permissions → Tenant access policy: checks scope (evidence: `auth_engine/src/main/java/org/raghul/auth_engine/service/RoleService.java`)
- Role permissions → Audit logging: records outcomes (evidence: `auth_engine/src/main/java/org/raghul/auth_engine/service/RoleService.java`)
- Audit logging → Audit log repository: saves audit logs (evidence: `auth_engine/src/main/java/org/raghul/auth_engine/service/AuditLogService.java`)
- Super-admin API → Tenant administration: administers tenants (evidence: `auth_engine/src/main/java/org/raghul/auth_engine/controller/SuperAdminController.java`)
