# be9/acl9 architecture

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

- Interactive diagram: https://gitdiagram.com/be9/acl9
- Repository: https://github.com/be9/acl9

## Overview

##### Project type and purpose
- This is an open-source RubyGem that integrates into Rails applications to provide a role-based authorization DSL.
- Its purpose is to let Rails controllers declare access-control rules in a clear, testable DSL and to manage role assignments on subjects (e.g., users) and objects (e.g., models).

##### File structure
- Top‐level:
- gemspec, Gemfile, bin/ (CLI shims), Rakefile, Appraisals (matrix testing), .github/workflows
- lib/acl9 – core implementation: controller and model extensions, helpers, prepositions, version
- lib/generators/acl9/setup – Rails generator code and templates to scaffold migrations & models
- test/ – unit tests for controller_extensions and model_extensions, plus a "dummy" Rails app under test/dummy demonstrating integration
- Patterns and conventions:
- Uses Rails “concern”-style mixins for extending ActionController (ControllerExtensions) and ActiveRecord models (ModelExtensions)
- Provides a DSL builder (dsl_base.rb) for access_control blocks
- Offers configuration via Acl9.config with default_* settings
- Follows MVC extension pattern—no standalone services or microservices

##### Key insights from the README
- Two subsystems:
a. Access Control Subsystem (controller DSL: allow/deny, actions, conditions)
b. Role Subsystem (user.has_role!, has_no_role!, join tables for roles & role_objects)
- Provides a Rails generator (acl9:setup) to create migrations and models
- Configurable defaults for class names, association names, subject methods, global-role protection, name normalization

- Rails App (host)
- Acl9 Gem
– ControllerExtensions (DSL parser & before_action filter)
– ModelExtensions (has_role? / has_role! on subject & object)
– Helpers (view‐level methods)
– Prepositions (DSL support)
– Configuration module (Acl9.config)
– Generators (acl9:setup → migrations + scaffolding)
- ActiveRecord Models
– Role
– RoleObject (join model)
– Subject model (e.g. User)
– Object models (e.g. School, Department)
- Database (tables: roles, role_objects, plus application tables)
- Test Dummy App (example integration and functional tests)
1. HTTP Request → Rails router → Controller (extended by ControllerExtensions)
2. ControllerExtensions runs access_control rules → invokes ModelExtensions on current_user (subject)
3. has_role? queries Role & RoleObject tables via ActiveRecord
4. Decision (allow/deny) → Controller action or access denied response
5. Generators (dev‐time): CLI Thor tasks → templates → create migration & model files in host app
6. Configuration flows: initializers → Acl9.config → affects runtime behavior
7. Tests: dummy app bootstraps Rails + Acl9 to validate behavior end-to-end
c. Architectural patterns and principles:
- Plugin/extension pattern: injects behavior via mixins into Rails MVC layers
- DSL Builder pattern for declarative access_control rules
- Convention over configuration: sensible defaults, overridable via config or model/controller macros
- Modular subsystems (Access Control vs Role Management)
d. Key technologies and libraries:
- Ruby, Bundler
- Rails (ActiveSupport, ActiveRecord, ActionController)
- Thor (for generators)
- Rake (tasks and test runner)
- Appraisals (multi‐Rails version testing)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Host Rails App
    subgraph "Host Rails App" 
        direction TB
        Router["Rails Router"]:::host
        Controller["ApplicationController"]:::host
        Models["ActiveRecord Models\n(User, School, Department)"]:::host
    end

    %% Acl9 Gem Core Modules
    subgraph "Acl9 Gem" 
        direction TB
        CE["ControllerExtensions\n(parses access_control)"]:::gemcore
        DSL["DSL Base"]:::gemcore
        ME["ModelExtensions\n(role methods)"]:::gemcore
        MS["ModelExtensions for_subject"]:::gemcore
        MO["ModelExtensions for_object"]:::gemcore
        Helpers["Helpers Module"]:::gemcore
        Prepositions["Prepositions Support"]:::gemcore
        Config["Configuration Module"]:::gemcore
        Version["Version Definition"]:::gemcore
    end

    %% CLI & Generators
    subgraph "CLI & Generators" 
        direction TB
        Bin["CLI Scripts (thor)"]:::cli
        Generators["Setup Generator"]:::cli
        Templates["Generator Templates"]:::cli
        Gemspec["Gem Specification"]:::cli
        Rake["Rake Tasks"]:::cli
    end

    %% Database
    subgraph "Database" 
        direction TB
        Roles["roles table"]:::db
        RoleObjects["role_objects table"]:::db
        AppTables["Application Tables"]:::db
    end

    %% Tests & CI
    subgraph "Testing & CI"
        direction TB
        TestCE["ControllerExtensions Tests"]:::tests
        TestME["ModelExtensions Tests"]:::tests
        Dummy["Dummy Rails App"]:::tests
        Appraisals["Appraisals Matrix"]:::tests
        CI["CI Workflow"]:::tests
    end

    %% Runtime Flow
    Router -->|"dispatches request"| Controller
    Controller -->|"before_action access_control"| CE
    CE -->|"uses DSL"| DSL
    CE -->|"invokes has_role?"| ME
    ME --> MS
    ME --> MO
    ME -->|"queries"| Roles
    ME -->|"queries"| RoleObjects
    Roles -->|"data"| AppTables
    RoleObjects --> AppTables
    ME -->|"decision allow/deny"| Controller
    Controller -->|"response"| Router

    %% Dev-time Flow
    Bin -->|"rails g acl9:setup"| Generators
    Generators --> Templates
    Gemspec --> Bin
    Rake --> Appraisals

    %% Configuration Flow
    initial["Initializer"]:::host -->|"sets up"| Config
    Config --> CE
    Config --> ME

    %% Testing Flow
    Dummy -->|"bootstraps Rails+Acl9"| CE
    Dummy --> ME
    Appraisals --> Dummy
    CI --> Appraisals
    CI --> TestCE
    CI --> TestME

    %% Click Events
    click CE "https://github.com/be9/acl9/blob/master/lib/acl9/controller_extensions.rb"
    click DSL "https://github.com/be9/acl9/blob/master/lib/acl9/controller_extensions/dsl_base.rb"
    click ME "https://github.com/be9/acl9/blob/master/lib/acl9/model_extensions.rb"
    click MS "https://github.com/be9/acl9/blob/master/lib/acl9/model_extensions/for_subject.rb"
    click MO "https://github.com/be9/acl9/blob/master/lib/acl9/model_extensions/for_object.rb"
    click Helpers "https://github.com/be9/acl9/blob/master/lib/acl9/helpers.rb"
    click Prepositions "https://github.com/be9/acl9/blob/master/lib/acl9/prepositions.rb"
    click Config "https://github.com/be9/acl9/blob/master/lib/acl9.rb"
    click Version "https://github.com/be9/acl9/blob/master/lib/acl9/version.rb"
    click Generators "https://github.com/be9/acl9/blob/master/lib/generators/acl9/setup/setup_generator.rb"
    click Templates "https://github.com/be9/acl9/tree/master/lib/generators/acl9/setup/templates/"
    click Gemspec "https://github.com/be9/acl9/blob/master/acl9.gemspec"
    click Bin "https://github.com/be9/acl9/tree/master/bin/thor"
    click Rake "https://github.com/be9/acl9/tree/master/Rakefile"
    click TestCE "https://github.com/be9/acl9/tree/master/test/controller_extensions/"
    click TestME "https://github.com/be9/acl9/tree/master/test/models/"
    click Dummy "https://github.com/be9/acl9/tree/master/test/dummy/"
    click Appraisals "https://github.com/be9/acl9/tree/master/Appraisals/"
    click CI "https://github.com/be9/acl9/blob/master/.github/workflows/acl9.yml"

    %% Styles
    classDef gemcore fill:#eeeeee,stroke:#333,stroke-width:1px
    classDef host fill:#a0c4ff,stroke:#333,stroke-width:1px
    classDef db fill:#caffbf,stroke:#333,stroke-width:1px
    classDef cli fill:#ffadad,stroke:#333,stroke-width:1px
    classDef tests fill:#ffd6a5,stroke:#333,stroke-width:1px
```
