# mettle/sendportal architecture

> Architecture diagram of the GitHub repository mettle/sendportal, 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/mettle/sendportal
- Repository: https://github.com/mettle/sendportal

## Overview

##### Project type and purpose
- This is a full-stack, self-hosted email-marketing application named SendPortal, built with Laravel (PHP) and Livewire.
- It provides user authentication, multi-workspace management, subscriber/list management, campaign creation, email sending via third-party providers (SES, Postmark, Sendgrid, etc.), and tracking/reporting.

##### File structure
- Top-level folders:
– app/: Laravel application code (Controllers, Models, Services, Repositories, Console commands, Middleware)
– bootstrap/: framework bootstrapper
– config/: configuration files (database, mail, queue, horizon)
– database/: migrations, factories, seeders
– public/: web server entry point (index.php)
– resources/views: Blade templates and Livewire views (frontend)
– routes/: web, api, console, channels
– storage/: cache, sessions, logs
– tests/: Feature and Unit tests
- Key patterns:
– MVC (Controllers, Models, Views)
– Services + Repositories for business logic
– Console commands for install/upgrade workflows
– Livewire for dynamic, reactive UI components
– Laravel Queues + Horizon for asynchronous email dispatch and tracking
– Multi-workspace isolation with middleware enforcing workspace ownership

##### README for additional insights
- Confirms Laravel 10+, PHP 8.2+, MySQL/PostgreSQL, and integration with external mail APIs
- Core logic is in a separate package (sendportal-core), but this wrapper provides auth, routing, multi-workspace

a. Main components
– Client (Browser/SPA)
– Web Server (Nginx/Apache)
– Application Server (Laravel + PHP-FPM)
– Frontend Layer (Blade + Livewire)
– HTTP/API Layer (Controllers → Services → Repositories → Models)
– Queue Worker Layer (Laravel Queues + Horizon)
– Database (MySQL/PostgreSQL)
– Cache (Redis)
– External Email Providers (SES, Postmark, Sendgrid, Mailgun, Mailjet)
– SMTP/Webhook endpoints for bounce/complaint tracking
b. Relationships and interactions
1. Client sends HTTP requests to Web Server
2. Web Server forwards to PHP-FPM / Laravel application
3. Laravel routes → Controllers → Requests → Services → Repositories → Database
4. Controllers return Blade/Livewire views or JSON (API)
5. Actions like “Send Campaign” dispatch Jobs to Queue (Redis)
6. Queue Worker (Horizon) processes jobs, calls External Email APIs
7. Event listeners persist tracking data back to Database
8. Scheduled tasks (cron) trigger recurring jobs (campaign scheduling, cleanup)
c. Architectural patterns & design principles
– MVC for web requests
– Service–Repository for business/domain logic separation
– Command Bus for install/upgrade commands
– Middleware to enforce workspace scoping and authentication
– Event-Driven for email tracking and reporting
– Queues for scalability and non-blocking email dispatch
d. Key technologies/frameworks
– Laravel 10+, PHP 8.2
– Livewire for dynamic UI
– Blade templates
– MySQL or PostgreSQL
– Redis for queue & cache
– Laravel Horizon for queue monitoring
– Amazon SES, Postmark, Sendgrid, Mailgun, Mailjet

##### Capturing essential architectural elements
- Detail every major module:
– Authentication & Authorization
– Workspace management
– Subscriber & List management
– Campaign creation & scheduling
– Email dispatch jobs
– Tracking & reporting events
- How data flows from user input through service layer to external mailer, back through event listeners into reporting UI

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client Layer" 
        direction TB
        Browser["Client (Browser/SPA)"]:::frontend
    end

    %% Web Server Layer
    subgraph "Web Server Layer" 
        direction TB
        WebServer["Web Server (Nginx/Apache)"]:::backend
    end

    Browser -->|"HTTP/HTTPS"| WebServer
    WebServer -->|"FastCGI"| AppServer

    %% Application Server
    subgraph "Application Server" 
        direction TB
        AppServer["PHP-FPM / Laravel App"]:::backend

        subgraph "Frontend Layer"
            direction TB
            Blade["Blade Templates"]:::frontend
            Livewire["Livewire Components"]:::frontend
        end

        subgraph "HTTP/API Layer"
            direction TB
            Controllers["Controllers"]:::backend
            ServicesRepo["Services & Repositories"]:::backend
            Requests["HTTP Requests & Resources"]:::backend
            Middleware["Middleware (Auth & Workspace)"]:::backend
        end

        Controllers --> ServicesRepo
        ServicesRepo -->|"SQL"| Database
        Controllers -->|"renders"| Blade
        Controllers -->|"renders"| Livewire
        Controllers -->|"JSON"| APIClients

        Middleware -.-> Controllers

    end

    WebServer --> AppServer

    %% Queue Worker Layer
    subgraph "Worker Layer"
        direction TB
        Queue["Laravel Queue (Redis)"]:::cache
        Horizon["Horizon Worker"]:::backend
        ConsoleCmds["Console Commands"]:::backend
    end

    AppServer -->|"enqueue"| Queue
    Queue --> Horizon
    AppServer --->|"cron/dotted"| ConsoleCmds

    %% Infrastructure
    subgraph "Infrastructure"
        direction TB
        Database["MySQL/PostgreSQL"]:::db
        Redis["Redis (Cache & Queue)"]:::cache
    end

    ServicesRepo --> Database
    Queue --> Redis
    AppServer --> Redis

    %% External Services
    subgraph "External Email Providers"
        direction TB
        SES["Amazon SES"]:::external
        Postmark["Postmark"]:::external
        Sendgrid["Sendgrid"]:::external
        Mailgun["Mailgun"]:::external
        Mailjet["Mailjet"]:::external
    end

    Horizon -->|"API Calls"| SES
    Horizon -->|"API Calls"| Postmark
    Horizon -->|"API Calls"| Sendgrid
    Horizon -->|"API Calls"| Mailgun
    Horizon -->|"API Calls"| Mailjet

    %% Click Events
    click Controllers "https://github.com/mettle/sendportal/tree/master/app/Http/Controllers"
    click Middleware "https://github.com/mettle/sendportal/blob/master/app/Http/Middleware/Authenticate.php"
    click Middleware "https://github.com/mettle/sendportal/blob/master/app/Http/Middleware/RequireWorkspace.php"
    click Middleware "https://github.com/mettle/sendportal/blob/master/app/Http/Middleware/OwnsCurrentWorkspace.php"
    click Middleware "https://github.com/mettle/sendportal/blob/master/app/Http/Middleware/OwnsRequestedWorkspace.php"
    click ServicesRepo "https://github.com/mettle/sendportal/tree/master/app/Services/Workspaces"
    click ServicesRepo "https://github.com/mettle/sendportal/blob/master/app/Repositories/WorkspacesRepository.php"
    click Blade "https://github.com/mettle/sendportal/blob/master/resources/views/**/*.blade.php"
    click Livewire "https://github.com/mettle/sendportal/blob/master/app/Livewire/Setup.php"
    click Livewire "https://github.com/mettle/sendportal/blob/master/resources/views/livewire/setup.blade.php"
    click Queue "https://github.com/mettle/sendportal/blob/master/config/queue.php"
    click Horizon "https://github.com/mettle/sendportal/blob/master/config/horizon.php"
    click Horizon "https://github.com/mettle/sendportal/blob/master/app/Providers/HorizonServiceProvider.php"
    click ConsoleCmds "https://github.com/mettle/sendportal/blob/master/app/Console/Commands/InstallApplication.php"
    click ConsoleCmds "https://github.com/mettle/sendportal/blob/master/app/Console/Commands/UpgradeApplication.php"
    click ConsoleCmds "https://github.com/mettle/sendportal/blob/master/app/Console/Kernel.php"
    click Controllers "https://github.com/mettle/sendportal/blob/master/routes/web.php"
    click Controllers "https://github.com/mettle/sendportal/blob/master/routes/api.php"
    click Requests "https://github.com/mettle/sendportal/tree/master/app/Http/Requests"
    click Requests "https://github.com/mettle/sendportal/tree/master/app/Http/Resources"
    click Database "https://github.com/mettle/sendportal/blob/master/database/migrations/*.php"
    click Database "https://github.com/mettle/sendportal/tree/master/database/factories"
    click Database "https://github.com/mettle/sendportal/blob/master/database/seeders/DatabaseSeeder.php"
    click Redis "https://github.com/mettle/sendportal/blob/master/config/cache.php"
    click Redis "https://github.com/mettle/sendportal/blob/master/config/session.php"

    %% Legend
    subgraph "Legend"
        direction TB
        A[Blue = Frontend]:::frontend
        B[Green = Backend]:::backend
        C[Orange = Database]:::db
        D[Yellow = Cache/Queue]:::cache
        E[Purple = External Service]:::external
    end

    classDef frontend fill:#D0E8FF,stroke:#69B9FF,color:#034A91;
    classDef backend fill:#DFF7D8,stroke:#6CC24A,color:#2F6627;
    classDef db fill:#FFE5B4,stroke:#FFC070,color:#7A4F01;
    classDef cache fill:#FFF4C1,stroke:#FFE066,color:#7A5E00;
    classDef external fill:#E2D4F0,stroke:#B299D9,color:#5C3F6D
```
