How jeffgreco13/filament-breezy works
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)