# pradeepkaswan/inbox-zero architecture

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

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

## Overview

##### Main Components
- Frontend Client: Represented by the “apps/web” directory. This is a Next.js-based frontend that manages the user interface (UI), including pages for onboarding, email actions, analytics, and settings.
- API/Backend Server: Also part of “apps/web” (using Next.js API routes) and “apps/unsubscriber” for specific services. This handles server-side logic (e.g., handling API endpoints, executing actions with email data, and integrating with the LLM).
- Database Layer: The project uses Postgres (managed via Prisma migrations in the “apps/web/prisma” folder) to store user data, emails, categories, and configuration settings.
- Caching/Queue Services: Upstash Redis (and the option to use Docker Compose for Redis) to manage caching, real-time email triggers, and queueing for tasks like emailing actions or tracking.
- External Services:
- Google APIs for OAuth, Gmail operations, PubSub (push notifications), and Contacts.
- OpenAI (or alternative LLM providers such as Anthropic and Ollama) for the AI personal assistant functions.
- Tinybird for data analytics and email statistics.
- Additional Libraries/Packages: Several packages in the “packages” directory (such as tinybird, resend, loops, etc.) provide shared functionality and utility methods related to email actions, API connectivity, and analytics.

##### Relationships and Interactions
- The Client (web browser) communicates with the Next.js frontend, which renders pages and invokes API routes.
- API routes handle requests from the client and coordinate with internal modules to interact with external services (Google, OpenAI, Tinybird) and the Postgres database via Prisma.
- The system interacts with external email services through dedicated endpoints (for instance, the Gmail API for sending, archiving, or processing emails, which are well represented in the “apps/web/app/api/google/*” directories).
- LLM interactions for AI assistant functions occur via specific APIs (e.g., ai-categorize, ai-reply) that are defined both as part of the Next.js backend and within utility modules.
- Caching and message queuing are managed via integration with Upstash Redis (or a local Redis instance via Docker Compose) to buffer tasks and manage session data.

##### Architectural Patterns and Designs
- Monorepo Structure: The project employs a monorepo (using Turborepo and pnpm workspaces) to consolidate the apps and shared packages. This helps in modularizing the frontend, backend, and shared libraries.
- Separation of Concerns: Clear separation exists between the presentation layer (frontend pages and components in “apps/web/app”), the domain/business logic (in API routes and utility functions scattered across “apps/web/app/api” and “apps/unsubscriber”), and data access layer (Prisma and migrations in “apps/web/prisma”).
- API-centric and Microservice-Like Routing: API endpoints are organized by functionality (e.g., authentication, Gmail operations, AI tasks), which resemble microservices even though they reside within a single Next.js app.
- Use of Modern Tools: Adoption of Next.js for SSR/SSG rendering, Tailwind CSS for styling, Prisma for ORM, and integration with external services for extended functionalities.

##### Detailed Components
- Frontend (apps/web): Next.js pages, components, and client-side hooks.
- Backend API Endpoints: Controllers for Gmail, auth, AI actions, user settings, bulk unsubscribe, etc.
- Services & Utilities: Describe shared packages (like tinybird, resend, loops) connecting with external API endpoints.
- Middleware and Providers: Show how global state providers (e.g., for session, SWR, compose modal, analytics) wrap the application.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation Layer
    subgraph "Presentation Layer"
        Client["Web Client"]:::internal
        Frontend["Next.js Frontend"]:::internal
        Client -->|"UI_interaction"| Frontend
    end

    %% Application Layer
    subgraph "Application Layer"
        API["API/Backend Server (Next.js API & Unsubscriber)"]:::internal
        Shared["Shared Packages (resend, loops)"]:::auxiliary
        Frontend -->|"API_request"| API
        API -->|"UsesUtilities"| Shared
    end

    %% Data Layer
    subgraph "Data Layer"
        DB["Postgres Database (Prisma)"]:::database
    end

    %% External Services Layer
    subgraph "External Services"
        Google["Google APIs (OAuth, Gmail, PubSub, Contacts)"]:::external
        AI["AI/LLM Module"]:::external
        Redis["Redis Cache/Queue"]:::external
        Analytics["Tinybird Analytics"]:::external
    end

    %% Connections from Application Layer to Data and External Services
    API -->|"DB_Query"| DB
    API -->|"Email_Ops"| Google
    API -->|"AI_Request"| AI
    API -->|"Cache_Queue"| Redis
    API -->|"Analytics_Data"| Analytics

    %% Click Events
    click Frontend "https://github.com/pradeepkaswan/inbox-zero/tree/main/apps/web/app"
    click API "https://github.com/pradeepkaswan/inbox-zero/tree/main/apps/web/app/api"
    click API "https://github.com/pradeepkaswan/inbox-zero/tree/main/apps/unsubscriber/src"
    click DB "https://github.com/pradeepkaswan/inbox-zero/tree/main/apps/web/prisma"
    click Redis "https://github.com/pradeepkaswan/inbox-zero/tree/main/apps/web/utils/redis"
    click Redis "https://github.com/pradeepkaswan/inbox-zero/tree/main/apps/web/store"
    click Google "https://github.com/pradeepkaswan/inbox-zero/tree/main/apps/web/app/api/google"
    click AI "https://github.com/pradeepkaswan/inbox-zero/tree/main/apps/web/utils/ai"
    click AI "https://github.com/pradeepkaswan/inbox-zero/blob/main/apps/unsubscriber/src/llm.ts"
    click Analytics "https://github.com/pradeepkaswan/inbox-zero/tree/main/packages/tinybird"
    click Analytics "https://github.com/pradeepkaswan/inbox-zero/tree/main/packages/tinybird-ai-analytics"
    click Shared "https://github.com/pradeepkaswan/inbox-zero/tree/main/packages/resend"
    click Shared "https://github.com/pradeepkaswan/inbox-zero/tree/main/packages/loops"

    %% Styles
    classDef internal fill:#bbdefb,stroke:#1e88e5,stroke-width:2px;
    classDef external fill:#c8e6c9,stroke:#388e3c,stroke-width:2px;
    classDef database fill:#ffe082,stroke:#f57f17,stroke-width:2px;
    classDef auxiliary fill:#d1c4e9,stroke:#7e57c2,stroke-width:2px;
    class Client,Frontend,API,Shared internal
    class DB database
    class Google,AI,Redis,Analytics external
```
