How pradeepkaswan/inbox-zero works
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.