# izadoesdev/mailer architecture

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

- Interactive diagram: https://gitdiagram.com/izadoesdev/mailer
- Repository: https://github.com/izadoesdev/mailer

## Overview

##### Project type and purpose
- Mailbuddy is a full‑stack, serverless web application: a secure, privacy‑focused email client built on Next.js. It features a React‑based UI (Once UI + TailwindCSS), Next.js API routes as the backend, Prisma ORM with PostgreSQL (and vector storage) as the database layer, and integrations with Gmail’s API and external AI services for smart categorization and search.

##### File structure
- Top‑level: Next.js config files (next.config.mjs), environment (.env.example), Prisma schema, API routes under `src/app/api` and `src/api`, UI under `src/app` and `src/components`, a custom UI library under `src/once-ui`, utility libraries under `src/libs` (auth, db, query, utils, vector), and tests.
- The `src/app` directory uses the Next.js App Router: layout, pages, client and server components are organized by route groups (`(auth)`, `(dev)`, `(main)`, `(secondary)`).
- API routes live in `src/app/api/...` for public/edge routes and in `src/api/...` for server functions. They include authentication, email sync, background‑sync, calendar, contacts, and AI endpoints.
- Prisma files under `prisma/` define your data model and migrations.

##### README for additional insights
- Confirms a zero‑knowledge architecture: all encryption happens client‑side (in `src/libs/utils/encryption.ts` and in auth helpers).
- Tech stack: Next.js (App Router + API routes), React, Once UI, TailwindCSS, Prisma ORM, PostgreSQL + vector storage, BetterAuth, Gmail API, AI/ML (semantic search, categorization).

##### Elements
- Blue = Client‑side components
- Green = Server/API
- Orange = Database & Storage
- Purple = External services

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client Layer"
        direction TB
        Browser["Client Browser"]:::client
        UI["Next.js Frontend (App Router pages & layouts)"]:::client
        Encryption["Encryption Module"]:::client
    end

    %% Server Layer
    subgraph "Server Layer"
        direction TB
        API["Next.js API Layer (Serverless Functions)"]:::server
        AuthModule["Auth Module"]:::server
        AISvc["Business Logic / AI Module"]:::server
        Sync["Background Sync Module"]:::server
    end

    %% Database Layer
    subgraph "Database Layer"
        direction TB
        Postgres["PostgreSQL (Prisma)"]:::db
        Vector["Vector Store"]:::db
    end

    %% External Services
    subgraph "External Services"
        direction TB
        Gmail["Gmail API"]:::external
        AIProvider["AI Provider"]:::external
    end

    %% Data Flows
    Browser -->|"interact"| UI
    UI -->|"encrypt/decrypt"| Encryption
    UI -->|"HTTPS calls (encrypted)"| API

    API -->|"authenticate"| AuthModule
    AuthModule -->|"OAuth handshake"| Gmail
    Gmail -->|"tokens"| AuthModule

    API -->|"CRUD emails"| Postgres
    API -->|"store embeddings"| Vector

    Sync -->|"fetch new emails"| Gmail
    Gmail -->|"email data"| Sync
    Sync -->|"store encrypted emails"| Postgres
    Sync -->|"index embeddings"| Vector
    API -->|"trigger sync"| Sync

    AISvc -->|"categorize/search"| AIProvider
    AIProvider -->|"response data"| AISvc
    AISvc -->|"update index"| Vector

    %% Click Events
    click UI "https://github.com/izadoesdev/mailer/blob/master/src/app/layout.tsx"
    click UI "https://github.com/izadoesdev/mailer/blob/master/src/app/page.tsx"
    click UI "https://github.com/izadoesdev/mailer/tree/master/src/components"
    click Encryption "https://github.com/izadoesdev/mailer/blob/master/src/libs/utils/encryption.ts"
    click AuthModule "https://github.com/izadoesdev/mailer/blob/master/src/libs/auth/index.ts"
    click AuthModule "https://github.com/izadoesdev/mailer/blob/master/src/libs/auth/client.ts"
    click Sync "https://github.com/izadoesdev/mailer/blob/master/src/app/api/background-sync/route.ts"
    click AISvc "https://github.com/izadoesdev/mailer/blob/master/src/app/(dev)/ai/new/ai.ts"
    click Postgres "https://github.com/izadoesdev/mailer/blob/master/prisma/schema.prisma"
    click Vector "https://github.com/izadoesdev/mailer/blob/master/src/libs/vector.ts"
    click Gmail "https://github.com/izadoesdev/mailer/blob/master/src/app/api/utils/getFromGmail.ts"
    click AIProvider "https://github.com/izadoesdev/mailer/blob/master/src/app/(dev)/ai/new/utils/openrouter.ts"

    %% Styles
    classDef client fill:#D0EFFF,stroke:#333,stroke-width:1px
    classDef server fill:#D0FFD0,stroke:#333,stroke-width:1px
    classDef db fill:#FFDFA0,stroke:#333,stroke-width:1px
    classDef external fill:#E0C0FF,stroke:#333,stroke-width:1px
```
