Classmate 🧠📧

A distributed, event-driven email automation platform

Classmate is a microservices-based automation platform that lets users create email-triggered workflows (“flows”).
It continuously monitors Gmail, routes events through a message bus, and executes actions such as saving attachments to Google Drive or setting reminders — all in a scalable, decoupled way.

Think of it as Zapier-style automation, but purpose-built for Gmail and designed with modern backend architecture principles.

---

✨ Features

• 📬 Gmail-triggered workflows
• ⚙️ Event-driven architecture using Kafka
• 🧩 Microservices with clear separation of concerns
• 🔐 Google OAuth 2.0 for secure Gmail access
• 📦 Prisma ORM for database access
• 🐳 Dockerized services for easy deployment
• 🧠 Extensible action system (add new automations easily)

---

🏗️ System Architecture Overview

Classmate is built as a distributed system composed of multiple independent services:

High-level flow

1. User creates automation flows via the Frontend UI
2. Flow definitions are stored by the Backend API
3. Gmail is monitored via:
   • Poller Service (periodic polling)
   • Hooks Service (webhook ingestion)
4. Events are published to Kafka
5. Processor Service routes and enriches events
6. Worker Service executes the final actions
7. State and metadata are stored in a central database

---

📂 Repository Structure

.
├── frontend/        # Next.js UI
├── backend/         # API server (flows, auth)
├── poller/          # Gmail polling service
├── hooks/           # Webhook ingestion service
├── processor/       # Kafka event processor
├── worker/          # Action executor
├── docker-compose.yml
└── README.md

Architecture Diagram

🧩 Services Breakdown

1. Frontend (Next.js)

Path: frontend/

• User interface for managing flows
• Built with Next.js App Router
• Communicates with Backend API via REST

---

2. Backend API

Path: backend/

• Flow CRUD operations
• OAuth setup and token storage
• Central coordination layer
• Uses Prisma ORM for DB access

---

3. Poller Service

Path: poller/

• Periodically polls Gmail API
• Refreshes OAuth tokens
• Detects new emails/events
• Forwards events to Hooks or Kafka

---

4. Hooks Service

Path: hooks/

• Receives Gmail webhook notifications
• Validates and normalizes incoming events
• Publishes notifications to Kafka

---

5. Processor Service

Path: processor/

• Kafka consumer + producer
• Transforms raw events into actionable tasks
• Matches events against user-defined flows
• Publishes action messages

---

6. Worker Service

Path: worker/

• Executes automation actions
• Examples:
  • Save attachments to Google Drive
  • Set reminders
• Updates execution state in DB
• Interacts with external APIs

---

🗄️ Data & Messaging

Database

• Central relational DB (PostgreSQL / MySQL)
• Accessed via Prisma
• Each service has its own Prisma schema
• Shared logical data model

Message Broker

• Apache Kafka
• Used for:
  • Event ingestion
  • Flow routing
  • Action execution
• Enables horizontal scalability and loose coupling

---

🌐 External Integrations

• Google OAuth 2.0
• Gmail API
• Google Calendar API
• Google Drive API

Token refresh logic is handled inside Poller and Worker services.

---