How mail-0/zero works
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.”