How useplunk/plunk works
Project type and purpose
• Plunk is a full-stack, self-hosted email platform (“Open-Source Email Platform”) that provides transactional emails, automations, and broadcasts. It comprises:
• A REST/HTTP API service for handling email requests, user/project management, automations, and webhooks
• A Next.js-based dashboard (UI) for end-users to configure and monitor email activities
• Shared utilities, database schema (Prisma), and deployment/configuration assets
• Integrations with AWS SES for sending mail, SNS for inbound webhooks, and Redis for caching/queues
File structure
• Top-level:
• deployment/ (nginx, entry scripts, variable replacement)
• docker-compose.dev.yml, Dockerfile, .dockerignore for containerization
• prisma/ (schema and migrations; backs a PostgreSQL or MySQL instance)
• packages/monorepo (managed by Lerna + Yarn v4)
• packages/api: Node.js service (app.ts, controllers, services, middleware). Uses Prisma, Redis, SES, JWT auth, Cron jobs.
• packages/dashboard: Next.js UI (pages, components, hooks, styles). Calls the API under the hood (/pages/api/health).
• packages/shared: Shared TypeScript types/utilities used by both API and dashboard.
• Configuration: biome.json, tsconfig.json (root), package.json, lerna.json
README for additional insights
• Emphasizes AWS SES, self-hosting via Docker
• Mentions features (transactional, automations, broadcasts) which map to API services (ActionService, CampaignService, etc.) and UI screens
a. Main components
• User’s Browser / Dashboard (Next.js React app)
• API Service (Node/Express or similar, app.ts)
• Database (PostgreSQL/MySQL via Prisma)
• Cache/Queue (Redis)
• External Email Provider (AWS SES)
• External SNS for incoming webhooks
• Cron Scheduler (internal in API)
• Reverse Proxy (Nginx container)
b. Relationships and interactions
1. Browser ↔ Nginx (HTTPS) ↔ Dashboard
2. Dashboard → API (REST calls)
3. API → Database (Prisma ORM)
4. API → Redis (cache tasks, rate-limit, pub/sub)
5. API → AWS SES (send emails via SES SDK)
6. AWS SNS → API Webhooks Incoming Controller (SNS.ts)
7. Cron tasks (in API) → trigger automations via internal services → enqueue/send via SES
c. Architectural patterns/design principles
• Monorepo (code sharing via shared package)
• Layered API pattern (controllers → services → util/database)
• MVC-style separation in the API (controllers vs services vs middleware)
• Component-based design in UI (Next.js pages, React components, hooks)
• Infrastructure as containerized microservices (API + Dashboard behind Nginx)
d. Key technologies/frameworks/libraries
• Node.js, TypeScript, Prisma ORM, Express/Koa-style app
• Next.js, React, Tailwind CSS, postcss
• Redis, Docker, Docker Compose
• AWS SES & SNS SDK, JSON Web Tokens (auth)
• Lerna & Yarn Berry (monorepo tooling)
Detail without over-splitting
• Cron scheduler as a subcomponent of API.
• That Prisma migrations drive the schema.