# Architecture

For non-technical users: This page is intended for developers who want to understand or customize how MailTrixy is built. If you're looking for how to use MailTrixy's features, see the Features section instead.

A comprehensive overview of MailTrixy's technical architecture, design patterns, and system structure.

## Tech Stack Overview

MailTrixy is built on a modern PHP stack designed for scalability, maintainability, and developer productivity.

Technology | Version | Purpose
--- | --- | ---
Laravel | 12.x | Backend framework, routing, ORM, queues, events
Livewire | 4.x | Reactive UI components without writing JavaScript
Alpine.js | 3.x | Lightweight JavaScript for interactive UI elements
Tailwind CSS | 4.x | Utility-first CSS framework for styling
MySQL | 8.0+ | Primary relational database
PHP | 8.2+ | Server-side programming language
Laravel Sanctum | 4.x | API token authentication
Laravel Cashier | 15.x | Subscription billing with Stripe

## Directory Structure

MailTrixy follows the standard Laravel directory structure with additional organization for domain-specific logic.

    app/
    ├── Console/              # Artisan commands and Kernel
    ├── Events/               # Event classes for real-time notifications
    ├── Helpers/              # Global helper functions
    ├── Http/
    │   ├── Controllers/      # HTTP controllers (API & Web)
    │   ├── Middleware/        # Request middleware (workspace, throttle)
    │   └── Requests/         # Form request validation
    ├── Jobs/                 # 13 queue job classes
    ├── Livewire/             # 47 Livewire components
    ├── Mail/                 # Mailable classes for transactional emails
    ├── Models/               # 49 Eloquent models
    ├── Notifications/        # Notification classes
    ├── Policies/             # Authorization policies
    ├── Services/             # Service layer classes
    └── Traits/               # Shared traits (AuthorizesWorkspaceActions)

    database/
    ├── factories/            # Model factories for testing
    ├── migrations/           # 41 migration files
    └── seeders/              # Database seeders with demo data

    resources/
    ├── css/                  # Tailwind source files
    └── views/
        ├── components/       # Blade components
        ├── email-templates/  # 52 email templates
        ├── layouts/          # Application layouts
        └── livewire/         # Livewire component views

    routes/
    ├── api.php               # REST API routes (v1)
    ├── channels.php          # Broadcasting channels
    ├── console.php           # Console commands
    └── web.php               # Web routes

## 49 Models Overview

MailTrixy uses 49 Eloquent models organized across the following domains. Each model belongs to a workspace through the multi-tenant architecture.

Domain | Models | Count
--- | --- | ---
Core | User, Workspace, WorkspaceMember, WorkspaceInvitation, Role, Permission | 6
Email | EmailAccount, Email, EmailFolder, EmailAttachment, EmailSignature, EmailTemplate | 6
Conversations | Conversation, ConversationMessage, ConversationParticipant, ConversationAssignment, ConversationLabel | 5
Contacts | Contact, ContactGroup, ContactField, ContactFieldValue, ContactNote, ContactActivity | 6
Campaigns | Campaign, CampaignRecipient, CampaignAnalytics, CampaignTemplate, CampaignSchedule | 5
Workflows | Workflow, WorkflowStep, WorkflowExecution, WorkflowPreset, WorkflowLog | 5
AI | AiProvider, AiConversation, AiMessage, AiUsageLog, SentimentAnalysis | 5
Knowledge Base | KnowledgeBase, KBDocument, KBChunk, KBWebsiteScrape | 4
Billing | Plan, Subscription, Payment, Invoice | 4
Misc | Tag, CannedResponse, Webhook | 3

## 41 Migrations

MailTrixy ships with 41 database migrations that create all the required tables and indexes. Migrations are timestamped and run sequentially to establish the correct foreign key relationships. Key migration groups include:

- Core tables — users, workspaces, workspace_members, roles, permissions (5 migrations)
- Email tables — email_accounts, emails, email_folders, email_attachments, email_signatures, email_templates (6 migrations)
- Conversation tables — conversations, conversation_messages, participants, assignments, labels (5 migrations)
- Contact tables — contacts, contact_groups, custom fields, field values, notes, activities (6 migrations)
- Campaign tables — campaigns, campaign_recipients, analytics, templates, schedules (5 migrations)
- Workflow tables — workflows, steps, executions, presets, logs (5 migrations)
- AI tables — ai_providers, ai_conversations, ai_messages, usage_logs, sentiment_analyses (5 migrations)
- Knowledge base tables — knowledge_bases, kb_documents, kb_chunks, kb_website_scrapes (4 migrations)

## 47 Livewire Components

The frontend is powered by 47 Livewire components that provide reactive, real-time user interfaces without heavy JavaScript. Components are organized by feature domain:

- Inbox — ConversationList, ConversationView, MessageComposer, EmailViewer, FolderTree (5 components)
- Contacts — ContactTable, ContactForm, ContactImport, ContactGroupManager, ContactFieldEditor, MergeContacts (6 components)
- Campaigns — CampaignBuilder, CampaignList, TemplateEditor, RecipientSelector, CampaignAnalytics, ScheduleManager (6 components)
- Workflows — WorkflowBuilder, WorkflowList, StepEditor, WorkflowPresets, ExecutionLog (5 components)
- AI — AiChatPanel, AiReplyGenerator, SentimentViewer, AiSettings, SpendingCapManager (5 components)
- Knowledge Base — KBManager, DocumentUploader, WebsiteScraper, ChunkViewer (4 components)
- Settings — WorkspaceSettings, AccountSettings, EmailAccountManager, SignatureEditor, NotificationPreferences, WebhookManager (6 components)
- Admin — AdminDashboard, PlanManager, UserManager, PaymentGatewaySettings, GlobalSettings, SystemHealth (6 components)
- Shared — TagSelector, FileUploader, RichTextEditor, Modal (4 components)

## Multi-Tenant Workspace Architecture

MailTrixy uses a single-database, multi-tenant architecture where every data record belongs to a workspace. Workspace isolation is enforced at multiple levels:

- Global Scope — A `WorkspaceScope` is automatically applied to all workspace-scoped models, ensuring queries only return data belonging to the current workspace.
- Middleware — The `SetCurrentWorkspace` middleware resolves the active workspace from the session or subdomain and binds it to the application container.
- Model Trait — Models use the `BelongsToWorkspace` trait which auto-assigns `workspace_id` on creation and applies the global scope.
- Policy Layer — Authorization policies verify that the authenticated user belongs to the same workspace as the requested resource.

    // Example: BelongsToWorkspace trait
    trait BelongsToWorkspace
    {
        protected static function bootBelongsToWorkspace(): void
        {
            static::addGlobalScope(new WorkspaceScope);

            static::creating(function ($model) {
                if (! $model->workspace_id) {
                    $model->workspace_id = current_workspace_id();
                }
            });
        }

        public function workspace(): BelongsTo
        {
            return $this->belongsTo(Workspace::class);
        }
    }

## Service Layer Pattern

Business logic is encapsulated in dedicated service classes rather than being placed directly in controllers or Livewire components. This provides clean separation of concerns and makes the codebase testable.

- EmailSyncService — Handles IMAP connection, folder synchronization, and email parsing.
- CampaignService — Manages campaign creation, scheduling, sending, and analytics tracking.
- WorkflowEngine — Executes workflow steps, evaluates conditions, and manages execution state.
- AiService — Abstracts AI provider communication, token counting, and spending cap enforcement.
- KnowledgeBaseService — Handles document chunking, embedding generation, and semantic search.
- BillingService — Manages subscription lifecycle, plan limits, and payment gateway integration.
- ContactService — Handles contact CRUD, group management, import/export, and merge operations.
- WebhookService — Manages webhook registration, payload signing, delivery, and retry logic.

## Trait Usage

MailTrixy makes extensive use of PHP traits to share behavior across classes without inheritance hierarchies.

Trait | Used By | Purpose
--- | --- | ---
AuthorizesWorkspaceActions | Livewire components | Verifies that the current user has permission to perform an action within the active workspace
BelongsToWorkspace | Eloquent models | Auto-assigns workspace_id, applies global scope for tenant isolation
HasCustomFields | Contact model | Manages dynamic custom field values with get/set accessors
TracksActivity | Contact, Conversation | Automatically logs create, update, and delete events to the activity timeline
EncryptsAttributes | EmailAccount, AiProvider | Transparently encrypts and decrypts sensitive fields (tokens, API keys)
HasTags | Contact, Conversation, Email | Polymorphic tag relationship for categorization and filtering