How ktovoz/moemail works
Project Type and Purpose
• MoeMail is a full‑stack, serverless temporary email service built on Next.js (App Router) and Cloudflare’s edge platform.
• It offers a React‑based frontend, Next.js API routes for business logic, Cloudflare D1 (SQLite) as the primary database, Cloudflare KV for configuration, and two standalone Cloudflare Workers (email‑receiver and cleanup).
• Users authenticate via GitHub OAuth (NextAuth), create disposable mailboxes, receive messages (real‑time or Webhook), and manage roles/API keys under an RBAC system.
File Structure Analysis
• app/ – Next.js App Router with UI under components/ and page layouts, plus serverless API routes under app/api/.
• lib/ – shared utilities: DB (Drizzle ORM), auth, permissions, webhook helper, schema definitions.
• config/ & hooks/ – runtime config loaders and custom React hooks.
• drizzle.config.ts, drizzle/ – database migration scripts and metadata snapshots for D1 via Drizzle ORM.
• workers/ – two standalone workers:
• email-receiver.ts handles inbound email via Cloudflare Email Routing.
• cleanup.ts performs scheduled purging of expired mailboxes/messages.
• scripts/ – CLI tools for test data generation, local/remote migrations, and local webhook test server.
• public/ – static assets & PWA manifest.
• .github/workflows/deploy.yml – GitHub Actions for CI/CD: migrations, Pages, and Workers deployment.
• **wrangler*.toml** – Cloudflare Worker configuration examples.
Main Components & Responsibilities
A. Frontend (Cloudflare Pages)
• React UI with SSR/SSG via Next.js App Router
• Theme provider, layout, forms, dialogs, pages for home, login, profile, mailbox views
• Calls Next.js API routes (fetch/browser) or direct fetch for OpenAPI endpoints with X‑API‑Key header
B. API Layer (Next.js Serverless)
• Under app/api/: REST endpoints for auth (NextAuth/GitHub), email generation, listing, deletion, message retrieval, roles management, config retrieval, Webhook setup, API key CRUD
• Uses lib/db.ts (Drizzle ORM) to query Cloudflare D1
• Reads/Writes settings in KV (via lib/utils.ts)
C. Data Layer
• Cloudflare D1 (SQLite) – primary store for users, roles, API keys, mailboxes, messages
• Cloudflare KV – key‑value storage for site‑wide settings (DEFAULT_ROLE, email domains, max emails…)
D. Workers Microservices
1. Email Receiver Worker
• Triggered by inbound mail routing in Cloudflare Email Routing
• Parses email, writes to D1, triggers configured Webhooks (HTTP POST)
2. Cleanup Worker
• Scheduled (cron) Worker that removes expired mailboxes/messages from D1
3. Webhook Test Server (local, via scripts/webhook-test-server.ts)
E. External Integrations
• GitHub OAuth for user authentication
• Cloudflare Email Routing
• User‑provided Webhook endpoints
• GitHub Actions or Wrangler CLI for automated deployments
Relationships & Data Flows
• User’s browser ↔ Frontend UI (Next.js)
• Frontend → Next.js API → D1 / KV / NextAuth
• Inbound email → Cloudflare Email Routing → Email Receiver Worker → D1 → Webhook HTTP POST → User’s external service
• Cron Scheduler → Cleanup Worker → D1
• Admin (Emperor) UI → API → KV to update global settings
• GitHub Actions / Wrangler → Deploy Pages + Workers + Migrations
Architectural Patterns & Principles
• Separation of Concerns: UI, API, data, and background processing separated into distinct layers/services.
• Serverless & Edge: All compute (UI SSR, API, Workers) runs on Cloudflare’s edge.
• Event‑Driven: Email receiver reacts to mail events; cleanup runs on schedule.
• Role‑Based Access Control: RBAC implemented in API layer, enforced via middleware.
• Infrastructure as Code: Wrangler and GitHub Actions automate deployments.
Essential Elements
• Component boundaries (Pages vs. Workers)
• Authentication flow via NextAuth/GitHub
• Data interactions with D1 and KV
• Email reception and cleanup pipelines
• Deployment triggers (GitHub Actions / Wrangler)
• Role management & API Key issuance