# riskymh/emailthing architecture

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

- Interactive diagram: https://gitdiagram.com/riskymh/emailthing
- Repository: https://github.com/riskymh/emailthing

## Overview

##### Project type and purpose
- This is a full‑stack monorepo centered on email management (“EmailThing”).
- It contains two front‑ends:
– A PWA built with Bun + React/JSX (apps/pwa)
– A Next.js web app (apps/web)
- It also includes back‑end/serverless code:
– Next.js API routes under apps/web/app/api
– Cloudflare Email Workers for inbound (receive‑email) and outbound (send‑email)
- A shared database layer (packages/db) using Drizzle ORM + SQLite/Turso
- A CLI/SDK package (packages/emailthing) and helper scripts for setup

##### File structure
- Top‑level “apps” folder holds two separate front‑ends (pwa, web).
- “apps/web/app/api” contains REST/cron/debug/internal/v0 endpoints.
- “cloudflare-workers” houses standalone worker scripts for email ingest/send.
- “packages/db” exports schema, queries, and Drizzle config – consumed by both front‑ends and API.
- “packages/emailthing” provides a CLI and SDK for interacting with your email API.
- “scripts” includes administrative setup (create‑admin).
- CI/CD manifests: .github/workflows, bun.lock, package.json at root.

##### README for additional insights
- The Web UI and PWA call Cloudflare Email Workers to receive incoming mail and MailChannels (or custom workers) to send.
- Data persistence is in SQLite or Turso, via Drizzle.
- Service‑worker based notifications, S3 for attachments, DKIM, JWT tokens, and S3 environment variables.
- Local dev uses “bun db:push” and “bun dev --turbo” to spin up both front‑ends and API.

– UI → API → DB
– UI → API v0/send → Worker → MailChannels/S3
– Worker → API v0/receive-email → DB → UI (via Web Push)
– Blue for Clients
– Green for API/Serverless
– Orange for Data/Storage
– Purple for External Services

##### Detail
- Every logical component (PWA, web, API submodules, workers, packages, scripts).
- Don’t just show “Back‑end” – break it out into API routes, Workers, Cron jobs.
- Your shared modules (packages/db, packages/emailthing) and how they plug into each consumer.
- Configuration sources (env vars, bun scripts) as annotations if helpful.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Clients Layer
    subgraph "Clients"
        PWA["PWA Client"]:::clients
        Web["Web Client"]:::clients
    end

    %% API Layer
    subgraph "API Layer"
        subgraph "Next.js API Routes"
            APIInternal["API Internal Endpoints"]:::api
            APIV0["API v0 Endpoints"]:::api
            APICron["API Cron Jobs"]:::api
            APIDebug["API Debug/Info"]:::api
            APIGH["API GitHub Webhook"]:::api
        end
        subgraph "Serverless Email IO"
            CFRecv["Cloudflare Worker Receive Email"]:::api
            CFRecvMany["Cloudflare Worker Receive Bulk"]:::api
            CFSend["Cloudflare Worker Send Email"]:::api
        end
    end

    %% Data & Storage Layer
    subgraph "Data & Storage"
        DB["Database (Drizzle ORM)"]:::data
        S3["S3 Attachments Storage"]:::data
    end

    %% Shared Modules
    subgraph "Shared Modules"
        DBPkg["packages/db"]:::shared
        EmailPkg["packages/emailthing"]:::shared
        Scripts["scripts/create-admin"]:::shared
    end

    %% External Services
    subgraph "External Services"
        SMTP["Inbound SMTP"]:::ext
        MailChan["MailChannels SMTP"]:::ext
        CFEmailRoute["Cloudflare Email Routing"]:::ext
        WebPush["Web Push Notifications"]:::ext
    end

    %% Connections
    PWA -->|"REST/API calls"| APIInternal
    PWA -->|"v0 Email I/O"| APIV0
    Web -->|"REST/API calls"| APIInternal
    Web -->|"v0 Email I/O"| APIV0

    APIV0 -->|"send email"| CFSend
    CFSend -->|"SMTP"| MailChan

    SMTP --> CFRecv
    SMTP --> CFRecvMany
    CFEmailRoute --> CFRecv
    CFEmailRoute --> CFRecvMany

    CFRecv -->|"POST /receive-email"| APIV0
    CFRecvMany -->|"POST /receive-many"| APIV0

    APIV0 -->|"DB queries"| DB
    APIInternal -->|"DB queries"| DB
    APICron -->|"cleanup jobs"| DB

    DB -->|"notify"| WebPush
    WebPush --> PWA
    WebPush --> Web

    EmailPkg -->|"SDK/API automation"| APIV0

    DBPkg --> DB
    DBPkg --> APIInternal
    DBPkg --> APIV0
    DBPkg --> CFRecv
    DBPkg --> CFRecvMany

    Scripts --> DB

    APIDebug --> DB
    APIGH --> DB

    %% Click Events
    click PWA "https://github.com/riskymh/emailthing/tree/main/apps/pwa"
    click Web "https://github.com/riskymh/emailthing/tree/main/apps/web"
    click APIInternal "https://github.com/riskymh/emailthing/tree/main/apps/web/app/api/internal"
    click APIV0 "https://github.com/riskymh/emailthing/tree/main/apps/web/app/api/v0"
    click APICron "https://github.com/riskymh/emailthing/tree/main/apps/web/app/api/cron"
    click APIDebug "https://github.com/riskymh/emailthing/tree/main/apps/web/app/api/debug"
    click APIGH "https://github.com/riskymh/emailthing/tree/main/apps/web/app/api/github"
    click CFRecv "https://github.com/riskymh/emailthing/blob/main/cloudflare-workers/receive-email.js"
    click CFRecvMany "https://github.com/riskymh/emailthing/blob/main/cloudflare-workers/receive-email-many.js"
    click CFSend "https://github.com/riskymh/emailthing/blob/main/cloudflare-workers/send-email.js"
    click DBPkg "https://github.com/riskymh/emailthing/tree/main/packages/db"
    click EmailPkg "https://github.com/riskymh/emailthing/tree/main/packages/emailthing"
    click Scripts "https://github.com/riskymh/emailthing/blob/main/scripts/create-admin.ts"

    %% Styles
    classDef clients fill:#cce5ff,stroke:#333,stroke-width:1px
    classDef api fill:#d4edda,stroke:#333,stroke-width:1px
    classDef data fill:#fff3cd,stroke:#333,stroke-width:1px
    classDef ext fill:#E6E0F8,stroke:#333,stroke-width:1px
    classDef shared fill:#e2e3e5,stroke:#333,stroke-width:1px
```
