# unsend-dev/unsend architecture

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

- Interactive diagram: https://gitdiagram.com/unsend-dev/unsend
- Repository: https://github.com/unsend-dev/unsend

## Overview

##### Project Type and Purpose
- This project is a full-stack application designed for managing and sending emails via Amazon SES. Its features include a web dashboard for transactional and marketing emails, REST APIs, a dedicated SMTP server for email processing, and extensive documentation. It is built to support email campaigns, contact management, scheduling, and eventual expansion to other messaging protocols.
- The README and file structure reveal multiple “apps” (e.g., “apps/web” for the dashboard, “apps/marketing” for the landing site, “apps/smtp-server” for SMTP support, “apps/docs” for documentation) and several internal packages (SDKs, UI components, email-editor, etc.) that support different aspects of the system.

##### File Structure – Key Observations
- Top-Level Apps:
- apps/web: This is the main dashboard and backend API. It uses Next.js and includes API endpoints (using NextAuth.js for authentication, tRPC for RPC APIs, and hono for exposing public API endpoints) and also integrates with Prisma (database migrations, schema) and Redis (queue/process management).
- apps/marketing: Hosts the marketing website, built with Next.js, showcasing integration code and static pages.
- apps/smtp-server: Contains a dedicated SMTP server implementation (node-based) for handling incoming SMTP requests.
- apps/docs: Contains extensive documentation with several “.mdx” files covering API references, getting started guides, and more.
- Docker and Deployment:
- The docker directory includes Dockerfiles and associated scripts for building and running the project in both development and production environments.
- Packages:
- packages/email-editor: An advanced email editor based on TipTap and jsx-email libraries.
- packages/sdk, packages/ui, packages/tailwind-config, etc.: These modules provide common libraries for the email sending functionality, UI elements, and configuration shared across the apps.

##### Extracting Additional Insights from the README
- The project explicitly mentions integration with Amazon SES, REST API capabilities, and a public dashboard that shows metrics (delivered, opened, clicked, etc.).
- It emphasizes components such as email editing (using jsx-email and tiptap), API endpoints (with tRPC and hono), and infrastructure components (Redis, Prisma ORM, NextAuth).

##### Main Components
a. User-Facing Applications and Dashboards:
- Dashboard (apps/web): Next.js web application; houses API routes, NextAuth integration, tRPC modules, and internal server components (e.g., campaign-service, domain-service, email-service).
- Marketing Website (apps/marketing): Next.js-based public marketing site.
- Documentation Portal (apps/docs): Provides API references and guides.

b. Backend Services:
- SMTP Server (apps/smtp-server): Processes and dispatches emails via Amazon SES.
- Public API Service: Exposed through hono framework (inside apps/web/src/server/public-api) for external integrations and callbacks.
- Queue/Worker System: Represented by Redis (apps/web/src/server/redis and the queue modules) that process jobs like email sending.

c. Data Management and External Dependencies:
- Database: Managed via Prisma (apps/web/prisma) – handles email logs, campaigns, contacts, domains, etc.
- External Services: Amazon SES (for sending emails) and SNS (for notifications); these are integrated in the modules under apps/web/src/server/aws.
- Authentication: Handled via NextAuth.js within the web app for both user and API session management.

d. Shared Libraries / Packages:
- Email Editor and SDK: Include packages/email-editor and packages/sdk that encapsulate core email editing and formatting functionality.
- UI Components: packages/ui provides styled, reusable UI elements across the applications.
- Configuration and Standards: packages/tailwind-config and packages/typescript-config ensure consistent styling and coding practices.

##### Relationships and Interactions
- API Gateway / Backend Server (apps/web): Connecting with the database (Prisma), external APIs (SES, SNS), and internal queues (Redis).
- SMTP Server (apps/smtp-server): Acting as a dedicated service that connects with the SES API while also interacting with scheduling and queue services.
- Public API (via hono in apps/web) for external callbacks.
- Shared libraries (SDK, Email Editor, UI) as auxiliary components that support the system.
- From the Dashboard UI to the API endpoints and authentication layer.
- From API endpoints to the database and Redis queues.
- From the SMTP server to external services (Amazon SES, SNS).
- From the email editor package to the Dashboard (where users design emails).
- From the public API to external clients.

##### Architectural Patterns and Design Principles
- Separation of Concerns: Separate apps for marketing, dashboard, SMTP server, and docs.
- Microservices / Modular Architecture: Although within one repository, the components are organized modularly (apps and packages) to isolate business logic, UI, and email processing.
- API Gateway Pattern: The apps/web acts as the central API server, handling authentication via NextAuth and request routing via tRPC.
- Developer Extensibility: The email editor and SDK packages expose core functionality for customization or reuse in other systems.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User-Facing Applications
    subgraph "User-Facing Applications"
        D["Dashboard (Next.js, NextAuth, tRPC)"]:::ui
        M["Marketing Website (Next.js)"]:::ui
        DOC["Documentation Portal (MDX)"]:::ui
    end

    %% Backend Services
    subgraph "Backend Services"
        API["API Endpoints & Authentication"]:::backend
        DB["Database (Prisma)"]:::database
        Q["Queue/Worker & Redis"]:::backend
        AWS["AWS Integrations (SES, SNS)"]:::external
        PAPI["Public API (hono)"]:::backend
        SMTP["SMTP Server (Node.js)"]:::backend
    end

    %% Shared Packages
    subgraph "Shared Packages"
        EE["Email Editor"]:::shared
        SDK["SDK"]:::shared
        UIComp["UI Components"]:::shared
        CONF["Styling & Configuration"]:::shared
    end

    %% External Services (Represented as external components)
    SES["Amazon SES"]:::externalService
    SNS["SNS"]:::externalService
    EXT["External Clients"]:::externalService

    %% Relationships
    D -->|"calls"| API
    API -->|"queries"| DB
    API -->|"sendsJobs"| Q
    API -->|"integrates"| AWS
    API -->|"exposes"| PAPI
    API -->|"triggers"| SMTP

    SMTP -->|"dispatches"| AWS

    AWS -->|"sendsEmails"| SES
    AWS -->|"notifies"| SNS

    PAPI -->|"receivesCalls"| EXT

    D -->|"uses"| EE
    D -->|"uses"| SDK
    D -->|"renders"| UIComp

    %% Classes
    classDef ui fill:#fef9c7,stroke:#333,stroke-width:2px;
    classDef backend fill:#bbf7d0,stroke:#333,stroke-width:2px;
    classDef database fill:#fca5a5,stroke:#333,stroke-width:2px;
    classDef external fill:#dbeafe,stroke:#333,stroke-width:2px;
    classDef shared fill:#ddd6fe,stroke:#333,stroke-width:2px;
    classDef externalService fill:#fcd34d,stroke:#333,stroke-width:2px;

    %% Click Events (Paths from component mapping)
    click D "https://github.com/unsend-dev/unsend/tree/main/apps/web"
    click API "https://github.com/unsend-dev/unsend/tree/main/apps/web/src/app/api"
    click PAPI "https://github.com/unsend-dev/unsend/tree/main/apps/web/src/server/public-api"
    click DB "https://github.com/unsend-dev/unsend/tree/main/apps/web/prisma"
    click Q "https://github.com/unsend-dev/unsend/tree/main/apps/web/src/server/queue"
    click Q "https://github.com/unsend-dev/unsend/blob/main/apps/web/src/server/redis.ts"
    click AWS "https://github.com/unsend-dev/unsend/tree/main/apps/web/src/server/aws"
    click SMTP "https://github.com/unsend-dev/unsend/tree/main/apps/smtp-server"
    click M "https://github.com/unsend-dev/unsend/tree/main/apps/marketing"
    click DOC "https://github.com/unsend-dev/unsend/tree/main/apps/docs"
    click EE "https://github.com/unsend-dev/unsend/tree/main/packages/email-editor"
    click SDK "https://github.com/unsend-dev/unsend/tree/main/packages/sdk"
    click UIComp "https://github.com/unsend-dev/unsend/tree/main/packages/ui"
    click CONF "https://github.com/unsend-dev/unsend/tree/main/packages/tailwind-config"
    click CONF "https://github.com/unsend-dev/unsend/tree/main/packages/typescript-config"
```
