📄 Viewing: README.md
# Maildoll - Email & SMS Marketing SaaS Application
## Project Overview
Maildoll is a comprehensive SaaS (Software as a Service) platform designed for Email and SMS marketing automation. It empowers organizations to manage campaigns, verify emails, track delivery, and monetize services through subscription plans. Built on the Laravel framework, it offers a robust, scalable solution for marketing needs.
## Core Features
- **Campaign Management**: Create, schedule, and track Email and SMS campaigns.
- **Contact Management**: advanced list management with segmentation, import/export, and suppression lists.
- **Automation**: Autoresponders and scheduled triggers for drip campaigns.
- **Payment Integration**: Supports multiple gateways including Stripe, PayPal, Razorpay, Paytm, Mollie, PayU, and more.
- **Role-Based Access Control**: Multi-tenant architecture supporting Admins, Customers, and Agents.
- **Server Management**: Configure multiple SMTP servers (SendGrid, Mailgun, Amazon SES) and SMS Gateways (Twilio, Plivo, Nexmo/Vonage, Infobip).
- **Reporting & Analytics**: Real-time dashboards using Chart.js to visualize open rates, click-through rates, and bounce analytics.
- **Email Verification**: Built-in tools (`EmailVerify.php`) to validate contact lists before sending.
- **Template Builder**: Drag-and-drop email builder using `vue-email-editor` and CKEditor.
## Technology Stack
The project leverages a modern LAMP stack with Vue.js for reactive frontend components.
### Backend
- **Laravel Framework (v8.14)**: Chosen for its elegant syntax, robust dependency injection container, and extensive ecosystem (Jobs, Queues, Eloquent ORM).
- **PHP (^8.0)**: ensures high performance and type safety.
- **MySQL**: Relational database for structured data storage (Campaigns, Contacts, Logs).
### Frontend
- **Vue.js (v2.x)**: Powers interactive components like the Email Builder and Dashboard.
- **Tailwind CSS (v1.4) & Bootstrap (v4)**: Hybrid approach for responsive and utility-first styling.
- **jQuery**: Legacy support for certain UI plugins.
### Key Libraries
- **Maatwebsite/Excel**: For bulk import/export of contacts.
- **Spatie/Laravel-Permission** (inferred): For role management.
- **Guzzle**: For HTTP requests to third-party APIs (SMS gateways).
## Directory Structure
```
/
├── app/ # Core Application Logic
│ ├── Console/ # Artisan Commands and Scheduled Kernels
│ ├── Http/ # Controllers, Middleware, and Requests
│ ├── Models/ # Eloquent ORM Models (Campaign, Contact, User, etc.)
│ ├── Mail/ # Mailable classes for email notifications
│ ├── Jobs/ # Queueable jobs for background processing (Sending emails)
├── config/ # Configuration files (Services, Mail, Payment gateways)
├── database/ # Migrations, Seeders, and Factories
├── public/ # Web root (Assets, index.php)
├── resources/ # Views (Blade templates), raw CSS/JS assets, Vue components
├── routes/ # Web and API route definitions
├── storage/ # Logs, compiled templates, and file uploads
├── tests/ # Feature and Unit tests
└── vendor/ # Composer dependencies
```
## Migration Runbook
`MIGRATION_RUNBOOK.md`
### Prompt:
```
Role: You are acting as a Principal Software Architect and Migration Hardening Expert specializing in legacy strangler migrations and distributed messaging reliability.
Target File: MIGRATION_RUNBOOK.md (EDIT IN-PLACE)
Objective:
Harden and refine the runbook to eliminate contradictions, enforce deterministic execution, and guarantee safe coexistence of legacy Laravel SMS logic and the Go Messaging Service.
DO NOT regenerate the full file.
Perform surgical, minimal edits only.
========================
HARD EXECUTION GUARANTEES (NON-NEGOTIABLE)
========================
These guarantees MUST become explicitly enforced invariants inside the runbook.
Invariant 1 — Single Execution Authority
At any moment, for a given message_uuid, exactly ONE system may perform the external provider send.
Mode behavior MUST be:
OFF:
* Laravel legacy driver sends SMS
* Go service MUST NOT be called
SHADOW:
* Laravel legacy driver sends SMS
* Go service MUST be called with dry_run=true
* Go service MUST NOT call external providers
* Go service result MUST NOT affect HTTP response
* Go service result MUST NOT decrement quota
ON:
* Go service sends SMS (dry_run=false)
* Laravel MUST NOT send SMS unless Go fails BEFORE acceptance
* Legacy fallback is allowed ONLY when Go request:
- times out (>500ms), OR
- returns transport failure, OR
- circuit breaker is OPEN
Invariant 2 — UUID is generated ONCE at entry point
$messageUuidMap MUST be generated BEFORE any send logic.
UUID generation MUST NOT occur inside retry loops or provider loops.
Invariant 3 — Laravel is the ONLY writer to sms_logs
Go service MUST NOT write to sms_logs.
Go writes ONLY to its internal logs table.
Laravel writes Go results into sms_logs with:
source = 'go'
message_uuid
provider_message_id
status
Invariant 4 — Quota decrement safety
Quota decrement MUST occur ONLY when:
mode == ON
AND status IN ('accepted', 'duplicate')
Quota MUST NOT decrement in SHADOW mode.
========================
MANDATORY STRUCTURAL FIXES
========================
1) Canonical Step Consolidation
Ensure exactly ONE canonical step that modifies:
app/Http/Controllers/SmsController.php
Delete or merge any duplicate integration steps.
The canonical logic MUST include:
* Pre-generation of $messageUuidMap
* Pre-generation of $recipientMap
* Strict mode switch block:
switch ($mode) {
case 'OFF':
legacy_send()
break
case 'SHADOW':
legacy_send()
go_send(dry_run=true)
break
case 'ON':
go_send(dry_run=false, timeout=500ms)
if go_send failed BEFORE acceptance:
legacy_send_fallback()
break
}
Delete any logic that generates UUID inside message loops.
Delete any mention of MessagingServiceClient->getRecipientByUuid().
========================
2) Strict 500ms Fallback Gate
Go service calls MUST include explicit timeout of 500ms.
Example requirement in runbook:
Http::timeout(0.5)
Verification Gate MUST include simulated timeout scenario and legacy fallback validation.
========================
3) SHADOW mode provider isolation enforcement
In Go handler section:
Ensure explicit guard:
if req.DryRun {
log("DRY_RUN_NO_PROVIDER_CALL")
return accepted
}
Provider code MUST NOT execute when DryRun == true.
Remove any conflicting statements.
========================
4) Reconciliation correctness enforcement
Ensure reconciliation step uses:
message_uuid as the ONLY join key.
Add mandatory verification query example:
Laravel:
SELECT message_uuid FROM sms_logs WHERE source='go'
Go:
SELECT message_uuid FROM go_sms_logs
Mismatch detection rule MUST be explicit.
========================
OUTPUT REQUIREMENTS (STRICT)
Do NOT output the full file.
Output ONLY:
Part A — Sections modified (by exact headings)
Part B — Exact modified blocks with 3–5 surrounding lines of context
Part C — List of deleted duplicate or conflicting blocks (by heading name)
Part D — Confirmation that all 4 invariants are now enforced
========================
QUALITY BAR
The final runbook MUST allow an automated agent to execute migration step-by-step with zero ambiguity and zero possibility of duplicate external SMS sends.
```
NovaShell
🛸 NovaShell — Cyber Yellow Mode