# apache/casbin architecture

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

- Interactive diagram: https://gitdiagram.com/apache/casbin
- Repository: https://github.com/apache/casbin

## Overview

1. **What this repository is**
   Apache Casbin is a Go authorization engine, not an application server. The core runtime accepts a request like `{subject, object, action}` plus a policy/model definition, then decides allow/deny. Most of the repo is the library itself; `examples/` and `*_test.go` files are there to validate and demonstrate supported access-control patterns.

2. **Core enforcement pipeline**
   The central flow is: load a **model** and **policy**, build an **enforcer**, then call `Enforce(...)`. The enforcer evaluates the request against the model’s matcher expression, consults policy records, and reduces matching policy effects into a final decision. The top-level entry points are in `enforcer*.go`, `frontend.go`, `management_api.go`, and `rbac_api*.go`.

3. **Model subsystem**
   The `model/` package represents Casbin’s PERM metamodel: request, policy, effect, matcher, assertions, and functions. It parses `.conf` model files, stores model sections, and provides the data structure the enforcer executes against. This is the configuration boundary that lets the same engine support ACL, RBAC, ABAC, RESTful, deny-override, and priority-based policies.

4. **Policy and effect evaluation**
   Policy rows are matched against the request and then reduced by an effect strategy. The `effector/` package contains the default policy-effect logic, while `detector/` handles conflict/priority-style decision behavior. These components are the policy decision boundary: they determine how multiple matching rules become a single allow/deny outcome.

5. **Matching and built-in operators**
   Request-policy comparisons are not limited to equality. The `util/` package contains built-in operators such as key matching, glob matching, IP matching, and other helper functions used inside matcher expressions. This is how Casbin supports REST-style path matching and ABAC-style attribute predicates without hardcoding the model.

6. **RBAC and role hierarchy**
   RBAC is isolated into `rbac/` and the role-manager APIs. The default role manager builds and queries role links, including hierarchical roles and domain-aware roles. This subsystem feeds the enforcer with role relationships so policies can say “admin can read” instead of enumerating every user.

7. **Persistence and adapters**
   Policy storage is abstracted behind `persist/`. Adapters load and save policy from external stores; file and string adapters are included, and the interfaces support filtered, batch, update, and contextual variants. This means policy storage is pluggable and the enforcer itself stays storage-agnostic.

8. **Caching, syncing, and distributed consistency**
   Several enforcer variants support operational concerns around scale and consistency: `enforcer_cached*.go` uses in-memory policy result caching, `enforcer_synced.go` and `persist/cache/` coordinate synchronized state, and `enforcer_distributed.go` plus watcher abstractions support multi-node policy propagation. The `persist/watcher*.go` code is the boundary for broadcasting policy changes to other instances.

9. **Transactions and conflict handling**
   The `transaction*.go` files add transactional policy mutation behavior, including buffered updates and commit/conflict handling. This layer matters when policy updates must be atomic or serialized relative to concurrent authorization changes. It sits above persistence and below the management API.

10. **Management APIs**
   `management_api.go` exposes the general-purpose policy administration surface: add/remove rules, load/save, query policy, and manipulate model state. `rbac_api.go` and `rbac_api_with_domains.go` are convenience layers specialized for role/user mapping. These APIs are the primary way applications mutate authorization state at runtime.

11. **Contexts, sync variants, and internal boundaries**
   Context-aware and synchronized variants (`enforcer_context.go`, `rbac_api_context.go`, `*_synced.go`) adapt the same core behavior for callers that need request-scoped data or thread-safe access patterns. The repo also includes `internal_api.go`, `ai_api.go`, and `frontend_old.go`, which indicate compatibility and layered API evolution rather than separate products.

12. **Configuration, errors, and logging**
   `config/` parses runtime settings, `constant/` holds shared constants, `errors/` defines domain-specific error types, and `log/` provides the logger abstraction. These packages are supporting infrastructure rather than decision logic, but they define the library’s runtime behavior and diagnostics surface.

13. **Examples and validation**
   The large `examples/` directory is effectively a catalog of supported authorization models and edge cases: ACL, RBAC, ABAC, domains/tenants, deny-override, priority, and custom matchers. The many `*_test.go` files exercise those modes and verify compatibility across enforcer variants, persistence modes, and role-manager behavior.

14. **Architecture in one sentence**
   Casbin’s architecture is a layered authorization engine: model parsing and matcher evaluation at the core, role management and effect reduction around it, and pluggable persistence/synchronization/transaction layers around that core for real-world deployment needs.

Main entry points: [`enforcer.go`](https://github.com/apache/casbin/blob/master/enforcer.go) (Enforcer), [`persist/adapter.go`](https://github.com/apache/casbin/blob/master/persist/adapter.go) (Persistence), [`frontend.go`](https://github.com/apache/casbin/blob/master/frontend.go) (Frontend API), [`management_api.go`](https://github.com/apache/casbin/blob/master/management_api.go) (Mgmt API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Core engine"]
  node_enforcer["Enforcer<br/>runtime core<br/>[enforcer.go]"]
  node_frontend["Frontend API<br/>public API<br/>[frontend.go]"]
  node_management["Mgmt API<br/>policy admin<br/>[management_api.go]"]
  node_rbacapi["RBAC API<br/>role admin<br/>[rbac_api.go]"]
  node_modelpkg["Model<br/>[model.go]"]
  node_matcher["Operators<br/>match helpers"]
end

subgraph group_policy["Policy logic"]
  node_effector["Effector<br/>effect reducer<br/>[effector.go]"]
  node_detector["Detector<br/>conflict logic<br/>[detector.go]"]
  node_rbac["RBAC core<br/>role graph<br/>[role_manager.go]"]
  node_rolemgr["Default role mgr<br/>hierarchy engine<br/>[role_manager.go]"]
end

subgraph group_storage["Persistence"]
  node_persist[("Persistence<br/>policy store<br/>[adapter.go]")]
  node_fileadp["File adapter<br/>policy adapter<br/>[adapter.go]"]
  node_stringadp["String adapter<br/>policy adapter<br/>[adapter.go]"]
  node_cache["Policy cache<br/>sync cache<br/>[cache.go]"]
  node_watcher["Watcher<br/>change broadcast<br/>[watcher.go]"]
  node_tx["Transactions<br/>policy mutation<br/>[transaction.go]"]
end

subgraph group_support["Support packages"]
  node_config["Config<br/>[config.go]"]
  node_logger["Logger<br/>diagnostics<br/>[logger.go]"]
  node_errors["Errors"]
end

node_frontend -->|"creates/uses"| node_enforcer
node_management -->|"loads/saves"| node_persist
node_rbacapi -->|"manages roles"| node_rbac
node_enforcer -->|"executes model"| node_modelpkg
node_enforcer -->|"reduces effects"| node_effector
node_enforcer -->|"resolves conflicts"| node_detector
node_enforcer -->|"consults roles"| node_rbac
node_rbac -->|"default impl"| node_rolemgr
node_modelpkg -->|"uses functions"| node_matcher
node_persist -->|"implements"| node_fileadp
node_persist -->|"implements"| node_stringadp
node_persist -->|"supports"| node_cache
node_persist -->|"broadcasts"| node_watcher
node_tx -->|"wraps"| node_persist
node_management -->|"mutates atomically"| node_tx
node_enforcer -->|"loads policy"| node_persist
node_enforcer -->|"cached variants"| node_cache
node_frontend -->|"reads settings"| node_config
node_frontend -->|"logs"| node_logger
node_management -->|"returns"| node_errors

click node_enforcer "https://github.com/apache/casbin/blob/master/enforcer.go"
click node_frontend "https://github.com/apache/casbin/blob/master/frontend.go"
click node_management "https://github.com/apache/casbin/blob/master/management_api.go"
click node_rbacapi "https://github.com/apache/casbin/blob/master/rbac_api.go"
click node_modelpkg "https://github.com/apache/casbin/blob/master/model/model.go"
click node_matcher "https://github.com/apache/casbin/blob/master/util/builtin_operators.go"
click node_effector "https://github.com/apache/casbin/blob/master/effector/effector.go"
click node_detector "https://github.com/apache/casbin/blob/master/detector/detector.go"
click node_rbac "https://github.com/apache/casbin/blob/master/rbac/role_manager.go"
click node_rolemgr "https://github.com/apache/casbin/blob/master/rbac/default-role-manager/role_manager.go"
click node_persist "https://github.com/apache/casbin/blob/master/persist/adapter.go"
click node_fileadp "https://github.com/apache/casbin/blob/master/persist/file-adapter/adapter.go"
click node_stringadp "https://github.com/apache/casbin/blob/master/persist/string-adapter/adapter.go"
click node_cache "https://github.com/apache/casbin/blob/master/persist/cache/cache.go"
click node_watcher "https://github.com/apache/casbin/blob/master/persist/watcher.go"
click node_tx "https://github.com/apache/casbin/blob/master/transaction.go"
click node_config "https://github.com/apache/casbin/blob/master/config/config.go"
click node_logger "https://github.com/apache/casbin/blob/master/log/logger.go"
click node_errors "https://github.com/apache/casbin/blob/master/errors/constraint_errors.go"

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_enforcer,node_frontend,node_management,node_rbacapi,node_modelpkg,node_matcher toneBlue
class node_effector,node_detector,node_rbac,node_rolemgr toneAmber
class node_persist,node_fileadp,node_stringadp,node_cache,node_watcher,node_tx toneMint
class node_config,node_logger,node_errors toneRose
```

## Components

### Core engine

Request evaluation, model execution, and enforcement APIs.

- [Enforcer](https://github.com/apache/casbin/blob/master/enforcer.go): runtime core · Main authorization runtime that evaluates requests against model and policy. · `enforcer.go`
- [Frontend API](https://github.com/apache/casbin/blob/master/frontend.go): public API · Top-level façade for application-facing enforcement and administration entry points. · `frontend.go`
- [Mgmt API](https://github.com/apache/casbin/blob/master/management_api.go): policy admin · Adds, removes, loads, saves, and queries policy and model state. · `management_api.go`
- [RBAC API](https://github.com/apache/casbin/blob/master/rbac_api.go): role admin · Convenience API for managing users, roles, and domain-aware mappings. · `rbac_api.go`
- [Model](https://github.com/apache/casbin/blob/master/model/model.go): PERM model · Parses and stores request, policy, effect, matcher, and function sections. · `model/model.go`
- [Operators](https://github.com/apache/casbin/blob/master/util/builtin_operators.go): match helpers · Built-in key, glob, IP, and other matcher functions used in expressions. · `util/builtin_operators.go`

### Policy logic

Effect reduction, conflict handling, and role hierarchy.

- [Effector](https://github.com/apache/casbin/blob/master/effector/effector.go): effect reducer · Combines matching policy outcomes into a final allow or deny decision. · `effector/effector.go`
- [Detector](https://github.com/apache/casbin/blob/master/detector/detector.go): conflict logic · Handles priority and indeterminate-style decision behavior. · `detector/detector.go`
- [RBAC core](https://github.com/apache/casbin/blob/master/rbac/role_manager.go): role graph · Role manager interfaces and hierarchy resolution for role links. · `rbac/role_manager.go`
- [Default role mgr](https://github.com/apache/casbin/blob/master/rbac/default-role-manager/role_manager.go): hierarchy engine · Default implementation that builds and queries role inheritance links. · `rbac/default-role-manager/role_manager.go`

### Persistence

Adapters, cache, watchers, and transaction support.

- [Persistence](https://github.com/apache/casbin/blob/master/persist/adapter.go): policy store · Adapter interfaces for loading and saving policy state. · `persist/adapter.go`
- [File adapter](https://github.com/apache/casbin/blob/master/persist/file-adapter/adapter.go): policy adapter · Built-in file-based adapter implementation. · `persist/file-adapter/adapter.go`
- [String adapter](https://github.com/apache/casbin/blob/master/persist/string-adapter/adapter.go): policy adapter · Built-in in-memory/string-based adapter implementation. · `persist/string-adapter/adapter.go`
- [Policy cache](https://github.com/apache/casbin/blob/master/persist/cache/cache.go): sync cache · Caches policy data and synchronized state for faster repeated access. · `persist/cache/cache.go`
- [Watcher](https://github.com/apache/casbin/blob/master/persist/watcher.go): change broadcast · Broadcasts policy changes to other enforcers or nodes. · `persist/watcher.go`
- [Transactions](https://github.com/apache/casbin/blob/master/transaction.go): policy mutation · Buffers updates and handles commit or conflict behavior for policy changes. · `transaction.go`

### Support packages

Configuration, logging, errors, and shared helpers.

- [Config](https://github.com/apache/casbin/blob/master/config/config.go): runtime config · Parses runtime settings and library configuration. · `config/config.go`
- [Logger](https://github.com/apache/casbin/blob/master/log/logger.go): diagnostics · Logging abstraction used by the library. · `log/logger.go`
- [Errors](https://github.com/apache/casbin/blob/master/errors/constraint_errors.go): domain errors · Typed error definitions for constraint and RBAC failures. · `errors/constraint_errors.go`

## Connections

- Frontend API → Enforcer: creates/uses · Application-facing entry points delegate to the core runtime.
- Mgmt API → Persistence: loads/saves · Policy administration uses persistence adapters to read and write state.
- RBAC API → RBAC core: manages roles · RBAC helpers manipulate role links and domain mappings.
- Enforcer → Model: executes model · The enforcer evaluates requests using the parsed PERM model.
- Enforcer → Effector: reduces effects · Matching policy results are collapsed into a final decision.
- Enforcer → Detector: resolves conflicts · Priority and indeterminate behavior is handled during enforcement.
- Enforcer → RBAC core: consults roles · Role relationships are used during matcher evaluation.
- RBAC core → Default role mgr: default impl · The default role manager provides hierarchy queries.
- Model → Operators: uses functions · Matcher expressions call built-in comparison and path helpers.
- Persistence → File adapter: implements · File-backed storage is one concrete adapter.
- Persistence → String adapter: implements · String/in-memory storage is another concrete adapter.
- Persistence → Policy cache: supports · Cached and synchronized policy state sits behind the persistence layer.
- Persistence → Watcher: broadcasts · Watchers propagate policy updates to other instances.
- Transactions → Persistence: wraps · Transactional policy mutation sits above persistence.
- Mgmt API → Transactions: mutates atomically · Policy admin operations can route through transactional handling.
- Enforcer → Persistence: loads policy · Core runtime depends on adapters to obtain policy data.
- Enforcer → Policy cache: cached variants · Cached enforcers reuse synchronized policy results.
- Frontend API → Config: reads settings · Library behavior can be influenced by runtime configuration.
- Frontend API → Logger: logs · Public APIs rely on the logging abstraction for diagnostics.
- Mgmt API → Errors: returns · Administration APIs surface typed domain errors.