# dropocol/coldjot architecture

> Architecture diagram of the GitHub repository dropocol/coldjot, 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/dropocol/coldjot
- Repository: https://github.com/dropocol/coldjot

## Overview

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.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Global Entities
    User["User"]:::external

    %% Client Layer
    WebApp["Web Application (Next.js)"]:::frontend
    
    %% Service Layer
    MailOps["Mail Operations Service (Backend)"]:::backend
    
    %% Data Layer
    DB["PostgreSQL Database"]:::database
    Shared["Shared Types & Configurations"]:::util

    %% Caching & Queues Subgraph
    subgraph "Caching & Queues"
        QC["Queue Config"]:::queue
        RK["Redis Keys"]:::queue
        RC["Redis Connection"]:::queue
    end

    %% External Integrations Subgraph
    subgraph "External Integrations"
        GOOGLE_M["Google API (MailOps)"]:::external
        GOOGLE_W["Google API (Web)"]:::external
    end

    %% Relationships
    User -->|"uses"| WebApp
    WebApp -->|"API_calls"| MailOps
    WebApp -->|"CRUD_operations"| DB
    MailOps -->|"CRUD_operations"| DB
    MailOps -->|"job_processing"| QC
    MailOps -->|"job_processing"| RK
    MailOps -->|"job_processing"| RC
    WebApp -->|"OAuth_integration"| GOOGLE_W
    MailOps -->|"Google_integration"| GOOGLE_M
    WebApp -->|"uses_shared"| Shared
    MailOps -->|"uses_shared"| Shared

    %% Click Events
    click WebApp "https://github.com/dropocol/coldjot/tree/master/apps/web"
    click MailOps "https://github.com/dropocol/coldjot/tree/master/apps/mailops"
    click DB "https://github.com/dropocol/coldjot/tree/master/packages/database"
    click QC "https://github.com/dropocol/coldjot/blob/master/apps/mailops/src/config/queue/index.ts"
    click RK "https://github.com/dropocol/coldjot/blob/master/apps/mailops/src/config/redis/keys.ts"
    click RC "https://github.com/dropocol/coldjot/blob/master/apps/mailops/src/services/shared/redis/connection.ts"
    click GOOGLE_M "https://github.com/dropocol/coldjot/tree/master/apps/mailops/src/lib/google"
    click GOOGLE_W "https://github.com/dropocol/coldjot/tree/master/apps/web/src/lib/google"
    click Shared "https://github.com/dropocol/coldjot/tree/master/packages/types"

    %% Styles
    classDef frontend fill:#bbf,stroke:#333,stroke-width:2px;
    classDef backend fill:#bfb,stroke:#333,stroke-width:2px;
    classDef database fill:#ffdb58,stroke:#333,stroke-width:2px;
    classDef external fill:#f9c,stroke:#333,stroke-width:2px;
    classDef util fill:#ddd,stroke:#333,stroke-width:2px;
    classDef queue fill:#ffc,stroke:#333,stroke-width:2px;
```
