# mail-0/zero architecture

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

- Interactive diagram: https://gitdiagram.com/mail-0/zero
- Repository: https://github.com/mail-0/zero

## Overview

##### Project Type and Purpose
- Zero is an open-source, self-hosted email application that serves as a Gmail alternative. It leverages AI for email automation and offers integrations with external email services (e.g., Gmail, Outlook).
- The project is a full-stack application built with Next.js/React on the frontend, Node.js and API routes on the backend, and uses PostgreSQL (with Drizzle ORM) for the database layer. Authentication is handled via Better Auth with additional support for Google OAuth (and optionally GitHub OAuth).

##### File Structure for Architectural Patterns
- The primary application is contained in the “apps/mail” directory. This folder includes:
- The Next.js “app” directory with subdirectories for authentication, error handling, various routes/pages (e.g., create, settings, mail components), and API endpoints. These indicate how the UI and backend routes are organized.
- The “actions” directory, which holds functions to process various email-related actions (e.g., ai-reply, notes, send, and utilities). This reflects the logic layer for handling individual email commands or features.
- Supporting directories such as “config”, “hooks”, and “lib” which represent configuration files, custom React hooks (for navigation, settings, and connection handling), and abstraction for authentication, email utilities, cookie handling, etc.
- The “packages” directory supports shared resources:
- “db” contains the schema, migrations, and Drizzle ORM configuration for PostgreSQL.
- “eslint-config” and “tailwind-config” show standardized styling and linting configurations.
- Additional configuration files (Docker, Dev Container, .env examples) reinforce containerized development and environment management.

##### Key Components
a. Frontend:
- UI Layers and React Components (pages, dynamic routes, and context providers).
- Separate modules such as authentication pages, error pages, and routing structures.
- Use of TailwindCSS and Shadcn UI for styling.
b. Backend/API:
- Authentication endpoints (Better Auth, OAuth integrations for Google and GitHub).
- Mail-specific endpoints (for creating, sending, and managing emails).
- AI and utility actions (from the “actions” folder).
c. Database:
- That migrations and schema management reside in “packages/db.”
d. Authentication and External Integrations:
- Components that handle Better Auth, Google OAuth, and optionally GitHub OAuth.
- External email integrations for Gmail/Outlook via API calls.
e. Development and Deployment Infrastructure:
- Docker-related services (.devcontainer, docker-compose.yaml) which indicate containerization for development.
- CI/CD integrations visible via .github/workflows.
f. Shared Utilities and Configuration:
- Components from “lib”, “hooks”, “config”, and “providers” for authentication context and global state.

##### Relationships and Interactions
- That the Backend uses Drizzle ORM to query and manage data in the PostgreSQL database.
- Communication between the authentication mechanism (Better Auth and OAuth providers) and both the frontend and backend.
- Interactions between external email services (Gmail API) and the backend.
- Caching or auxiliary services (like Redis, as referenced in the environment variables) if applicable to your deployment.

##### Incorporating Architectural Patterns and Technologies
- Since Zero is modular and based on Next.js, emphasize the separation between the frontend (React-based UI components) and backend (API routes and server utilities).
- Clearly label architectural patterns such as “server-side rendering” or “API routes” if needed.
- Nodes with key technologies: “Next.js”, “React”, “Node.js”, “Drizzle ORM”, “PostgreSQL”, “TailwindCSS”, “Better Auth”, “Google OAuth.”

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend Layer"
        A["Next.js Frontend"]:::frontend
        A1["UI Pages (apps/mail/app)"]:::frontend
        A2["UI Components (apps/mail/components)"]:::frontend
        A --> A1
        A --> A2
    end

    %% Backend/API Layer
    subgraph "Backend/API Layer"
        B["Next.js Server API"]:::backend
        B1["API Endpoints (apps/mail/app/api)"]:::backend
        B2["Email Actions & AI (apps/mail/actions)"]:::backend
        B --> B1
        B --> B2
    end

    %% Database Layer
    subgraph "Database Layer"
        C["PostgreSQL Database\n(Drizzle ORM)"]:::database
    end

    %% Authentication & External Integrations
    subgraph "Authentication & External"
        D["Authentication & OAuth"]:::auth
        D1["Auth Pages (apps/mail/(auth))"]:::auth
        D2["Auth Utilities (apps/mail/lib/auth)"]:::auth
        D3["Auth Providers (apps/mail/providers)"]:::auth
        D4["Email Services (Gmail/Outlook)"]:::external
        D --> D1
        D --> D2
        D --> D3
        D --> D4
    end

    %% Shared Utilities & Configuration
    subgraph "Shared Utilities & Configuration"
        E1["Configuration Files (apps/mail/config)"]:::utility
        E2["Constants (apps/mail/constants)"]:::utility
        E3["Custom Hooks (apps/mail/hooks)"]:::utility
        E4["Utility Functions (apps/mail/lib)"]:::utility
    end

    %% Development & Deployment Infrastructure
    subgraph "Development & Deployment"
        F1["Dev Container (.devcontainer)"]:::infra
        F2["Docker Compose (docker-compose.yaml)"]:::infra
        F3["CI/CD Workflows (.github/workflows)"]:::infra
    end

    %% Relationships and Data Flow
    A -->|"API_requests"| B
    B -->|"DB_queries"| C
    A -->|"Auth_request"| D1
    D1 -->|"Auth_response"| B
    B -->|"Invokes"| D2
    B -->|"Invokes"| D3
    B -->|"External_call"| D4

    %% Shared utilities support Frontend & Backend
    E1 --- A
    E2 --- A
    E3 --- A
    E4 --- B

    %% Development & Deployment supports Frontend & Backend
    F1 --- A
    F1 --- B
    F2 --- A
    F2 --- B
    F3 --- A
    F3 --- B

    %% Style Definitions
    classDef frontend fill:#f9e79f,stroke:#D35400,stroke-width:2px;
    classDef backend fill:#aed6f1,stroke:#2874A6,stroke-width:2px;
    classDef database fill:#abebc6,stroke:#239B56,stroke-width:2px,stroke-dasharray: 5 5;
    classDef auth fill:#f5cba7,stroke:#B9770E,stroke-width:2px;
    classDef external fill:#d5f5e3,stroke:#1E8449,stroke-width:2px;
    classDef utility fill:#d6eaf8,stroke:#2E86C1,stroke-width:2px;
    classDef infra fill:#e8daef,stroke:#6C3483,stroke-width:2px;

    %% Click Events
    click A1 "https://github.com/mail-0/zero/tree/staging/apps/mail/app"
    click A2 "https://github.com/mail-0/zero/tree/staging/apps/mail/components"
    click B1 "https://github.com/mail-0/zero/tree/staging/apps/mail/app/api"
    click B2 "https://github.com/mail-0/zero/tree/staging/apps/mail/actions"
    click C "https://github.com/mail-0/zero/tree/staging/packages/db"
    click D1 "https://github.com/mail-0/zero/tree/staging/apps/mail/(auth)"
    click D2 "https://github.com/mail-0/zero/tree/staging/apps/mail/lib/auth"
    click D3 "https://github.com/mail-0/zero/tree/staging/apps/mail/providers"
    click E1 "https://github.com/mail-0/zero/tree/staging/apps/mail/config"
    click E2 "https://github.com/mail-0/zero/tree/staging/apps/mail/constants"
    click E3 "https://github.com/mail-0/zero/tree/staging/apps/mail/hooks"
    click E4 "https://github.com/mail-0/zero/tree/staging/apps/mail/lib"
    click F1 "https://github.com/mail-0/zero/blob/staging/.devcontainer"
    click F2 "https://github.com/mail-0/zero/blob/staging/docker-compose.yaml"
    click F3 "https://github.com/mail-0/zero/tree/staging/.github/workflows"
```
