# 4nass/keycloak-access-requests architecture

> Architecture diagram of the GitHub repository 4nass/keycloak-access-requests, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/4nass/keycloak-access-requests
- Repository: https://github.com/4nass/keycloak-access-requests

## Overview

Keycloak Access Requests is a realm-scoped Keycloak extension for cataloguing requestable roles and groups, collecting access requests, approving or rejecting them, and provisioning approved access. The principal flow runs from the Account console or REST API through request services, with approval followed by synchronous provisioning; audit history and administration are additional capabilities. The graph includes the documented console and notification integrations, but source excerpts do not establish all runtime wiring, so uncertain connections are omitted or marked unverified.

Main entry points: [`src/main/java/ch/anass/keycloak/accessrequests/core/service/RequestService.java`](https://github.com/4nass/keycloak-access-requests/blob/main/src/main/java/ch/anass/keycloak/accessrequests/core/service/RequestService.java) (Request service), [`src/main/java/ch/anass/keycloak/accessrequests/spi/realm/resource`](https://github.com/4nass/keycloak-access-requests/tree/main/src/main/java/ch/anass/keycloak/accessrequests/spi/realm/resource) (Realm REST), [`src/main/java/ch/anass/keycloak/accessrequests/core/service/CatalogService.java`](https://github.com/4nass/keycloak-access-requests/blob/main/src/main/java/ch/anass/keycloak/accessrequests/core/service/CatalogService.java) (Catalog service), [`src/main/java/ch/anass/keycloak/accessrequests/core/port/AccessRequestRepository.java`](https://github.com/4nass/keycloak-access-requests/blob/main/src/main/java/ch/anass/keycloak/accessrequests/core/port/AccessRequestRepository.java) (Request repository)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Keycloak API"]
  node_realm_api["Realm REST"]
  node_catalog_handler["Catalog handler"]
  node_request_handler["Requester handler"]
  node_approval_handler["Approval handler"]
  node_notifications["Email notifications"]
end

subgraph group_core["Access workflow"]
  node_catalog_service["Catalog service"]
  node_request_service["Request service"]
  node_approval_queue["Approval queue"]
  node_request_model["Request state<br/>[AccessRequest.java]"]
  node_provisioning["Entitlement provisioning"]
end

subgraph group_storage["Persistence"]
  node_entitlements["Entitlement repository"]
  node_requests["Request repository"]
  node_jpa[("JPA persistence")]
end

subgraph group_account["Account console"]
  node_account_routes["Account flows<br/>[routes.tsx]"]
  node_account_api["Account API client"]
end

subgraph group_admin["Admin console"]
  node_admin_routes["Admin pages<br/>[routes.tsx]"]
  node_admin_api["Admin API client"]
end

node_requester(("Requester"))
node_approver(("Approver"))

node_requester -->|"uses"| node_account_routes
node_approver -->|"uses"| node_account_routes
node_requester -->|"calls"| node_realm_api
node_realm_api -.->|"routes"| node_catalog_handler
node_realm_api -.->|"routes"| node_request_handler
node_realm_api -.->|"routes"| node_approval_handler
node_catalog_handler -.->|"invokes"| node_catalog_service
node_request_handler -.->|"invokes"| node_request_service
node_approval_handler -.->|"invokes"| node_request_service
node_catalog_service -->|"queries"| node_entitlements
node_catalog_service -->|"checks pending"| node_requests
node_catalog_service -->|"checks access"| node_request_service
node_request_service -->|"persists requests"| node_requests
node_request_service -->|"loads entitlement"| node_entitlements
node_request_service -.->|"provisions access"| node_provisioning
node_request_service -->|"updates state"| node_request_model
node_approval_queue -->|"queries queue"| node_requests
node_requests -.->|"implemented by"| node_jpa
node_entitlements -.->|"implemented by"| node_jpa
node_account_routes -.->|"loads API client"| node_account_api
node_admin_routes -.->|"loads API client"| node_admin_api

click node_realm_api "https://github.com/4nass/keycloak-access-requests/tree/main/src/main/java/ch/anass/keycloak/accessrequests/spi/realm/resource"
click node_catalog_handler "https://github.com/4nass/keycloak-access-requests/blob/main/src/main/java/ch/anass/keycloak/accessrequests/spi/realm/resource/AccessRequestCatalogHandler.java"
click node_request_handler "https://github.com/4nass/keycloak-access-requests/blob/main/src/main/java/ch/anass/keycloak/accessrequests/spi/realm/resource/AccessRequestRequesterHandler.java"
click node_approval_handler "https://github.com/4nass/keycloak-access-requests/blob/main/src/main/java/ch/anass/keycloak/accessrequests/spi/realm/resource/AccessRequestApprovalHandler.java"
click node_catalog_service "https://github.com/4nass/keycloak-access-requests/blob/main/src/main/java/ch/anass/keycloak/accessrequests/core/service/CatalogService.java"
click node_request_service "https://github.com/4nass/keycloak-access-requests/blob/main/src/main/java/ch/anass/keycloak/accessrequests/core/service/RequestService.java"
click node_approval_queue "https://github.com/4nass/keycloak-access-requests/blob/main/src/main/java/ch/anass/keycloak/accessrequests/core/service/ApprovalQueueService.java"
click node_request_model "https://github.com/4nass/keycloak-access-requests/blob/main/src/main/java/ch/anass/keycloak/accessrequests/core/domain/request/AccessRequest.java"
click node_provisioning "https://github.com/4nass/keycloak-access-requests/blob/main/src/main/java/ch/anass/keycloak/accessrequests/core/port/EntitlementProvisioner.java"
click node_entitlements "https://github.com/4nass/keycloak-access-requests/blob/main/src/main/java/ch/anass/keycloak/accessrequests/core/port/EntitlementRepository.java"
click node_requests "https://github.com/4nass/keycloak-access-requests/blob/main/src/main/java/ch/anass/keycloak/accessrequests/core/port/AccessRequestRepository.java"
click node_jpa "https://github.com/4nass/keycloak-access-requests/tree/main/src/main/java/ch/anass/keycloak/accessrequests/persistence/jpa"
click node_account_routes "https://github.com/4nass/keycloak-access-requests/blob/main/themes/access-requests-ui/src/account/routes.tsx"
click node_account_api "https://github.com/4nass/keycloak-access-requests/blob/main/themes/access-requests-ui/src/account/api/AccessRequestsApi.ts"
click node_admin_routes "https://github.com/4nass/keycloak-access-requests/blob/main/themes/access-requests-ui/src/admin/routes.tsx"
click node_admin_api "https://github.com/4nass/keycloak-access-requests/blob/main/themes/access-requests-ui/src/admin/api/EntitlementsAdminApi.ts"
click node_notifications "https://github.com/4nass/keycloak-access-requests/tree/main/src/main/java/ch/anass/keycloak/accessrequests/spi/notification"

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_realm_api,node_catalog_handler,node_request_handler,node_approval_handler,node_notifications toneBlue
class node_catalog_service,node_request_service,node_approval_queue,node_request_model,node_provisioning toneAmber
class node_entitlements,node_requests,node_jpa,node_requester toneMint
class node_account_routes,node_account_api toneRose
class node_admin_routes,node_admin_api,node_approver toneIndigo
```

## Components

### Keycloak API

- [Realm REST](https://github.com/4nass/keycloak-access-requests/tree/main/src/main/java/ch/anass/keycloak/accessrequests/spi/realm/resource): `src/main/java/ch/anass/keycloak/accessrequests/spi/realm/resource`
- [Catalog handler](https://github.com/4nass/keycloak-access-requests/blob/main/src/main/java/ch/anass/keycloak/accessrequests/spi/realm/resource/AccessRequestCatalogHandler.java): `src/main/java/ch/anass/keycloak/accessrequests/spi/realm/resource/AccessRequestCatalogHandler.java`
- [Requester handler](https://github.com/4nass/keycloak-access-requests/blob/main/src/main/java/ch/anass/keycloak/accessrequests/spi/realm/resource/AccessRequestRequesterHandler.java): `src/main/java/ch/anass/keycloak/accessrequests/spi/realm/resource/AccessRequestRequesterHandler.java`
- [Approval handler](https://github.com/4nass/keycloak-access-requests/blob/main/src/main/java/ch/anass/keycloak/accessrequests/spi/realm/resource/AccessRequestApprovalHandler.java): `src/main/java/ch/anass/keycloak/accessrequests/spi/realm/resource/AccessRequestApprovalHandler.java`
- [Email notifications](https://github.com/4nass/keycloak-access-requests/tree/main/src/main/java/ch/anass/keycloak/accessrequests/spi/notification): `src/main/java/ch/anass/keycloak/accessrequests/spi/notification`

### Access workflow

- [Catalog service](https://github.com/4nass/keycloak-access-requests/blob/main/src/main/java/ch/anass/keycloak/accessrequests/core/service/CatalogService.java): `src/main/java/ch/anass/keycloak/accessrequests/core/service/CatalogService.java`
- [Request service](https://github.com/4nass/keycloak-access-requests/blob/main/src/main/java/ch/anass/keycloak/accessrequests/core/service/RequestService.java): `src/main/java/ch/anass/keycloak/accessrequests/core/service/RequestService.java`
- [Approval queue](https://github.com/4nass/keycloak-access-requests/blob/main/src/main/java/ch/anass/keycloak/accessrequests/core/service/ApprovalQueueService.java): `src/main/java/ch/anass/keycloak/accessrequests/core/service/ApprovalQueueService.java`
- [Request state](https://github.com/4nass/keycloak-access-requests/blob/main/src/main/java/ch/anass/keycloak/accessrequests/core/domain/request/AccessRequest.java): `src/main/java/ch/anass/keycloak/accessrequests/core/domain/request/AccessRequest.java`
- [Entitlement provisioning](https://github.com/4nass/keycloak-access-requests/blob/main/src/main/java/ch/anass/keycloak/accessrequests/core/port/EntitlementProvisioner.java): `src/main/java/ch/anass/keycloak/accessrequests/core/port/EntitlementProvisioner.java`

### Persistence

- [Entitlement repository](https://github.com/4nass/keycloak-access-requests/blob/main/src/main/java/ch/anass/keycloak/accessrequests/core/port/EntitlementRepository.java): `src/main/java/ch/anass/keycloak/accessrequests/core/port/EntitlementRepository.java`
- [Request repository](https://github.com/4nass/keycloak-access-requests/blob/main/src/main/java/ch/anass/keycloak/accessrequests/core/port/AccessRequestRepository.java): `src/main/java/ch/anass/keycloak/accessrequests/core/port/AccessRequestRepository.java`
- [JPA persistence](https://github.com/4nass/keycloak-access-requests/tree/main/src/main/java/ch/anass/keycloak/accessrequests/persistence/jpa): `src/main/java/ch/anass/keycloak/accessrequests/persistence/jpa`

### Account console

- [Account flows](https://github.com/4nass/keycloak-access-requests/blob/main/themes/access-requests-ui/src/account/routes.tsx): `themes/access-requests-ui/src/account/routes.tsx`
- [Account API client](https://github.com/4nass/keycloak-access-requests/blob/main/themes/access-requests-ui/src/account/api/AccessRequestsApi.ts): `themes/access-requests-ui/src/account/api/AccessRequestsApi.ts`

### Admin console

- [Admin pages](https://github.com/4nass/keycloak-access-requests/blob/main/themes/access-requests-ui/src/admin/routes.tsx): `themes/access-requests-ui/src/admin/routes.tsx`
- [Admin API client](https://github.com/4nass/keycloak-access-requests/blob/main/themes/access-requests-ui/src/admin/api/EntitlementsAdminApi.ts): `themes/access-requests-ui/src/admin/api/EntitlementsAdminApi.ts`

### Other components

- **Requester**
- **Approver**

## Connections

- Requester → Account flows: uses (evidence: `README.md`)
- Approver → Account flows: uses (evidence: `README.md`)
- Requester → Realm REST: calls (evidence: `README.md`)
- Realm REST → Catalog handler: routes (evidence: `src/main/java/ch/anass/keycloak/accessrequests/spi/realm/resource/AccessRequestCatalogHandler.java`)
- Realm REST → Requester handler: routes
- Realm REST → Approval handler: routes
- Catalog handler → Catalog service: invokes
- Requester handler → Request service: invokes
- Approval handler → Request service: invokes
- Catalog service → Entitlement repository: queries (evidence: `src/main/java/ch/anass/keycloak/accessrequests/core/service/CatalogService.java`)
- Catalog service → Request repository: checks pending (evidence: `src/main/java/ch/anass/keycloak/accessrequests/core/service/CatalogService.java`)
- Catalog service → Request service: checks access (evidence: `src/main/java/ch/anass/keycloak/accessrequests/core/service/CatalogService.java`)
- Request service → Request repository: persists requests (evidence: `src/main/java/ch/anass/keycloak/accessrequests/core/service/RequestService.java`)
- Request service → Entitlement repository: loads entitlement (evidence: `src/main/java/ch/anass/keycloak/accessrequests/core/service/RequestService.java`)
- Request service → Entitlement provisioning: provisions access (evidence: `src/main/java/ch/anass/keycloak/accessrequests/core/service/RequestService.java`)
- Request service → Request state: updates state (evidence: `src/main/java/ch/anass/keycloak/accessrequests/core/service/RequestService.java`)
- Approval queue → Request repository: queries queue (evidence: `src/main/java/ch/anass/keycloak/accessrequests/core/service/ApprovalQueueService.java`)
- Request repository → JPA persistence: implemented by (evidence: `src/main/java/ch/anass/keycloak/accessrequests/persistence/jpa/repository/JpaAccessRequestRepository.java`)
- Entitlement repository → JPA persistence: implemented by
- Account flows → Account API client: loads API client
- Admin pages → Admin API client: loads API client
