# tusharthakur04/classmate architecture

> Architecture diagram of the GitHub repository tusharthakur04/classmate, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-02-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tusharthakur04/classmate
- Repository: https://github.com/tusharthakur04/classmate

## Overview

##### Project type and purpose
- This is a full-stack, microservices-based automation tool (“classmate”) that lets users define flows triggered by Gmail events and execute actions (save to Drive, set reminders, call Calendar API, etc.).
- Key use cases: OAuth onboarding, polling Gmail history, publishing events to a message bus (Kafka), processing flows, and executing actions in isolated worker containers.

##### File structure
Top-level directories each represent a service/component, all packaged as independent Docker containers:
- frontend: Next.js React UI for flow creation and dashboard
- backend: core API (user management, flow CRUD, OAuth endpoints)
- hooks: webhook registration service that receives event posts and writes to the database
- poller: long-polls the Gmail API, fetches new messages/history, and forwards events to hooks or Kafka
- processor: subscribes to Kafka, interprets flow definitions, and emits action tasks
- worker: executes individual actions (Gmail send, Drive upload, Calendar create, reminders)
Each service uses Prisma (schema.prisma) for DB access, and they share a central relational database. processor also integrates with Kafka as a message broker.

##### README
- The README is minimal, so we rely on controllers, routes, utils, and Prisma schemas to infer responsibility boundaries, API endpoints, and data flows.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend Layer"
        direction TB
        Frontend["Next.js UI"]:::frontend
    end

    %% API Layer
    subgraph "Backend Service"
        direction TB
        BackendAPI["Backend API"]:::api
        Controllers["Controllers"]:::api
        Routes["Routes"]:::api
        BackendPrisma["Prisma Schema"]:::database
        Controllers --> Routes
        Controllers --> BackendPrisma
        BackendAPI --> Controllers
        BackendAPI --> BackendPrisma
    end

    %% Hooks Service
    subgraph "Hooks Service"
        direction TB
        HooksAPI["Hooks API"]:::api
        HooksIndex["Entry Point"]:::api
        HooksRoutes["Routes"]:::api
        HooksPrisma["Prisma Schema"]:::database
        HooksIndex --> HooksRoutes
        HooksIndex --> HooksPrisma
        HooksAPI --> HooksIndex
    end

    %% Poller Service
    subgraph "Poller Service"
        direction TB
        PollerAPI["Poller API"]:::api
        PollerIndex["Entry Point"]:::api
        PollerUtils["Gmail Polling Utils"]:::api
        PollerPrisma["Prisma Schema"]:::database
        PollerIndex --> PollerUtils
        PollerIndex --> PollerPrisma
        PollerAPI --> PollerIndex
    end

    %% Processor Service
    subgraph "Processor Service"
        direction TB
        ProcessorAPI["Processor API"]:::api
        ProcessorIndex["Entry Point"]:::api
        ProcessorKafka["Kafka Integration"]:::broker
        ProcessorPrisma["Prisma Schema"]:::database
        ProcessorIndex --> ProcessorKafka
        ProcessorIndex --> ProcessorPrisma
        ProcessorAPI --> ProcessorIndex
    end

    %% Worker Service
    subgraph "Worker Service"
        direction TB
        WorkerAPI["Worker API"]:::api
        WorkerIndex["Entry Point"]:::api
        WorkerActions["Action Handlers"]:::api
        WorkerUtils["Utils (Drive/Calendar/Token)"]:::api
        WorkerPrisma["Prisma Schema"]:::database
        WorkerIndex --> WorkerActions
        WorkerIndex --> WorkerUtils
        WorkerIndex --> WorkerPrisma
        WorkerAPI --> WorkerIndex
    end

    %% Shared Infrastructure
    subgraph "Shared Infrastructure"
        direction TB
        Database[(PostgreSQL)]:::database
        Kafka[(Kafka Message Broker)]:::broker
    end

    %% External APIs
    subgraph "External Services"
        direction TB
        GmailAPI["Google Gmail API"]:::external
        DriveAPI["Google Drive API"]:::external
        CalendarAPI["Google Calendar API"]:::external
    end

    %% User Interaction
    User[("User")]:::external
    User -->|"HTTPS"| Frontend
    Frontend -->|"HTTPS"| BackendAPI

    %% OAuth Flow
    BackendAPI -->|"OAuth2"| GmailAPI
    GmailAPI -->|"OAuth2 Response"| BackendAPI
    BackendAPI --> Database

    %% Polling Flow
    PollerAPI -->|"HTTPS"| GmailAPI
    GmailAPI -->|"History ID"| PollerAPI
    PollerAPI -->|"HTTP POST"| HooksAPI
    PollerAPI -->|"Publish"| Kafka

    %% Hooks to DB
    HooksAPI --> Database

    %% Processor Flow
    ProcessorAPI -->|"Subscribe"| Kafka
    ProcessorAPI --> Database
    ProcessorAPI -->|"Publish Tasks"| Kafka

    %% Worker Flow
    WorkerAPI -->|"Subscribe Tasks"| Kafka
    WorkerAPI -->|"Gmail Call"| GmailAPI
    WorkerAPI -->|"Drive Upload"| DriveAPI
    WorkerAPI -->|"Calendar Call"| CalendarAPI
    WorkerAPI --> Database

    %% Database access from services
    BackendAPI --> Database
    HooksAPI --> Database
    PollerAPI --> Database
    ProcessorAPI --> Database
    WorkerAPI --> Database

    %% Click Events
    click Frontend "https://github.com/tusharthakur04/classmate/tree/main/frontend/"
    click BackendAPI "https://github.com/tusharthakur04/classmate/tree/main/backend/"
    click Controllers "https://github.com/tusharthakur04/classmate/tree/main/backend/src/controller/"
    click Routes "https://github.com/tusharthakur04/classmate/tree/main/backend/src/routes/"
    click BackendPrisma "https://github.com/tusharthakur04/classmate/blob/main/backend/prisma/schema.prisma"
    click HooksAPI "https://github.com/tusharthakur04/classmate/tree/main/hooks/"
    click HooksIndex "https://github.com/tusharthakur04/classmate/blob/main/hooks/src/index.ts"
    click HooksRoutes "https://github.com/tusharthakur04/classmate/blob/main/hooks/src/routes/flows.ts"
    click HooksPrisma "https://github.com/tusharthakur04/classmate/blob/main/hooks/prisma/schema.prisma"
    click PollerAPI "https://github.com/tusharthakur04/classmate/tree/main/poller/"
    click PollerIndex "https://github.com/tusharthakur04/classmate/blob/main/poller/src/index.ts"
    click PollerUtils "https://github.com/tusharthakur04/classmate/tree/main/poller/src/utils/"
    click PollerPrisma "https://github.com/tusharthakur04/classmate/blob/main/poller/prisma/schema.prisma"
    click ProcessorAPI "https://github.com/tusharthakur04/classmate/tree/main/processor/"
    click ProcessorIndex "https://github.com/tusharthakur04/classmate/blob/main/processor/src/index.ts"
    click ProcessorKafka "https://github.com/tusharthakur04/classmate/blob/main/processor/src/lib/kafka.ts"
    click ProcessorPrisma "https://github.com/tusharthakur04/classmate/blob/main/processor/prisma/schema.prisma"
    click WorkerAPI "https://github.com/tusharthakur04/classmate/tree/main/worker/"
    click WorkerIndex "https://github.com/tusharthakur04/classmate/blob/main/worker/src/index.ts"
    click WorkerActions "https://github.com/tusharthakur04/classmate/tree/main/worker/src/actions/"
    click WorkerUtils "https://github.com/tusharthakur04/classmate/tree/main/worker/src/utils/"
    click WorkerPrisma "https://github.com/tusharthakur04/classmate/blob/main/worker/prisma/schema.prisma"

    %% Styles
    classDef frontend fill:#AEDBFF,stroke:#0366d6,color:#000;
    classDef api fill:#C8E6C9,stroke:#388E3C,color:#000;
    classDef database fill:#FFF9C4,stroke:#FBC02D,color:#000;
    classDef broker fill:#FFE0B2,stroke:#F57C00,color:#000;
    classDef external fill:#E0E0E0,stroke:#9E9E9E,color:#000;
```
