# useplunk/plunk architecture

> Architecture diagram of the GitHub repository useplunk/plunk, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/useplunk/plunk
- Repository: https://github.com/useplunk/plunk

## Overview

##### 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.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User and UI Layer
    Browser["User's Browser"]:::frontend
    Nginx["Reverse Proxy (Nginx)"]:::infra
    Dashboard["Dashboard (Next.js UI)"]:::frontend

    %% API Layer
    subgraph "API Service (Node/Express)"
        Controllers["API Controllers"]:::backend
        Services["Business Services"]:::backend
        Cron["Cron Scheduler"]:::backend
        Controllers -->|calls| Services
        Cron -->|triggers| Services
    end

    %% Data Stores & External
    Database["Database<br/>(PostgreSQL/MySQL)"]:::database
    Redis["Cache/Queue<br/>(Redis)"]:::database
    SES["AWS SES"]:::external
    SNS["AWS SNS"]:::external

    %% Interactions
    Browser -->|HTTPS| Nginx
    Nginx -->|serves UI| Dashboard
    Dashboard -->|REST API calls| Controllers
    Services -->|ORM queries| Database
    Services -->|cache/pub-sub| Redis
    Services -->|send email| SES
    SNS -->|webhook POST| Controllers

    %% Click Events
    click Nginx "https://github.com/useplunk/plunk/blob/main/deployment/nginx.conf"
    click Nginx "https://github.com/useplunk/plunk/blob/main/deployment/entry.sh"
    click Nginx "https://github.com/useplunk/plunk/blob/main/deployment/replace-variables.sh"
    click Dashboard "https://github.com/useplunk/plunk/tree/main/packages/dashboard/src/pages"
    click Dashboard "https://github.com/useplunk/plunk/tree/main/packages/dashboard/src/components"
    click Dashboard "https://github.com/useplunk/plunk/tree/main/packages/dashboard/src/lib/hooks"
    click Dashboard "https://github.com/useplunk/plunk/blob/main/packages/dashboard/src/lib/network.ts"
    click Dashboard "https://github.com/useplunk/plunk/blob/main/packages/dashboard/src/layouts/Dashboard.tsx"
    click Controllers "https://github.com/useplunk/plunk/tree/main/packages/api/src/controllers"
    click Cron "https://github.com/useplunk/plunk/blob/main/packages/api/src/app/cron.ts"
    click Services "https://github.com/useplunk/plunk/tree/main/packages/api/src/services"
    click Services "https://github.com/useplunk/plunk/blob/main/packages/api/src/util/ses.ts"
    click Services "https://github.com/useplunk/plunk/blob/main/packages/api/src/services/redis.ts"
    click Controllers "https://github.com/useplunk/plunk/blob/main/packages/api/src/controllers/Webhooks/Incoming/SNS.ts"
    click Database "https://github.com/useplunk/plunk/blob/main/prisma/schema.prisma"

    %% Styles
    classDef frontend fill:#e0f7e9,stroke:#2e7d32,stroke-width:1px;
    classDef backend fill:#e3f2fd,stroke:#1565c0,stroke-width:1px;
    classDef database fill:#fff3e0,stroke:#ef6c00,stroke-width:1px;
    classDef infra fill:#eceff1,stroke:#607d8b,stroke-width:1px;
    classDef external fill:#ffebee,stroke:#c62828,stroke-width:1px;
```
