# elie222/inbox-zero architecture

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

- Interactive diagram: https://gitdiagram.com/elie222/inbox-zero
- Repository: https://github.com/elie222/inbox-zero

## Overview

##### Main components
- Frontend (apps/web) – Next.js React app serving UI and client-side logic.
- Serverless API (apps/web/api) – Next.js API routes handling user actions, Gmail integration, AI requests, reply tracking, cleanup, etc.
- Background services
– Unsubscriber (apps/unsubscriber) – standalone Node process for bulk-unsubscribe jobs.
– mcp-server (apps/mcp-server) – minimal compute proxy for long-running tasks (optional).
- Data stores
– PostgreSQL (Prisma) – primary relational store for users, rules, history, settings.
– Redis (Upstash or local) – queues, real-time state (categorization progress, reply-tracker).
– Tinybird analytics – event ingestion & query engine for email analytics.
- External integrations
– Gmail API (via Google Pub/Sub webhook & REST calls)
– OAuth (NextAuth + Google)
– LLM providers (OpenAI, Anthropic, Ollama, etc.)
– Third-party email service (Resend)
– Payment/webhook (LemonSqueezy)

##### Relationships and data flow
- User → Browser → Next.js Frontend → Next.js API
- API → Prisma client → PostgreSQL
- API → Redis → job queues → background services
- API/Background → Gmail API (via Pub/Sub or REST)
- API/Background → LLM provider for AI-driven actions
- Email events (Pub/Sub webhook) → Next.js API → Redis/DB
- Analytics events → Tinybird
- Payment/webhooks → Next.js API → DB

##### Architectural patterns
- Monorepo (Turborepo + pnpm workspaces)
- Serverless first (Next.js API routes) augmented by small Node workers
- CQRS-style separation: API for commands/queries, Redis queues for tasks
- Externalized AI layering: all “intelligence” calls go through a unified AI-utils module
- Prisma for schema-driven migrations and type safety

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Layer
    User["User"]:::external
    User --> Frontend

    %% Web App
    subgraph "Web App"
        Frontend["Next.js Frontend"]:::frontend
        API["Next.js API"]:::api
    end

    %% Background Workers
    subgraph "Background Workers"
        Unsubscriber["Unsubscriber Service"]:::worker
        MCP["MCP-Server Worker"]:::worker
    end

    %% Data Stores
    subgraph "Data Stores"
        PostgreSQL["PostgreSQL (Prisma)"]:::db
        Redis["Redis Queues & State"]:::db
    end

    %% External Integrations
    subgraph "External Services"
        Gmail["Gmail API"]:::external
        OAuth["OAuth (NextAuth)"]:::external
        LLM["LLM Providers"]:::external
        Resend["Resend Email Service"]:::external
        Tinybird["Tinybird Analytics"]:::external
        Lemon["LemonSqueezy Webhooks"]:::external
    end

    %% Core Flows
    Frontend -->|"API Calls"| API
    API -->|"Reads/Writes"| PostgreSQL
    API -->|"Push to Queue"| Redis
    API -->|"Auth Requests"| OAuth
    API -->|"Gmail REST"| Gmail
    API -->|"AI Requests"| LLM
    API -->|"Send Emails"| Resend
    API -->|"Analytics Events"| Tinybird
    API -->|"Payment Webhook"| PostgreSQL

    Gmail -->|"Pub/Sub Webhook"| API
    API -->|"Enqueue Event"| Redis

    Redis -->|"Process Clean"| Unsubscriber
    Redis -->|"Process Tasks"| MCP

    Unsubscriber -->|"Bulk Unsubscribe"| Gmail
    MCP -->|"Long-Running Tasks"| LLM

    %% Click Events
    click Frontend "https://github.com/elie222/inbox-zero/tree/main/apps/web"
    click API "https://github.com/elie222/inbox-zero/tree/main/apps/web/app/api"
    click Unsubscriber "https://github.com/elie222/inbox-zero/blob/main/apps/unsubscriber/src/main.ts"
    click MCP "https://github.com/elie222/inbox-zero/blob/main/apps/mcp-server/src/index.ts"
    click PostgreSQL "https://github.com/elie222/inbox-zero/blob/main/apps/web/prisma/schema.prisma"
    click Redis "https://github.com/elie222/inbox-zero/blob/main/apps/web/utils/upstash/index.ts"
    click Gmail "https://github.com/elie222/inbox-zero/tree/main/apps/web/app/api/google"
    click OAuth "https://github.com/elie222/inbox-zero/blob/main/apps/web/app/api/auth/[...nextauth]"
    click LLM "https://github.com/elie222/inbox-zero/blob/main/apps/web/utils/llms/index.ts"
    click Resend "https://github.com/elie222/inbox-zero/blob/main/packages/resend/src/index.ts"
    click Tinybird "https://github.com/elie222/inbox-zero/blob/main/packages/tinybird-ai-analytics/src/client.ts"
    click Lemon "https://github.com/elie222/inbox-zero/blob/main/apps/web/app/api/lemon-squeezy/webhook/route.ts"

    %% Styles
    classDef frontend fill:#cce5ff,stroke:#337ab7;
    classDef api fill:#d4edda,stroke:#28a745;
    classDef worker fill:#fff3cd,stroke:#ffb822;
    classDef db fill:#e2e3e5,stroke:#6c757d;
    classDef external fill:#f8d7da,stroke:#dc3545;
```
