# karosown/katool-security architecture

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

- Interactive diagram: https://gitdiagram.com/karosown/katool-security
- Repository: https://github.com/karosown/katool-security

## Overview

KaTool Security is a role- and permission-based authentication framework spanning a centralized auth-management service and adapters for in-process, Dubbo, Spring Cloud Gateway, and Zuul use. The main request path applies login and role/permission checks before allowing an application request; the auth center manages users, tokens, roles, sites, and endpoint rules. README documents these modes and capabilities; sampled source confirms portions of user and endpoint-rule management, while many runtime links below rely on the documented module responsibilities and names.

Main entry points: [`katool-security-auth/src/main/java/cn/katool/security/auth/KaToolSecurityAuthCenterApplication.java`](https://github.com/karosown/katool-security/blob/master/katool-security-auth/src/main/java/cn/katool/security/auth/KaToolSecurityAuthCenterApplication.java) (Authentication Center), [`katool-security-auth/src/main/resources/static/js`](https://github.com/karosown/katool-security/tree/master/katool-security-auth/src/main/resources/static/js) (Management UI), [`katool-security-interceptor/src/main/java/cn/katool/security/interceptor/AuthInterceptor.java`](https://github.com/karosown/katool-security/blob/master/katool-security-interceptor/src/main/java/cn/katool/security/interceptor/AuthInterceptor.java) (Auth Interceptor), [`katool-security-gateway-starter-parent/katool-security-gateway-spring-cloud-gateway-starter/src/main/java/cn/katool/security/starter/gateway/gateway/filter/KaAuthFilter.java`](https://github.com/karosown/katool-security/blob/master/katool-security-gateway-starter-parent/katool-security-gateway-spring-cloud-gateway-starter/src/main/java/cn/katool/security/starter/gateway/gateway/filter/KaAuthFilter.java) (Cloud Gateway Filter)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_enforcement["Request Enforcement"]
  node_authcheck["Auth Annotations<br/>[AuthCheck.java]"]
  node_interceptor["Auth Interceptor"]
  node_dubbo_filter["Dubbo Filter"]
  node_auth_logic["Auth Logic"]
  node_logic_container["Logic Container"]
end

subgraph group_integration["Framework Integration"]
  node_boot_starter["Boot Starter"]
  node_gateway_filter["Cloud Gateway Filter<br/>[KaAuthFilter.java]"]
  node_zuul_filter["Zuul Filter<br/>[KaAuthFilter.java]"]
  node_gateway_util["Gateway Auth Utility"]
  node_remote_api["Auth Service API<br/>[AuthService.java]"]
end

subgraph group_authcenter["Auth Center"]
  node_auth_center["Authentication Center"]
end

subgraph group_management["Administration"]
  node_user_api["User Management"]
  node_user_service["User Service"]
  node_auth_api["Endpoint Rules"]
  node_auth_service["Rule Service"]
  node_role_api["Role Management"]
  node_site_api["Site Settings"]
  node_token_api["Token Operations"]
  node_admin_ui["Management UI"]
end

subgraph group_state["State and Jobs"]
  node_database[("Relational Database")]
  node_redis[("Redis")]
  node_token_task["Token Cleanup<br/>[TokenTask.java]"]
  node_auth_sync["Rule Sync Task"]
end

node_requester(("Application Request"))
node_app["Protected Application"]
node_gateway["API Gateway"]
node_admin(("Administrator"))

node_requester -->|"submits request"| node_interceptor
node_interceptor -->|"evaluates annotations"| node_authcheck
node_interceptor -->|"checks access"| node_auth_logic
node_auth_logic -->|"dispatches logic"| node_logic_container
node_interceptor -->|"allows request"| node_app
node_requester -->|"sends request"| node_gateway_filter
node_gateway -->|"dispatches request"| node_gateway_filter
node_gateway -.->|"dispatches request"| node_zuul_filter
node_gateway_filter -->|"uses auth utility"| node_gateway_util
node_gateway_filter -->|"requests auth data"| node_remote_api
node_zuul_filter -.->|"requests auth data"| node_remote_api
node_remote_api -->|"remote calls"| node_auth_center
node_boot_starter -->|"configures checks"| node_interceptor
node_dubbo_filter -->|"checks provider calls"| node_auth_logic
node_auth_center -->|"serves user routes"| node_user_api
node_auth_center -->|"serves rule routes"| node_auth_api
node_auth_center -->|"serves role routes"| node_role_api
node_auth_center -->|"serves site routes"| node_site_api
node_auth_center -->|"serves token routes"| node_token_api
node_user_api -->|"manages users"| node_user_service
node_user_service -->|"reads and writes"| node_database
node_auth_api -->|"manages rules"| node_auth_service
node_auth_service -->|"reads and writes"| node_database
node_role_api -->|"manages role data"| node_database
node_site_api -->|"manages site data"| node_database
node_token_api -->|"manages tokens"| node_redis
node_token_task -->|"cleans expired tokens"| node_redis
node_auth_sync -->|"synchronizes rules"| node_remote_api
node_admin -->|"uses console"| node_admin_ui
node_admin_ui -->|"calls management API"| node_user_api
node_admin_ui -->|"calls management API"| node_auth_api
node_admin_ui -->|"calls management API"| node_role_api
node_admin_ui -->|"calls management API"| node_site_api
node_admin_ui -->|"calls management API"| node_token_api

click node_authcheck "https://github.com/karosown/katool-security/blob/master/katool-security-core/src/main/java/cn/katool/security/core/annotation/AuthCheck.java"
click node_interceptor "https://github.com/karosown/katool-security/blob/master/katool-security-interceptor/src/main/java/cn/katool/security/interceptor/AuthInterceptor.java"
click node_dubbo_filter "https://github.com/karosown/katool-security/blob/master/katool-security-interceptor/src/main/java/cn/katool/security/filter/DubboProviderAuthFilter.java"
click node_auth_logic "https://github.com/karosown/katool-security/blob/master/katool-security-interface/src/main/java/cn/katool/security/logic/KaSecurityAuthLogic.java"
click node_logic_container "https://github.com/karosown/katool-security/blob/master/katool-security-interface/src/main/java/cn/katool/security/logic/KaToolSecurityAuthLogicContainer.java"
click node_boot_starter "https://github.com/karosown/katool-security/blob/master/katool-security-spring-boot-starter/src/main/java/cn/katool/security/starter/KaSecurityIniter.java"
click node_gateway_filter "https://github.com/karosown/katool-security/blob/master/katool-security-gateway-starter-parent/katool-security-gateway-spring-cloud-gateway-starter/src/main/java/cn/katool/security/starter/gateway/gateway/filter/KaAuthFilter.java"
click node_zuul_filter "https://github.com/karosown/katool-security/blob/master/katool-security-gateway-starter-parent/katool-security-gateway-zuul-starter/src/main/java/cn/katool/security/starter/gateway/zuul/filter/KaAuthFilter.java"
click node_gateway_util "https://github.com/karosown/katool-security/blob/master/katool-security-gateway-starter-parent/katool-security-gateway-spring-cloud-gateway-starter/src/main/java/cn/katool/security/starter/utils/KaSecurityAuthUtil.java"
click node_remote_api "https://github.com/karosown/katool-security/blob/master/katool-security-interface/src/main/java/cn/katool/security/service/AuthService.java"
click node_auth_center "https://github.com/karosown/katool-security/blob/master/katool-security-auth/src/main/java/cn/katool/security/auth/KaToolSecurityAuthCenterApplication.java"
click node_user_api "https://github.com/karosown/katool-security/blob/master/katool-security-auth/src/main/java/cn/katool/security/auth/controller/KaSecurityUserController.java"
click node_user_service "https://github.com/karosown/katool-security/blob/master/katool-security-auth/src/main/java/cn/katool/security/auth/service/KaSecurityUserService.java"
click node_auth_api "https://github.com/karosown/katool-security/blob/master/katool-security-auth/src/main/java/cn/katool/security/auth/controller/KaSecurityAuthController.java"
click node_auth_service "https://github.com/karosown/katool-security/blob/master/katool-security-auth/src/main/java/cn/katool/security/auth/service/impl/AuthInnerServiceImpl.java"
click node_role_api "https://github.com/karosown/katool-security/blob/master/katool-security-auth/src/main/java/cn/katool/security/auth/controller/KaSecurityRoleController.java"
click node_site_api "https://github.com/karosown/katool-security/blob/master/katool-security-auth/src/main/java/cn/katool/security/auth/controller/KaSecuritySiteController.java"
click node_token_api "https://github.com/karosown/katool-security/blob/master/katool-security-auth/src/main/java/cn/katool/security/auth/controller/KaSecurityTokenController.java"
click node_admin_ui "https://github.com/karosown/katool-security/tree/master/katool-security-auth/src/main/resources/static/js"
click node_token_task "https://github.com/karosown/katool-security/blob/master/katool-security-task/src/main/java/cn/katool/security/task/TokenTask.java"
click node_auth_sync "https://github.com/karosown/katool-security/blob/master/katool-security-gateway-starter-parent/katool-security-gateway-core/src/main/java/cn/katool/security/starter/gateway/core/job/AuthListSyncTask.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_authcheck,node_interceptor,node_dubbo_filter,node_auth_logic,node_logic_container toneBlue
class node_boot_starter,node_gateway_filter,node_zuul_filter,node_gateway_util,node_remote_api toneAmber
class node_auth_center,node_requester,node_gateway toneMint
class node_user_api,node_user_service,node_auth_api,node_auth_service,node_role_api,node_site_api,node_token_api,node_admin_ui toneRose
class node_database,node_redis,node_token_task,node_auth_sync,node_app,node_admin toneIndigo
```

## Components

### Request Enforcement

- [Auth Annotations](https://github.com/karosown/katool-security/blob/master/katool-security-core/src/main/java/cn/katool/security/core/annotation/AuthCheck.java): `katool-security-core/src/main/java/cn/katool/security/core/annotation/AuthCheck.java`
- [Auth Interceptor](https://github.com/karosown/katool-security/blob/master/katool-security-interceptor/src/main/java/cn/katool/security/interceptor/AuthInterceptor.java): `katool-security-interceptor/src/main/java/cn/katool/security/interceptor/AuthInterceptor.java`
- [Dubbo Filter](https://github.com/karosown/katool-security/blob/master/katool-security-interceptor/src/main/java/cn/katool/security/filter/DubboProviderAuthFilter.java): `katool-security-interceptor/src/main/java/cn/katool/security/filter/DubboProviderAuthFilter.java`
- [Auth Logic](https://github.com/karosown/katool-security/blob/master/katool-security-interface/src/main/java/cn/katool/security/logic/KaSecurityAuthLogic.java): `katool-security-interface/src/main/java/cn/katool/security/logic/KaSecurityAuthLogic.java`
- [Logic Container](https://github.com/karosown/katool-security/blob/master/katool-security-interface/src/main/java/cn/katool/security/logic/KaToolSecurityAuthLogicContainer.java): `katool-security-interface/src/main/java/cn/katool/security/logic/KaToolSecurityAuthLogicContainer.java`

### Framework Integration

- [Boot Starter](https://github.com/karosown/katool-security/blob/master/katool-security-spring-boot-starter/src/main/java/cn/katool/security/starter/KaSecurityIniter.java): `katool-security-spring-boot-starter/src/main/java/cn/katool/security/starter/KaSecurityIniter.java`
- [Cloud Gateway Filter](https://github.com/karosown/katool-security/blob/master/katool-security-gateway-starter-parent/katool-security-gateway-spring-cloud-gateway-starter/src/main/java/cn/katool/security/starter/gateway/gateway/filter/KaAuthFilter.java): `katool-security-gateway-starter-parent/katool-security-gateway-spring-cloud-gateway-starter/src/main/java/cn/katool/security/starter/gateway/gateway/filter/KaAuthFilter.java`
- [Zuul Filter](https://github.com/karosown/katool-security/blob/master/katool-security-gateway-starter-parent/katool-security-gateway-zuul-starter/src/main/java/cn/katool/security/starter/gateway/zuul/filter/KaAuthFilter.java): `katool-security-gateway-starter-parent/katool-security-gateway-zuul-starter/src/main/java/cn/katool/security/starter/gateway/zuul/filter/KaAuthFilter.java`
- [Gateway Auth Utility](https://github.com/karosown/katool-security/blob/master/katool-security-gateway-starter-parent/katool-security-gateway-spring-cloud-gateway-starter/src/main/java/cn/katool/security/starter/utils/KaSecurityAuthUtil.java): `katool-security-gateway-starter-parent/katool-security-gateway-spring-cloud-gateway-starter/src/main/java/cn/katool/security/starter/utils/KaSecurityAuthUtil.java`
- [Auth Service API](https://github.com/karosown/katool-security/blob/master/katool-security-interface/src/main/java/cn/katool/security/service/AuthService.java): `katool-security-interface/src/main/java/cn/katool/security/service/AuthService.java`

### Auth Center

- [Authentication Center](https://github.com/karosown/katool-security/blob/master/katool-security-auth/src/main/java/cn/katool/security/auth/KaToolSecurityAuthCenterApplication.java): `katool-security-auth/src/main/java/cn/katool/security/auth/KaToolSecurityAuthCenterApplication.java`

### Administration

- [User Management](https://github.com/karosown/katool-security/blob/master/katool-security-auth/src/main/java/cn/katool/security/auth/controller/KaSecurityUserController.java): `katool-security-auth/src/main/java/cn/katool/security/auth/controller/KaSecurityUserController.java`
- [User Service](https://github.com/karosown/katool-security/blob/master/katool-security-auth/src/main/java/cn/katool/security/auth/service/KaSecurityUserService.java): `katool-security-auth/src/main/java/cn/katool/security/auth/service/KaSecurityUserService.java`
- [Endpoint Rules](https://github.com/karosown/katool-security/blob/master/katool-security-auth/src/main/java/cn/katool/security/auth/controller/KaSecurityAuthController.java): `katool-security-auth/src/main/java/cn/katool/security/auth/controller/KaSecurityAuthController.java`
- [Rule Service](https://github.com/karosown/katool-security/blob/master/katool-security-auth/src/main/java/cn/katool/security/auth/service/impl/AuthInnerServiceImpl.java): `katool-security-auth/src/main/java/cn/katool/security/auth/service/impl/AuthInnerServiceImpl.java`
- [Role Management](https://github.com/karosown/katool-security/blob/master/katool-security-auth/src/main/java/cn/katool/security/auth/controller/KaSecurityRoleController.java): `katool-security-auth/src/main/java/cn/katool/security/auth/controller/KaSecurityRoleController.java`
- [Site Settings](https://github.com/karosown/katool-security/blob/master/katool-security-auth/src/main/java/cn/katool/security/auth/controller/KaSecuritySiteController.java): `katool-security-auth/src/main/java/cn/katool/security/auth/controller/KaSecuritySiteController.java`
- [Token Operations](https://github.com/karosown/katool-security/blob/master/katool-security-auth/src/main/java/cn/katool/security/auth/controller/KaSecurityTokenController.java): `katool-security-auth/src/main/java/cn/katool/security/auth/controller/KaSecurityTokenController.java`
- [Management UI](https://github.com/karosown/katool-security/tree/master/katool-security-auth/src/main/resources/static/js): `katool-security-auth/src/main/resources/static/js`

### State and Jobs

- **Relational Database**
- **Redis**
- [Token Cleanup](https://github.com/karosown/katool-security/blob/master/katool-security-task/src/main/java/cn/katool/security/task/TokenTask.java): `katool-security-task/src/main/java/cn/katool/security/task/TokenTask.java`
- [Rule Sync Task](https://github.com/karosown/katool-security/blob/master/katool-security-gateway-starter-parent/katool-security-gateway-core/src/main/java/cn/katool/security/starter/gateway/core/job/AuthListSyncTask.java): `katool-security-gateway-starter-parent/katool-security-gateway-core/src/main/java/cn/katool/security/starter/gateway/core/job/AuthListSyncTask.java`

### Other components

- **Application Request**
- **Protected Application**
- **API Gateway**
- **Administrator**

## Connections

- Application Request → Auth Interceptor: submits request
- Auth Interceptor → Auth Annotations: evaluates annotations
- Auth Interceptor → Auth Logic: checks access
- Auth Logic → Logic Container: dispatches logic
- Auth Interceptor → Protected Application: allows request
- Application Request → Cloud Gateway Filter: sends request
- API Gateway → Cloud Gateway Filter: dispatches request
- API Gateway → Zuul Filter: dispatches request
- Cloud Gateway Filter → Gateway Auth Utility: uses auth utility
- Cloud Gateway Filter → Auth Service API: requests auth data
- Zuul Filter → Auth Service API: requests auth data
- Auth Service API → Authentication Center: remote calls
- Boot Starter → Auth Interceptor: configures checks
- Dubbo Filter → Auth Logic: checks provider calls
- Authentication Center → User Management: serves user routes
- Authentication Center → Endpoint Rules: serves rule routes
- Authentication Center → Role Management: serves role routes
- Authentication Center → Site Settings: serves site routes
- Authentication Center → Token Operations: serves token routes
- User Management → User Service: manages users
- User Service → Relational Database: reads and writes
- Endpoint Rules → Rule Service: manages rules
- Rule Service → Relational Database: reads and writes
- Role Management → Relational Database: manages role data
- Site Settings → Relational Database: manages site data
- Token Operations → Redis: manages tokens
- Token Cleanup → Redis: cleans expired tokens
- Rule Sync Task → Auth Service API: synchronizes rules
- Administrator → Management UI: uses console
- Management UI → User Management: calls management API
- Management UI → Endpoint Rules: calls management API
- Management UI → Role Management: calls management API
- Management UI → Site Settings: calls management API
- Management UI → Token Operations: calls management API