# hexters/maillens architecture

> Architecture diagram of the GitHub repository hexters/maillens, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hexters/maillens
- Repository: https://github.com/hexters/maillens

## Overview

MailLens is a Laravel development mail catcher: the host app sends mail through its configured `lens` mailer, which stores messages for browsing at `/mail`. The inbox supports search, message previews and source, attachment downloads, polling, deletion and read-state management; password protection is optional. Queued mail is captured when Laravel’s queue runs it. The graph follows the sampled provider, transport, model, routes, middleware and controller; the README documents database storage and the migration, whose implementation was not sampled.

Main entry points: [`src/routes/web.php`](https://github.com/hexters/maillens/blob/main/src/routes/web.php) (Inbox routes), [`src/MailLensServiceProvider.php`](https://github.com/hexters/maillens/blob/main/src/MailLensServiceProvider.php) (Service provider), [`src/Transport/MailLensTransport.php`](https://github.com/hexters/maillens/blob/main/src/Transport/MailLensTransport.php) (Capture transport), [`src/Http/Controllers/MailLensController.php`](https://github.com/hexters/maillens/blob/main/src/Http/Controllers/MailLensController.php) (Inbox controller)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_integration["Laravel integration"]
  node_provider["Service provider"]
  node_config["MailLens config<br/>[config.php]"]
  node_routes["Inbox routes<br/>[web.php]"]
end

subgraph group_capture["Mail capture"]
  node_transport["Capture transport"]
end

subgraph group_inbox["Inbox and access"]
  node_guard["Password guard<br/>[MailLensGuard.php]"]
  node_lock_view["Lock screen<br/>[lock.blade.php]"]
  node_controller["Inbox controller"]
  node_inbox_view["Inbox interface<br/>[index.blade.php]"]
end

subgraph group_persistence["Message persistence"]
  node_message_model["Message model"]
  node_message_table[("Message table")]
end

node_host_app(("Laravel app"))
node_browser(("Developer browser"))
node_queue_worker(("Laravel queue worker"))

node_host_app -.->|"boots package"| node_provider
node_provider -->|"merges config"| node_config
node_provider -->|"registers mailer"| node_transport
node_provider -->|"loads when active"| node_routes
node_host_app -->|"sends via lens"| node_transport
node_queue_worker -->|"runs queued send"| node_transport
node_transport -->|"creates and prunes"| node_message_model
node_message_model -.->|"stores messages"| node_message_table
node_routes -->|"guards inbox routes"| node_guard
node_guard -->|"renders lock screen"| node_lock_view
node_routes -->|"dispatches requests"| node_controller
node_controller -->|"queries and updates"| node_message_model
node_controller -->|"renders inbox"| node_inbox_view
node_browser -->|"opens inbox"| node_routes
node_inbox_view -->|"polls for changes"| node_routes

click node_provider "https://github.com/hexters/maillens/blob/main/src/MailLensServiceProvider.php"
click node_config "https://github.com/hexters/maillens/blob/main/src/Config/config.php"
click node_routes "https://github.com/hexters/maillens/blob/main/src/routes/web.php"
click node_transport "https://github.com/hexters/maillens/blob/main/src/Transport/MailLensTransport.php"
click node_guard "https://github.com/hexters/maillens/blob/main/src/Http/Middleware/MailLensGuard.php"
click node_lock_view "https://github.com/hexters/maillens/blob/main/src/Resources/views/lock.blade.php"
click node_controller "https://github.com/hexters/maillens/blob/main/src/Http/Controllers/MailLensController.php"
click node_inbox_view "https://github.com/hexters/maillens/blob/main/src/Resources/views/index.blade.php"
click node_message_model "https://github.com/hexters/maillens/blob/main/src/Models/MailLensMessage.php"
click node_message_table "https://github.com/hexters/maillens/blob/main/database/migrations/2026_01_01_000000_create_maillens_messages_table.php"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_provider,node_config,node_routes,node_browser toneBlue
class node_transport toneAmber
class node_guard,node_lock_view,node_controller,node_inbox_view toneMint
class node_message_model,node_message_table,node_queue_worker toneRose
class node_host_app toneIndigo
```

## Components

### Laravel integration

- [Service provider](https://github.com/hexters/maillens/blob/main/src/MailLensServiceProvider.php): `src/MailLensServiceProvider.php`
- [MailLens config](https://github.com/hexters/maillens/blob/main/src/Config/config.php): `src/Config/config.php`
- [Inbox routes](https://github.com/hexters/maillens/blob/main/src/routes/web.php): `src/routes/web.php`

### Mail capture

- [Capture transport](https://github.com/hexters/maillens/blob/main/src/Transport/MailLensTransport.php): `src/Transport/MailLensTransport.php`

### Inbox and access

- [Password guard](https://github.com/hexters/maillens/blob/main/src/Http/Middleware/MailLensGuard.php): `src/Http/Middleware/MailLensGuard.php`
- [Lock screen](https://github.com/hexters/maillens/blob/main/src/Resources/views/lock.blade.php): `src/Resources/views/lock.blade.php`
- [Inbox controller](https://github.com/hexters/maillens/blob/main/src/Http/Controllers/MailLensController.php): `src/Http/Controllers/MailLensController.php`
- [Inbox interface](https://github.com/hexters/maillens/blob/main/src/Resources/views/index.blade.php): `src/Resources/views/index.blade.php`

### Message persistence

- [Message model](https://github.com/hexters/maillens/blob/main/src/Models/MailLensMessage.php): `src/Models/MailLensMessage.php`
- [Message table](https://github.com/hexters/maillens/blob/main/database/migrations/2026_01_01_000000_create_maillens_messages_table.php): `database/migrations/2026_01_01_000000_create_maillens_messages_table.php`

### Other components

- **Laravel app**
- **Developer browser**
- **Laravel queue worker**

## Connections

- Laravel app → Service provider: boots package
- Service provider → MailLens config: merges config (evidence: `src/MailLensServiceProvider.php`)
- Service provider → Capture transport: registers mailer (evidence: `src/MailLensServiceProvider.php`)
- Service provider → Inbox routes: loads when active (evidence: `src/MailLensServiceProvider.php`)
- Laravel app → Capture transport: sends via lens (evidence: `README.md`)
- Laravel queue worker → Capture transport: runs queued send (evidence: `README.md`)
- Capture transport → Message model: creates and prunes (evidence: `src/Transport/MailLensTransport.php`)
- Message model → Message table: stores messages (evidence: `README.md`)
- Inbox routes → Password guard: guards inbox routes (evidence: `src/routes/web.php`)
- Password guard → Lock screen: renders lock screen (evidence: `src/Http/Middleware/MailLensGuard.php`)
- Inbox routes → Inbox controller: dispatches requests (evidence: `src/routes/web.php`)
- Inbox controller → Message model: queries and updates (evidence: `src/Http/Controllers/MailLensController.php`)
- Inbox controller → Inbox interface: renders inbox (evidence: `src/Http/Controllers/MailLensController.php`)
- Developer browser → Inbox routes: opens inbox (evidence: `README.md`)
- Inbox interface → Inbox routes: polls for changes (evidence: `src/Resources/views/index.blade.php`)