# rolifycommunity/rolify architecture

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

- Interactive diagram: https://gitdiagram.com/rolifycommunity/rolify
- Repository: https://github.com/rolifycommunity/rolify

## Overview

##### Main components
- **Railtie (lib/rolify/railtie.rb)**
- Boots the gem in Rails, injects `rolify` and `resourcify` methods into models
- **Generators (lib/generators/…)**
- `rolify_generator`, `active_record` & `mongoid` generators create models, migrations, initializers
- **Core Engine (lib/rolify/…)**
- resource.rb (mixes in resource behaviour)
- role.rb (Role model logic)
- configure.rb (gem‐level configuration)
- dynamic.rb (dynamic method definitions)
- finders.rb (scoped queries: `.with_role`, `.find_roles`, etc.)
- matchers.rb (test matchers for RSpec)
- utils.rb (shared helper methods)
- version.rb
- **Adapters (lib/rolify/adapters/…)**
- ActiveRecord adapters: `resource_adapter.rb`, `role_adapter.rb`, `scopes.rb`
- Mongoid adapters: same structure under mongoid/
- Base adapter defines interface for persistence and query operations
- **Database (Postgres/MySQL for AR or MongoDB for Mongoid)**

##### Relationships and data flow
- **Rails App ➔ Railtie**
Rails initializes and loads the Railtie -> gem injects `rolify` into User and `resourcify` into resource classes
- **App Models (User, Forum, etc.)**
Calling `rolify` mixes in Core Engine + selects correct Adapter per ORM
Calling `resourcify` mixes in Resource behavior
- **Core Engine ➔ Adapters ➔ Database**
Role assignment (`user.add_role`) invokes Core Engine logic → Adapter writes to DB
Role queries (`user.has_role?`, `Forum.with_role`) invoke Finders → Adapter queries DB
- **Generators ➔ App File System**
Generates migration, model and initializer files before runtime

##### Architectural patterns & design principles
- **Plug-in Architecture**
- Uses Rails Railtie for automatic integration
- Exposes extension points via Generators
- **Adapter Pattern**
- Abstracts persistence behind a common interface for ActiveRecord vs. Mongoid
- **Mixin/Module Composition**
- Core behavior injected into host models via modules
- **Dynamic Method Definition**
- Uses `dynamic.rb` to define role methods on the fly

##### Detail level
- Configuration flow: “Application config ➔ configure.rb ➔ Core Engine”

- How the Rolify gem integrates into a Rails app
- The separation between its generation phase (Generators) and its runtime phase (Railtie → Core → Adapters)
- Its use of the Adapter pattern for multi-ORM support
- Data flows for role assignment and querying
- Extensibility points for future contributors or users

## Diagram (Mermaid)

```mermaid
flowchart TB
    RailsApp["Rails Application"]:::external
    Railtie["Railtie"]:::railtie

    RailsApp -->|"initializes Rails Railtie"| Railtie
    Railtie -->|"injects rolify/resourcify"| Resource
    Railtie --> CoreEngineLoad[/loads core modules/]:::coreEngine
    CoreEngineLoad --> Resource
    CoreEngineLoad --> Role
    CoreEngineLoad --> Configure
    CoreEngineLoad --> Dynamic
    CoreEngineLoad --> Finders
    CoreEngineLoad --> Matchers
    CoreEngineLoad --> Utils
    CoreEngineLoad --> Version

    subgraph "Generators"
        direction TB
        GenCommon["Rolify Generator"]:::generators
        GenAR["AR Rolify Generator"]:::generators
        GenMongo["Mongoid Rolify Generator"]:::generators
        GenUser["User Generator"]:::generators
        TmplAR["AR Templates"]:::generators
        TmplMongo["Mongoid Templates"]:::generators
        TmplCommon["Rolify Templates"]:::generators
    end

    RailsApp -->|"generates files"| GenCommon
    GenCommon --> GenAR
    GenCommon --> GenMongo
    GenCommon --> GenUser
    GenAR --> TmplAR
    GenMongo --> TmplMongo
    GenCommon --> TmplCommon

    subgraph "Core Engine\n(lib/rolify)"
        direction TB
        Resource["resource.rb"]:::coreEngine
        Role["role.rb"]:::coreEngine
        Configure["configure.rb"]:::coreEngine
        Dynamic["dynamic.rb"]:::coreEngine
        Finders["finders.rb"]:::coreEngine
        Matchers["matchers.rb"]:::coreEngine
        Utils["utils.rb"]:::coreEngine
        Version["version.rb"]:::coreEngine
    end

    subgraph "Adapters\n(lib/rolify/adapters)"
        direction TB
        BaseAdapter["base.rb"]:::adapters
        subgraph ActiveRecord
            ARResAdapter["resource_adapter.rb"]:::adapters
            ARRoleAdapter["role_adapter.rb"]:::adapters
            ARScopes["scopes.rb"]:::adapters
        end
        subgraph Mongoid
            MongoResAdapter["resource_adapter.rb"]:::adapters
            MongoRoleAdapter["role_adapter.rb"]:::adapters
            MongoScopes["scopes.rb"]:::adapters
        end
    end

    Resource -->|"selects adapter"| BaseAdapter
    Role --> BaseAdapter
    BaseAdapter --> ARResAdapter
    BaseAdapter --> ARRoleAdapter
    BaseAdapter --> ARScopes
    BaseAdapter --> MongoResAdapter
    BaseAdapter --> MongoRoleAdapter
    BaseAdapter --> MongoScopes

    subgraph Database
        direction TB
        Postgres["Postgres/MySQL"]:::database
        MongoDB["MongoDB"]:::database
    end

    ARResAdapter -->|"persists role"| Postgres
    ARRoleAdapter --> Postgres
    ARScopes -->|"queries roles"| Postgres
    MongoResAdapter -->|"persists role"| MongoDB
    MongoRoleAdapter --> MongoDB
    MongoScopes -->|"queries roles"| MongoDB

    Resource -->|"uses config"| Configure

    click Railtie "https://github.com/rolifycommunity/rolify/blob/master/lib/rolify/railtie.rb"
    click GenCommon "https://github.com/rolifycommunity/rolify/blob/master/lib/generators/rolify/rolify_generator.rb"
    click GenAR "https://github.com/rolifycommunity/rolify/blob/master/lib/generators/active_record/rolify_generator.rb"
    click GenMongo "https://github.com/rolifycommunity/rolify/blob/master/lib/generators/mongoid/rolify_generator.rb"
    click GenUser "https://github.com/rolifycommunity/rolify/blob/master/lib/generators/rolify/user_generator.rb"
    click TmplAR "https://github.com/rolifycommunity/rolify/tree/master/lib/generators/active_record/templates"
    click TmplMongo "https://github.com/rolifycommunity/rolify/tree/master/lib/generators/mongoid/templates"
    click TmplCommon "https://github.com/rolifycommunity/rolify/tree/master/lib/generators/rolify/templates"
    click Resource "https://github.com/rolifycommunity/rolify/blob/master/lib/rolify/resource.rb"
    click Role "https://github.com/rolifycommunity/rolify/blob/master/lib/rolify/role.rb"
    click Configure "https://github.com/rolifycommunity/rolify/blob/master/lib/rolify/configure.rb"
    click Dynamic "https://github.com/rolifycommunity/rolify/blob/master/lib/rolify/dynamic.rb"
    click Finders "https://github.com/rolifycommunity/rolify/blob/master/lib/rolify/finders.rb"
    click Matchers "https://github.com/rolifycommunity/rolify/blob/master/lib/rolify/matchers.rb"
    click Utils "https://github.com/rolifycommunity/rolify/blob/master/lib/rolify/utils.rb"
    click Version "https://github.com/rolifycommunity/rolify/blob/master/lib/rolify/version.rb"
    click BaseAdapter "https://github.com/rolifycommunity/rolify/blob/master/lib/rolify/adapters/base.rb"
    click ARResAdapter "https://github.com/rolifycommunity/rolify/blob/master/lib/rolify/adapters/active_record/resource_adapter.rb"
    click ARRoleAdapter "https://github.com/rolifycommunity/rolify/blob/master/lib/rolify/adapters/active_record/role_adapter.rb"
    click ARScopes "https://github.com/rolifycommunity/rolify/blob/master/lib/rolify/adapters/active_record/scopes.rb"
    click MongoResAdapter "https://github.com/rolifycommunity/rolify/blob/master/lib/rolify/adapters/mongoid/resource_adapter.rb"
    click MongoRoleAdapter "https://github.com/rolifycommunity/rolify/blob/master/lib/rolify/adapters/mongoid/role_adapter.rb"
    click MongoScopes "https://github.com/rolifycommunity/rolify/blob/master/lib/rolify/adapters/mongoid/scopes.rb"

    classDef coreEngine fill:#ADD8E6,stroke:#000
    classDef adapters fill:#98FB98,stroke:#000
    classDef generators fill:#FFA500,stroke:#000
    classDef railtie fill:#DDA0DD,stroke:#000
    classDef database fill:#F0E68C,stroke:#000
    classDef external fill:#CCCCCC,stroke:#000
```
