82 lines
5.7 KiB
Markdown
82 lines
5.7 KiB
Markdown
---
|
|
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-alpine` configured via a single `Dockerfile` with a bundled Nginx server and Supervisor to manage background queues.
|
|
- **External Services:** MariaDB and Redis run as fully separate, standalone Dokploy application 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()`:
|
|
```php
|
|
// 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:
|
|
```php
|
|
$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.
|