zemailnator/Project.md

description

description
Zemailnator - AI-First Project Documentation

Zemailnator Project Documentation

AI INSTRUCTION: This Project.md file contains critical context for the Zemailnator (Disposable Email Generator) application. When interacting with this project, ALWAYS load and review this file as part of your system instructions. Treat these guidelines, architectural details, and known security flaws as your primary working context.

1. Project Overview & Architecture

Zemailnator is a scalable disposable temporary email service (like Mailinator or 10 Minute Mail) built on the Laravel framework. It provides users with instant, disposable email addresses to prevent spam, with premium tiers offering custom domains, 10-minute validity enhancements, and bulk generation capabilities.

Core Mechanics:

• The platform uses IMAP (ddeboer/imap via PHP ext-imap) to fetch emails from a master mailbox.
• App\Models\Email::fetchProcessStoreEmail() processes incoming messages, parses HTML/Text bodies, extracts allowed attachments to the public Laravel Storage disk, and stores the records in the database.
• Background cleanup and email fetching are handled automatically via Supervisor running Laravel Scheduled Commands (emails:fetch, mailbox:clean, attachments:clean).

1.1 Deployment Architecture (Dokploy)

Zemailnator is containerized for zero-downtime deployment on Dokploy:

• Application Container: Uses php:8.4-fpm with a bundled Nginx server and Supervisor to manage background queues.
• External Services: MariaDB and Redis run as fully separate, standalone Dokploy instances to allow for independent backups and to prevent database restarts during application deployment.

2. Technology Stack

• Framework: Laravel 12.x
• PHP Version: >= 8.2
• Frontend / UI: Livewire v3, Flux UI Free, Tailwind CSS v4, Vite
• Admin Panel: Filament v4
• Billing: Laravel Cashier (Stripe) v15, alongside a custom Unified Payment System (OxaPay, etc.)
• Testing: Pest v3
• Email Parsing: PHP ext-imap, ddeboer/imap

3. Key Features

• Disposable Email Generation: Quick generation of random or temporary emails via Livewire components (e.g., /mailbox, /gmailnator).
• Premium Subscriptions: Tiered access (Stripe/Crypto) unlocking features like Premium Domains, 10-Minute Emails, and Bulk Email generation.
• Admin Dashboard: Fully managed via Filament, including logs functionality, failed jobs monitoring, and dynamic database configuration.
• Impersonation: Admins can impersonate users for troubleshooting (ImpersonationController).

4. Security & Technical Debt Improvements (Resolved)

The following critical flaws have been successfully addressed:

1. Hardcoded Credentials in Routes:
   • Resolved: The highly insecure /0xdash/slink and /0xdash/scache endpoints with basic HTTP authentication have been permanently removed. Storage linking is now handled securely during deployment via entrypoint.sh.
2. Public Attachment Storage (RCE Risk):
   • Resolved: Attachments are no longer stored directly in public/tmp/attachments. The Email model now strictly leverages Laravel's secure Storage::disk('public') abstraction avoiding direct file_put_contents.
3. Standalone PHP Scripts:
   • Resolved: Legacy scripts like dropmail.php and cleanCron.php now securely dispatch the new native Laravel Console Commands (mailbox:clean, etc.).
4. Legacy Checkout System:
   • Resolved: Old Stripe Cashier routes (checkout/{plan}) were removed to enforce the newer Unified Payment System.

(Note: Ensure rate limiting is strictly applied to Livewire generation endpoints to prevent DoS.)

5. Pros & Cons

Pros:

• Modern Stack: Utilizes bleeding-edge tools (Laravel 12, PHP 8.4, Livewire 3, Tailwind 4) resulting in a highly responsive SPA-like feel.
• Robust Admin Panel: Leveraging Filament provides out-of-the-box CRUD, logging, and mail monitoring.
• Production Ready: Fully containerized setup tailored for Dokploy using MariaDB/Redis standalone instances for maximum scalability and zero-downtime deployments.

Cons:

• Rate Limiting: Needs comprehensive throttling on Livewire generation endpoints to completely mitigate aggressive abuse.

6. Development Guide & Setup Best Practices

1. Ensure both ext-imap and ext-curl are enabled in your php.ini.
2. Run npm run dev in tandem with php artisan serve if working on Frontend/FluxUI adjustments.
3. To test email fetching locally without an active IMAP server, consider writing Pest tests mocking the ConnectionInterface.
4. Always use php artisan test before committing. The project uses Pest. Make sure datasets and mocking are used properly per the CLAUDE.md guidelines.

7. Examples / Workflows

Example: Fetching Emails The Email model has a primary function fetchProcessStoreEmail():

// Call this to manually pull emails
App\Models\Email::fetchProcessStoreEmail(); 

Example: Reading Emails (Livewire) The Mailbox component fetches emails for the active user session or session ID, parsing them via:

$emails = App\Models\Email::parseEmail($currentUserEmailAddress, $deletedArray);

8. AI Auto-Load Instruction

For AI Agents: Whenever you receive a new chat prompt within this workspace, your implicit first step must be to cross-reference the user's request against this Project.md document. Pay special attention to the Laravel 12 / Livewire 3 structures and strictly avoid executing basic auth routes or standard PHP scripts directly if Laravel-native alternatives exist. Use Pest for all tests. ALWAYS rely on the CLAUDE.md guidelines as your secondary set of standard rules.