# jeffgreco13/filament-breezy architecture

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

- Interactive diagram: https://gitdiagram.com/jeffgreco13/filament-breezy
- Repository: https://github.com/jeffgreco13/filament-breezy

## Overview

##### Project Type and Purpose
- This is an open-source Laravel package (“Filament Breezy”) that extends Filament v3 panels with enhanced user-security features (profile pages, password updates, two-factor authentication, Sanctum tokens, browser session management, and password-confirmation actions).
- It is not a standalone front-end/back-end app, but a plugin that hooks into a host Laravel/Filament project.

##### Top-Level Components
- Host Application / Filament Panel (consumer)
- FilamentBreezyServiceProvider (package entry point)
- BreezyCore (fluently configures/enables plugin features)
- Commands (e.g., `Install` command to scaffold migrations/views)
- Database Migrations (stubs for two-factor columns, `breezy_sessions` table)
- Models & Traits
- `BreezySession` model (tracks user sessions)
- `TwoFactorAuthenticatable` trait (adds TFA behavior to User)
- Middleware
- `MustTwoFactor` (enforces TFA before accessing resources)
- Livewire Components & Pages
- BrowserSessions, MyProfileComponent, PersonalInfo, TwoFactorAuthentication, SanctumTokens, UpdatePassword
- Page classes (MyProfilePage, TwoFactorPage)
- Blade View Templates (resources/views and components)
- Actions & Events
- `PasswordButtonAction` (wraps sensitive actions in a password confirmation modal)
- `LoginSuccess` event (hook for post-login behavior)
- Facades
- `FilamentBreezy` (shortcut to core plugin methods)
- External Services
- Laravel Auth (guards, sessions)
- Laravel Sanctum (personal access tokens)
- Storage (for avatars)
- Database (users table, migrations)

##### Relationships & Data Flows
- Registration Phase (startup)
→ Filament Panel calls `plugin(BreezyCore::make())`
→ ServiceProvider merges config, registers routes, Livewire components, middleware, facades, and publishes views/migrations.
→ Artisan commands become available (`breezy:install`, `vendor:publish`).
- Request Handling
1. HTTP Request to Filament route (e.g., `/my-profile`)
2. Laravel router passes through `MustTwoFactor` middleware if TFA is enabled and forced
3. Filament invokes Livewire component (e.g., `MyProfileComponent`)
4. Component’s `mount()` and `render()` call repository/model code, trait methods, and fetch session data via `BreezySession` model
5. Actions (button clicks) dispatch Livewire events, use `PasswordButtonAction`, update User model or BreezySession, fire `LoginSuccess` event
6. Database is read/written (users, breezy_sessions)
7. Response (Blade view) rendered back to user
- CLI Flow
→ `php artisan breezy:install` scaffolds migrations and publishes views
→ Developer may publish or override views/components, register custom Livewire pages

##### Architectural Patterns & Design Principles
- Laravel Service Provider & Facade Pattern for plugin registration and API
- MVC + Livewire (server-driven UI components with Blade templates)
- Event-Driven (e.g., `LoginSuccess` for extensibility)
- Trait Composition (`TwoFactorAuthenticatable`) for injecting behavior into User model
- Command Pattern (`Install` command) for scaffolding
- Configuration by Convention (methods on `BreezyCore` fluently enable features)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Host Layer
    subgraph "Host Layer" 
        direction TB
        HTTPK["Laravel HTTP Kernel"]:::host
        FilamentPanel["Filament Panel (Consumer)"]:::host
        CLI["Artisan CLI"]:::host
    end

    %% Plugin Layer
    subgraph "Plugin Layer" 
        direction TB
        ServiceProvider["FilamentBreezyServiceProvider\n(Laravel Service Provider)"]:::core
        BreezyCore["BreezyCore\n(Core Plugin API)"]:::core
        Facade["FilamentBreezy Facade"]:::core
        Routes["routes/web.php"]:::core
    end

    %% Feature Modules
    subgraph "Feature Modules" 
        direction TB
        Commands["Install Command\n(Artisan Command)"]:::feature
        Middleware["MustTwoFactor Middleware"]:::feature
        subgraph "Livewire Components" 
            direction TB
            LW1["BrowserSessions"]:::feature
            LW2["MyProfileComponent"]:::feature
            LW3["PersonalInfo"]:::feature
            LW4["TwoFactorAuthentication"]:::feature
            LW5["SanctumTokens"]:::feature
            LW6["UpdatePassword"]:::feature
        end
        subgraph "Page Classes" 
            direction TB
            Page1["MyProfilePage"]:::feature
            Page2["TwoFactorPage"]:::feature
        end
        Traits["TwoFactorAuthenticatable Trait"]:::feature
        Actions["PasswordButtonAction"]:::feature
        Events["LoginSuccess Event"]:::feature
    end

    %% Persistence Layer
    subgraph "Persistence Layer" 
        direction TB
        subgraph "Models & Migrations"
            direction TB
            Model["BreezySession Model"]:::persistence
            M1["add_two_factor_columns_to_table.php.stub"]:::persistence
            M2["create_breezy_sessions_table.php.stub"]:::persistence
        end
        DB["Database (users, breezy_sessions)"]:::external
    end

    %% External Integrations
    subgraph "External Integrations" 
        direction TB
        Auth["Laravel Auth Guard"]:::external
        Sanctum["Laravel Sanctum"]:::external
        Storage["Storage (Avatars)"]:::external
    end

    %% Connections
    FilamentPanel -->|"calls plugin() with BreezyCore"| ServiceProvider
    ServiceProvider -->|"registers routes"| Routes
    ServiceProvider -->|"registers Livewire"| LW1
    ServiceProvider -->|"registers Livewire"| LW2
    ServiceProvider -->|"registers Livewire"| LW3
    ServiceProvider -->|"registers Livewire"| LW4
    ServiceProvider -->|"registers Livewire"| LW5
    ServiceProvider -->|"registers Livewire"| LW6
    ServiceProvider -->|"registers pages"| Page1
    ServiceProvider -->|"registers pages"| Page2
    ServiceProvider -->|"registers middleware"| Middleware
    ServiceProvider -->|"registers facade"| Facade
    ServiceProvider -->|"publishes views/migrations"| CLI

    %% CLI Flow
    CLI -->|"runs breezy:install"| Commands
    Commands -->|"scaffolds migrations"| M1
    Commands -->|"scaffolds migrations"| M2

    %% HTTP Request Flow
    HTTPK --> Auth
    HTTPK -->|"/my-profile"| Routes
    Routes --> Middleware
    Middleware --> LW2
    LW2 -->|mount/render| Model
    Model --> DB
    LW2 -->|dispatches actions| Actions
    Actions --> Events
    Events --> Model
    Model --> DB
    LW2 --> Storage

    %% External Services
    LW5 --> Sanctum
    LW2 --> Auth

    %% Configuration API
    FilamentPanel --> BreezyCore
    BreezyCore -->|"enableTwoFactorAuthentication()"| Middleware
    BreezyCore -->|"enableBrowserSessions()"| LW1
    BreezyCore -->|"enableSanctumTokens()"| LW5

    %% Click Events
    click ServiceProvider "https://github.com/jeffgreco13/filament-breezy/blob/2.x/src/FilamentBreezyServiceProvider.php"
    click BreezyCore "https://github.com/jeffgreco13/filament-breezy/blob/2.x/src/BreezyCore.php"
    click Commands "https://github.com/jeffgreco13/filament-breezy/blob/2.x/src/Commands/Install.php"
    click M1 "https://github.com/jeffgreco13/filament-breezy/blob/2.x/database/migrations/add_two_factor_columns_to_table.php.stub"
    click M2 "https://github.com/jeffgreco13/filament-breezy/blob/2.x/database/migrations/create_breezy_sessions_table.php.stub"
    click Model "https://github.com/jeffgreco13/filament-breezy/blob/2.x/src/Models/BreezySession.php"
    click Traits "https://github.com/jeffgreco13/filament-breezy/blob/2.x/src/Traits/TwoFactorAuthenticatable.php"
    click Middleware "https://github.com/jeffgreco13/filament-breezy/blob/2.x/src/Middleware/MustTwoFactor.php"
    click LW1 "https://github.com/jeffgreco13/filament-breezy/blob/2.x/src/Livewire/BrowserSessions.php"
    click LW2 "https://github.com/jeffgreco13/filament-breezy/blob/2.x/src/Livewire/MyProfileComponent.php"
    click LW3 "https://github.com/jeffgreco13/filament-breezy/blob/2.x/src/Livewire/PersonalInfo.php"
    click LW4 "https://github.com/jeffgreco13/filament-breezy/blob/2.x/src/Livewire/TwoFactorAuthentication.php"
    click LW5 "https://github.com/jeffgreco13/filament-breezy/blob/2.x/src/Livewire/SanctumTokens.php"
    click LW6 "https://github.com/jeffgreco13/filament-breezy/blob/2.x/src/Livewire/UpdatePassword.php"
    click Page1 "https://github.com/jeffgreco13/filament-breezy/blob/2.x/src/Pages/MyProfilePage.php"
    click Page2 "https://github.com/jeffgreco13/filament-breezy/blob/2.x/src/Pages/TwoFactorPage.php"
    click Actions "https://github.com/jeffgreco13/filament-breezy/blob/2.x/src/Actions/PasswordButtonAction.php"
    click Events "https://github.com/jeffgreco13/filament-breezy/blob/2.x/src/Events/LoginSuccess.php"
    click Facade "https://github.com/jeffgreco13/filament-breezy/blob/2.x/src/Facades/FilamentBreezy.php"
    click Routes "https://github.com/jeffgreco13/filament-breezy/blob/2.x/routes/web.php"

    %% Styles
    classDef host fill:#dddddd,stroke:#888,stroke-width:1px;
    classDef core fill:#aaccff,stroke:#3388cc,stroke-width:2px;
    classDef feature fill:#ccffcc,stroke:#33aa33,stroke-width:1px;
    classDef external fill:#ffcc99,stroke:#cc6633,stroke-width:1px;
    classDef persistence fill:#e0ccff,stroke:#8866cc,stroke-width:1px;
```
