# martinpetricko/laravel-database-mail architecture

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

- Interactive diagram: https://gitdiagram.com/martinpetricko/laravel-database-mail
- Repository: https://github.com/martinpetricko/laravel-database-mail

## Overview

##### Project type and purpose
- This is an open-source Laravel package (“Laravel Database Mail”) that lets you store email templates in your database, link them to Laravel events, and automatically send them when those events fire. It integrates deeply with the Laravel framework by providing service providers, facades, migrations, models, event contracts/traits, listeners, mailables, and Artisan commands.

##### High-level file-structure analysis
- Top-level files: composer.json, README, config and database directories for publishing configuration/migrations, example code, and a full test suite.
- src/ directory subdivides into:
- Attachments (Attachment class)
- Commands (ExportMailTemplates, ImportMailTemplates)
- Events (contracts, concerns/traits for “TriggersDatabaseMail”)
- Listeners (SendDatabaseEmails)
- Mail (EventMail mailable)
- Models (MailTemplate, MailException)
- Properties (generic Property and Resolver implementations)
- Recipients (Recipient class)
- Exceptions (DatabaseMailException)
- Facades and ServiceProviders
- dir “example” shows user-side event and model usage.
- config/database-mail.php driving behavior (enabled events, resolvers, models, mailable).

##### Key architecture and interaction points from README
- ServiceProvider registers event listener for any event implementing the TriggersDatabaseMail interface.
- Events use the CanTriggerDatabaseMail trait and a static list of recipients/attachments.
- SendDatabaseEmails listener:
1) Fetches matching MailTemplate(s) for the event class
2) Resolves event properties via Resolvers (Eloquent, Boolean, String)
3) Instantiates EventMail mailable
4) Dispatches via Laravel’s Mailer to resolved Recipients, attaches resolved Attachments
5) Catches DatabaseMailException and logs via LaravelDatabaseMail facade into the mail_exceptions table.
- Artisan commands for importing/exporting MailTemplate JSON files.
- Migrations create two tables: mail_templates and mail_exceptions.

##### Components
a. Laravel Application (host)
- Service Provider (LaravelDatabaseMailServiceProvider)
- Facade (LaravelDatabaseMail)
- Event Dispatcher & Queue
- Mailer subsystem (Laravel\Mail\Mailer)
- Scheduler (for exception pruning/commands)
b. Package Core Components
- Config (database-mail.php)
- Migrations → Database (mail_templates, mail_exceptions)
- Models → Eloquent ORM
- Events (Contracts + CanTriggerDatabaseMail trait)
- Listener (SendDatabaseEmails)
- Resolvers (EloquentResolver, BooleanResolver, StringResolver)
- Mailable (EventMail)
- Attachments & Recipients
- Exceptions (DatabaseMailException)
- Commands (ExportMailTemplates, ImportMailTemplates)
c. External Services
- Database (MySQL/Postgres/etc.)
- SMTP/External Mail Transport

##### Relationships and data‐flow
1) Developer dispatches a Laravel Event (implements TriggersDatabaseMail).
2) Laravel Event Dispatcher invokes SendDatabaseEmails listener.
3) Listener queries MailTemplate model(s) by event class from the database.
4) Listener uses Resolvers to map event public properties → template variables.
5) Listener builds EventMail instance (Blade-rendered subject & body).
6) Listener calls Mailer→to(Recipients)…send(EventMail).
7) On error, DatabaseMailException is thrown & caught; Listener calls Facade→logException → persisted in mail_exceptions table.
8) Separate flow: Artisan commands read/write MailTemplate JSON files ↔ MailTemplate model(s).

##### Architectural patterns & design principles
- Laravel Service Provider & Facade pattern for integration
- Observer pattern (Events & Listeners)
- Command pattern (Artisan Commands)
- MVC/ActiveRecord via Eloquent Models
- Strategy pattern via pluggable Resolvers & Recipient/Attachment callbacks
- POPO (Plain Old PHP Object) Contracts & Traits for extensibility

## Diagram (Mermaid)

```mermaid
graph TB
    %% Laravel Core
    subgraph "Laravel Core"
        direction TB
        EventDispatcher["Event Dispatcher"]:::laravelCore
        Mailer["Laravel Mailer"]:::laravelCore
        Scheduler["Scheduler & Artisan"]:::laravelCore
    end

    %% Package Components
    subgraph "Package Components"
        direction TB
        ServiceProvider["LaravelDatabaseMailServiceProvider"]:::package
        Facade["LaravelDatabaseMail Facade"]:::package
        CoreFacade["LaravelDatabaseMail (Accessor)"]:::package
        Config["Config (database-mail.php)"]:::package

        subgraph "Events & Contracts"
            direction TB
            Contract["TriggersDatabaseMail Contract"]:::interface
            Trait["CanTriggerDatabaseMail Trait"]:::package
        end

        Listener["SendDatabaseEmails Listener"]:::package
        Mailable["EventMail Mailable"]:::package

        subgraph "Models"
            direction TB
            MailTemplate["MailTemplate Model"]:::package
            MailExceptionModel["MailException Model"]:::package
        end

        subgraph "Properties & Resolvers"
            direction TB
            Property["Property Base"]:::package
            ResolverInt["ResolverInterface"]:::interface
            BoolResolver["BooleanResolver"]:::package
            EloquentResolver["EloquentResolver"]:::package
            StringResolver["StringResolver"]:::package
        end

        Attachment["Attachment"]:::package
        Recipient["Recipient"]:::package
        ExceptionClass["DatabaseMailException"]:::package

        CommandsExport["ExportMailTemplates Command"]:::package
        CommandsImport["ImportMailTemplates Command"]:::package
    end

    %% Database
    subgraph "Database"
        direction TB
        TemplatesTable["mail_templates Table"]:::db
        ExceptionsTable["mail_exceptions Table"]:::db
    end

    %% External Services
    subgraph "External Services"
        direction TB
        SMTP["SMTP / Mail Transport"]:::external
        DB["Database (MySQL/Postgres)"]:::external
    end

    %% Runtime Flow
    ServiceProvider -->|registers listener| EventDispatcher
    EventDispatcher -->|fires event| Listener
    Listener -->|queries| MailTemplate
    MailTemplate -->|reads/writes| DB
    Listener -->|uses| ResolverInt
    ResolverInt --> BoolResolver
    ResolverInt --> EloquentResolver
    ResolverInt --> StringResolver
    Listener -->|builds| Mailable
    Mailable -->|sends via| Mailer
    Mailer -->|delivers| SMTP

    Listener -->|on error throws| ExceptionClass
    ExceptionClass -->|logs via facade| Facade
    Facade -->|calls accessor| CoreFacade
    CoreFacade -->|persists| MailExceptionModel
    MailExceptionModel -->|writes| DB

    %% CLI Commands
    CommandsExport -->|reads| MailTemplate
    CommandsImport -->|writes| MailTemplate
    CommandsExport --> DB
    CommandsImport --> DB

    %% Configuration
    ServiceProvider -->|loads| Config

    %% Click Events
    click ServiceProvider "https://github.com/martinpetricko/laravel-database-mail/blob/main/src/LaravelDatabaseMailServiceProvider.php"
    click Facade "https://github.com/martinpetricko/laravel-database-mail/blob/main/src/Facades/LaravelDatabaseMail.php"
    click CoreFacade "https://github.com/martinpetricko/laravel-database-mail/blob/main/src/LaravelDatabaseMail.php"
    click Config "https://github.com/martinpetricko/laravel-database-mail/blob/main/config/database-mail.php"
    click TemplatesTable "https://github.com/martinpetricko/laravel-database-mail/blob/main/database/migrations/create_mail_templates_table.php"
    click ExceptionsTable "https://github.com/martinpetricko/laravel-database-mail/blob/main/database/migrations/create_mail_exceptions_table.php"
    click MailTemplate "https://github.com/martinpetricko/laravel-database-mail/blob/main/src/Models/MailTemplate.php"
    click MailExceptionModel "https://github.com/martinpetricko/laravel-database-mail/blob/main/src/Models/MailException.php"
    click Contract "https://github.com/martinpetricko/laravel-database-mail/blob/main/src/Events/Contracts/TriggersDatabaseMail.php"
    click Trait "https://github.com/martinpetricko/laravel-database-mail/blob/main/src/Events/Concerns/CanTriggerDatabaseMail.php"
    click Listener "https://github.com/martinpetricko/laravel-database-mail/blob/main/src/Listeners/SendDatabaseEmails.php"
    click Mailable "https://github.com/martinpetricko/laravel-database-mail/blob/main/src/Mail/EventMail.php"
    click Property "https://github.com/martinpetricko/laravel-database-mail/blob/main/src/Properties/Property.php"
    click ResolverInt "https://github.com/martinpetricko/laravel-database-mail/blob/main/src/Properties/Resolvers/ResolverInterface.php"
    click BoolResolver "https://github.com/martinpetricko/laravel-database-mail/blob/main/src/Properties/Resolvers/BooleanResolver.php"
    click EloquentResolver "https://github.com/martinpetricko/laravel-database-mail/blob/main/src/Properties/Resolvers/EloquentResolver.php"
    click StringResolver "https://github.com/martinpetricko/laravel-database-mail/blob/main/src/Properties/Resolvers/StringResolver.php"
    click Attachment "https://github.com/martinpetricko/laravel-database-mail/blob/main/src/Attachments/Attachment.php"
    click Recipient "https://github.com/martinpetricko/laravel-database-mail/blob/main/src/Recipients/Recipient.php"
    click ExceptionClass "https://github.com/martinpetricko/laravel-database-mail/blob/main/src/Exceptions/DatabaseMailException.php"
    click CommandsExport "https://github.com/martinpetricko/laravel-database-mail/blob/main/src/Commands/ExportMailTemplates.php"
    click CommandsImport "https://github.com/martinpetricko/laravel-database-mail/blob/main/src/Commands/ImportMailTemplates.php"

    %% Styles
    classDef laravelCore fill:#ddd,stroke:#888,stroke-width:1px
    classDef package fill:#bbd,stroke:#448,stroke-width:1px
    classDef db fill:#fdc,stroke:#c84,stroke-width:1px
    classDef external fill:#dfd,stroke:#484,stroke-width:1px
    classDef interface stroke-dasharray: 5 5,stroke:#000,fill:#bbf
```
