# josephsilber/bouncer architecture

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

- Interactive diagram: https://gitdiagram.com/josephsilber/bouncer
- Repository: https://github.com/josephsilber/bouncer

## Overview

##### Project Type and Purpose
- Bouncer is an open-source library focused on managing roles and abilities using Eloquent. It enables developers to grant, revoke, and check permissions in both Laravel and non-Laravel environments.
- The README clearly explains how to install it, configure multi-tenancy, use its cache features, and integrate via a facade, service provider, and middleware. This indicates that its primary purpose is to act as a centralized authorization service.

##### File Structure
- Top-Level Folders:
- src: Contains the core classes (Bouncer, BaseClipboard, CachedClipboard, Helpers, custom service provider, console commands, and the “Conductors” which are responsible for various role/ability operations).
- migrations: Contains migration scripts and raw SQL for setting up the necessary database tables.
- middleware: Contains the ScopeBouncer middleware supporting multi-tenancy.
- tests: A comprehensive set of tests that validate the behavior of all aspects (ability, roles, ownership, multi-tenancy, etc.).
- workbench: Example application integration (models and migrations) showing real-world usage.
- Within the src directory, note the segregated concerns:
- Core functionalities: Bouncer, BouncerFacade, and BouncerServiceProvider.
- Conductors: These classes (like AssignsRoles, ChecksRoles, etc.) encapsulate the business logic for role and ability assignment, removal, syncing, and other permissions management.
- Database models and related helper classes under src/Database that wrap the Eloquent models (Ability and Role) and their relationships.
- Contracts: Interfaces ensuring that custom models and scoping behaviors can be maintained and extended.
- Additional components (Constraints, Console commands, Helpers) indicate a design that emphasizes modularity and ease of extension.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Integration Layer
    subgraph "Integration Layer"
        A1("Host Application Integration"):::integration
        A2("Bouncer Facade"):::integration
        A3("Service Provider"):::integration
        A4("Scope Middleware"):::integration
    end

    %% Business Logic Layer
    subgraph "Business Logic"
        B1("Core Bouncer"):::business
        B2("Conductors (Role/Ability Ops)"):::business
        B3("Cache Management"):::business
        B4("Constraints & Query Builders"):::business
    end

    %% Data Persistence Layer
    subgraph "Data Persistence"
        C1("Database Models (Ability/Role)"):::data
        C2("Migrations"):::data
    end

    %% Auxiliary Components
    subgraph "Auxiliary Components"
        D1("Console Commands"):::auxiliary
        D2("Helper Functions"):::auxiliary
    end

    %% Connections between Integration Layer and Business Logic
    A1 -->|"calls"| A2
    A3 -->|"initializes"| A2
    A3 -->|"injects"| B1
    A2 -->|"delegates"| B1
    A4 -->|"sets_tenant_context"| B1

    %% Connections within Business Logic and to Data Persistence
    B1 -->|"delegates"| B2
    B1 -->|"uses"| B3
    B1 -->|"utilizes"| D2
    B2 -->|"persists_data"| C1
    B2 -->|"applies_constraints"| B4
    B4 -->|"builds_queries"| C1

    %% Data Persistence setup
    C2 -->|"sets_up"| C1

    %% Auxiliary operations
    D1 -->|"cleans"| C1

    %% Click Events for Integration Layer
    click A1 "https://github.com/josephsilber/bouncer/tree/master/workbench/app/Models"
    click A2 "https://github.com/josephsilber/bouncer/blob/master/src/BouncerFacade.php"
    click A3 "https://github.com/josephsilber/bouncer/blob/master/src/BouncerServiceProvider.php"
    click A4 "https://github.com/josephsilber/bouncer/blob/master/middleware/ScopeBouncer.php"

    %% Click Events for Business Logic Layer
    click B1 "https://github.com/josephsilber/bouncer/blob/master/src/Bouncer.php"
    click B2 "https://github.com/josephsilber/bouncer/tree/master/src/Conductors"
    click B3 "https://github.com/josephsilber/bouncer/blob/master/src/CachedClipboard.php"
    click B4 "https://github.com/josephsilber/bouncer/tree/master/src/Constraints"
    click B4 "https://github.com/josephsilber/bouncer/tree/master/src/Database/Queries"

    %% Click Events for Data Persistence Layer
    click C1 "https://github.com/josephsilber/bouncer/blob/master/src/Database/Ability.php"
    click C1 "https://github.com/josephsilber/bouncer/blob/master/src/Database/Role.php"
    click C2 "https://github.com/josephsilber/bouncer/tree/master/migrations"

    %% Click Events for Auxiliary Components
    click D1 "https://github.com/josephsilber/bouncer/blob/master/src/Console/CleanCommand.php"
    click D2 "https://github.com/josephsilber/bouncer/blob/master/src/Helpers.php"

    %% Styling for nodes
    classDef integration fill:#AEDFF7,stroke:#333,stroke-width:2px;
    classDef business fill:#C8E6C9,stroke:#333,stroke-width:2px;
    classDef data fill:#FFF9C4,stroke:#333,stroke-width:2px;
    classDef auxiliary fill:#FADBD8,stroke:#333,stroke-width:2px;
```
