# afsakar/filament-otp-login architecture

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

- Interactive diagram: https://gitdiagram.com/afsakar/filament-otp-login
- Repository: https://github.com/afsakar/filament-otp-login

## Overview

##### Project Type and Purpose
- Type: A Laravel-based, open-source FilamentPHP plugin (package).
- Purpose: Replace Filament’s standard username/password login with a One-Time-Password flow—generate, store, send, verify OTP codes.

##### File Structure
Top-level:
- composer.json / package.json / package tooling (PSR, PHPStan, Pint, PostCSS/Tailwind)
- config/filament-otp-login.php (package config)
- database/migrations/… (migration stub for otp_codes table)
- resources/lang/{en, tr} (translations)
- resources/views (Blade templates for login page & OTP input)
- src/
– FilamentOtpLoginPlugin.php (plugin entry point)
– FilamentOtpLoginServiceProvider.php (Laravel service provider)
– Filament/Forms/OtpInput.php (Form component)
– Filament/Pages/Login.php (OTP-based login page)
– Models/OtpCode.php (Eloquent model) & Contracts/CanLoginDirectly.php
– Notifications/SendOtpCode.php (Laravel Notification)
– Commands/PruneOtpCodes.php (Artisan command to prune old codes)
– Testing/TestsFilamentOtpLogin.php (package tests)
- tests/ (unit and architecture tests)

##### Extract Additional Insights from README
- Installation: vendor:publish migrations, config, translations, views
- Configurable code length and expiry
- Uses Laravel Notifications (email/SMS channel)
- Cron-driven pruning recommended for production
- Extensible: implement CanLoginDirectly or override login page

##### Main Components & Their Interactions
A. Laravel Host Application
B. Filament Admin Panel
C. FilamentOtpLoginPlugin
– Registers ServiceProvider hooks
– Publishes migration, config, translations, views
– Binds custom login page and form component
– Hooks into Filament’s auth flow
D. OTPCode Model & Database Table (“otp_codes”)
E. Notification Subsystem
– SendOtpCode notification (email/SMS via Laravel Notification channels)
F. Artisan Command (PruneOtpCodes)
– Scheduled via cron to delete expired codes
G. Config & Localization (config file + lang folders)
H. Frontend Assets (Blade views, TailwindCSS, Alpine.js for OTP input)

Interactions (flow):
1. User → Filament login URL
2. Filament → Plugin → overrides default login page → shows OTP‐Input view
3. User enters email/username → submits form
4. Plugin generates OTP (random of configured length, expiration) → saves to otp_codes table
5. Plugin triggers SendOtpCode notification → Laravel Notification → Email/SMS Gateway
6. User receives OTP → enters code → Plugin verifies against OTPCode model (expires check)
7. On success: plugin calls Filament’s auth guard → issues session / JWT → user logged in
8. Cron job: PruneOtpCodes command → purges expired codes

##### Architectural Patterns & Design Principles
- Plugin Pattern: encapsulates all OTP logic behind a Filament plugin interface
- MVC:
– Models: OtpCode
– Views: Blade templates (login.blade.php, otp-input.blade.php)
– Controllers/Pages: Filament\Pages\Login
- Service Provider: Laravel’s extension mechanism
- Event-Driven / Notification: decoupled sending of OTP codes
- Scheduled Jobs: Artisan command for data hygiene
- Configuration-Driven: config file drives table name, code length, expiry
- Extensibility:
– Contract CanLoginDirectly for bypass logic
– loginPage() override for custom UI

##### Technologies & Frameworks to Annotate
- PHP 8+, Laravel framework
- FilamentPHP (Admin panel)
- Eloquent ORM (Models & Migrations)
- Laravel Notifications (Mail/SMS channels)
- Laravel Artisan Commands & Scheduler
- Blade templating, TailwindCSS, Alpine.js for UI
- PHPStan, Pest/PHPUnit for tests
- Composer / NPM for package management

##### Essential Elements
- Clear labels: component names, data stores, external systems
- Config & Translations: note that they drive plugin behavior
- Extensibility points: CanLoginDirectly contract, custom loginPage override

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Host Application Layer
    subgraph "Host Application"
        direction TB
        User["User"]:::external
        FilamentPanel["Filament Admin Panel"]:::service
    end

    %% Plugin Code Layer
    subgraph "FilamentOtpLoginPlugin Package"
        direction TB
        Plugin["FilamentOtpLoginPlugin"]:::plugin
        ServiceProvider["FilamentOtpLoginServiceProvider"]:::service
        Config["Configuration"]:::config
        Migration["DB Migration"]:::db
        Model["OtpCode Model"]:::db
        Contract["CanLoginDirectly Contract"]:::contract
        Notification["SendOtpCode Notification"]:::service
        Command["PruneOtpCodes Command"]:::command
        FormComponent["OtpInput Form Component"]:::plugin
        Page["Login Page"]:::plugin
        ViewForm["OTP Input Blade View"]:::view
        ViewPage["Login Blade View"]:::view
        TransEn["Translations (EN)"]:::config
        TransTr["Translations (TR)"]:::config
    end

    %% Database
    Database[(otp_codes table)]:::db

    %% External Services
    subgraph "External Services & Scheduler"
        direction TB
        Mailer["Email/SMS Gateway"]:::external
        Scheduler["Cron Scheduler"]:::external
    end

    %% Interactions
    User -->|"HTTP Request to /login"| FilamentPanel
    FilamentPanel -->|"Override Login Page"| Plugin
    Plugin -->|"showLoginPage()"| Page
    Page -->|"renders"| ViewPage
    Page -->|"includes form component"| FormComponent
    FormComponent -->|"renders"| ViewForm
    ViewForm -->|"submit credentials"| Plugin
    Plugin -->|"generate OTP"| Model
    Plugin -->|"save code"| Database
    Plugin -->|"trigger notification"| Notification
    Notification -->|"send via"| Mailer
    Mailer -->|"delivers OTP"| User
    User -->|"enters OTP"| Plugin
    Plugin -->|"verify code"| Model
    Plugin -->|"checks expiry"| Database
    Plugin -->|"authenticate"| FilamentPanel
    Scheduler -->|"runs"| Command
    Command -->|"prune expired"| Database

    %% Component Hooks
    Plugin --> ServiceProvider
    ServiceProvider --> Config
    ServiceProvider --> Migration
    ServiceProvider --> TransEn
    ServiceProvider --> TransTr

    %% Click events
    click Plugin "https://github.com/afsakar/filament-otp-login/blob/main/src/FilamentOtpLoginPlugin.php"
    click ServiceProvider "https://github.com/afsakar/filament-otp-login/blob/main/src/FilamentOtpLoginServiceProvider.php"
    click Config "https://github.com/afsakar/filament-otp-login/blob/main/config/filament-otp-login.php"
    click Migration "https://github.com/afsakar/filament-otp-login/blob/main/database/migrations/create_filament_otp_login_table.php.stub"
    click Model "https://github.com/afsakar/filament-otp-login/blob/main/src/Models/OtpCode.php"
    click Contract "https://github.com/afsakar/filament-otp-login/blob/main/src/Models/Contracts/CanLoginDirectly.php"
    click Notification "https://github.com/afsakar/filament-otp-login/blob/main/src/Notifications/SendOtpCode.php"
    click Command "https://github.com/afsakar/filament-otp-login/blob/main/src/Commands/PruneOtpCodes.php"
    click FormComponent "https://github.com/afsakar/filament-otp-login/blob/main/src/Filament/Forms/OtpInput.php"
    click Page "https://github.com/afsakar/filament-otp-login/blob/main/src/Filament/Pages/Login.php"
    click ViewForm "https://github.com/afsakar/filament-otp-login/blob/main/resources/views/forms/otp-input.blade.php"
    click ViewPage "https://github.com/afsakar/filament-otp-login/blob/main/resources/views/pages/login.blade.php"
    click TransEn "https://github.com/afsakar/filament-otp-login/blob/main/resources/lang/en/translations.php"
    click TransTr "https://github.com/afsakar/filament-otp-login/blob/main/resources/lang/tr/translations.php"

    %% Tests Layer
    subgraph "Tests"
        direction TB
        PluginTests["Plugin Tests"]:::test
        ArchTests["Architecture Tests"]:::test
        UnitTests["Unit & Pest Tests"]:::test
    end

    PluginTests --> Plugin
    ArchTests --> Plugin
    UnitTests --> Plugin

    click PluginTests "https://github.com/afsakar/filament-otp-login/blob/main/src/Testing/TestsFilamentOtpLogin.php"
    click ArchTests "https://github.com/afsakar/filament-otp-login/blob/main/tests/ArchTest.php"
    click UnitTests "https://github.com/afsakar/filament-otp-login/blob/main/tests/ExampleTest.php"

    %% Styles
    classDef service fill:#D2E8FF,stroke:#5B8CC4
    classDef plugin fill:#D6F5D6,stroke:#4CA64C
    classDef db fill:#FFF2CC,stroke:#D6B656,shape:cylinder
    classDef external fill:#F0F0F0,stroke:#999999,shape:cloud
    classDef config fill:#FFE5CC,stroke:#D18B48,shape:document
    classDef view fill:#F5D6D6,stroke:#C44C4C
    classDef contract fill:#EAD6F5,stroke:#8C4CA6
    classDef command fill:#FFF5CC,stroke:#ECAF4C
    classDef test fill:#EEEEEE,stroke:#CCCCCC
```
