How dropocol/coldjot works
Based on both the provided file tree and the README, ColdJot is a full‐stack email automation platform. Its purpose is to streamline email operations by offering features such as email sequences, contact management, mailbox integrations (especially with Gmail), analytics, and job processing. The system is split primarily into two major applications—with a clear separation between the web (frontend) and mail operations (backend) services—and also includes packages for database interaction and shared TypeScript types.
Main Components
• Web Application (Frontend): Located in the apps/web directory, this runs on Next.js with TypeScript and Tailwind. It contains pages, APIs (e.g., authentication routes, admin routes), components (UI, email editor, sequences, contact management, etc.), and utilities for connecting to external services.
• Mail Operations Service (Backend): Found in apps/mailops, this service is responsible for background job processing (using BullMQ with Redis), handling email sending, integrations (Gmail, PubSub), and managing business logic such as sequencing and rate limiting.
• Database: The packages/database section shows migrations and Prisma schema definition, which configures PostgreSQL as the main data store.
• Caching & Queues: Redis is used for caching, session management, job queues, and rate limiting. Connections and related keys are defined in the configuration files.
• External Integrations: This includes Google integrations such as Gmail API and Google OAuth for authentication, as well as Cloud PubSub for receiving email reply notifications – these integrations are configured in the environment files and implemented in libraries (apps/mailops/src/lib/google and apps/web/src/lib/google).
• Shared Types & Configurations: The packages/types module holds shared type definitions that ensure consistency across the system.
Relationships and Interactions
• The Web Application interacts with end users—for activities like email composition, scheduling sequences, viewing analytics, and managing contacts. It communicates with the backend Mail Operations API over HTTP (e.g., apps/mailops endpoints).
• API calls and webhooks from the Web App forward data to the Mail Operations service that processes background jobs (e.g., sending emails, rate-limiting, scheduling).
• The Mail Operations service leverages job processing frameworks (likely BullMQ) and connects with Redis for queue management and caching.
• Both the Web App and Mail Ops connect to the PostgreSQL database managed through Prisma (with migrations and schema updates) for persistence of emails, sequences, contacts, user data, and tracking information.
• External APIs (Google OAuth, Gmail API, and PubSub endpoints) are integrated via dedicated libraries; these fuel authentication workflows, OAuth callbacks, and real-time email reply tracking.
Architectural Patterns and Design Principles
• Separation of Concerns / Microservices: The split between apps/web and apps/mailops allows the UI and core processing to evolve independently.
• Modular Design: With shared modules (packages/types, packages/database), cool integration layers (e.g., google, auth, queue libraries) and designed configuration files, each component is clearly isolated and testable.
• Asynchronous Processing: Background jobs (queue-based processing with BullMQ and Redis) ensure that email sending and rate limiting are handled asynchronously.
• External API Integration: The system relies on reliable OAuth flows and pub-sub designs to streamline third-party integrations, thus improving security and functionality.
Technologies, Frameworks, and Libraries
• Frontend: Next.js, React, TypeScript, Tailwind CSS.
• Backend: Node.js with TypeScript; job processing using BullMQ; REST APIs.
• Database: PostgreSQL (with Prisma ORM).
• Caching & Queues: Redis.
• External Services: Google APIs (Gmail, OAuth, Cloud PubSub) and ngrok (for tunneling during development).
• Monorepo and Build Tools: Turborepo for managing the monorepo structure.
Putting It All Together
On one side, add a block for Redis to illustrate job queues and caching. On the other side, include an “External Services” block that lists Google APIs (OAuth, Gmail, Cloud PubSub) and show their connections to both services.
Finally, represent shared libraries and configuration modules as ancillary notes to indicate that they underpin both the front and back ends.