Email Cleaner & Smart Notifications¶
System that connects to Gmail, classifies emails via ML, and triggers notifications when action is required.
Overview¶
Email Cleaner & Smart Notifications connects to your Gmail account using OAuth 2.0, classifies incoming messages via a FastAPI ML microservice, and orchestrates automation through n8n flows for Telegram or Slack alerts.
Architecture at a Glance¶
flowchart LR
A["Gmail API (OAuth2)"] --> B["Fastify Backend (Node.js)"]
B --> C["FastAPI Microservice (Python ML)"]
C --> D["PostgreSQL Persistence"]
D --> E["n8n / Telegram Notifications"]
Features¶
- Classification — Detects type and intent of each email.
- Priority filtering — Shows messages that match configured criteria.
- OAuth2 integration — No stored passwords or IMAP usage.
- Automation — Connect rules to n8n workflows.
- Modular architecture — Node.js <-> Python <-> Cloud Run.
Quick Start¶
-
Clone the repo
git clone https://github.com/gtovar/email-cleaner-fastify.git cd email-cleaner-fastify -
Configure environment
cp .env.example .env
| Variable | Description | Required | Example |
|---|---|---|---|
| DATABASE_URL | PostgreSQL connection string | Yes | postgres://user:pass@localhost:5432/email_cleaner |
| GOOGLE_CLIENT_ID | OAuth 2.0 Client ID | Yes | xxx.apps.googleusercontent.com |
| GOOGLE_CLIENT_SECRET | OAuth 2.0 Client Secret | Yes | supersecret |
| GOOGLE_REDIRECT_URI | Redirect (OAuth) | Yes | http://localhost:3000/auth/google/callback |
| INTERNAL_JWT_SECRET | Inter-service / security | No | xxxxx |
| TOKEN_ENCRYPTION_KEY | Encrypt OAuth tokens at rest (base64 32 bytes) | Yes | base64-32-bytes |
| ML_BASE_URL | ML microservice URL | Yes | http://localhost:8000 |
| PORT | Backend port | Yes | 3000 |
| PORT_HTTP | HTTP port | No | 3001 |
| N8N_WEBHOOK_URL | Webhook for tests | No | http://localhost:5678/webhook/telegram-test |
| TELEGRAM_BOT_TOKEN | Telegram | No | xxxxx |
-
Run locally (Node/Fastify)
npm install npm run dev # http://localhost:3000 -
Run ML microservice (Python/FastAPI)
cd python/classifier python -m venv venv source venv/bin/activate pip install -r requirements.txt uvicorn main:app --reload --port 8000 # http://localhost:8000/docs -
Database npm run db:migrate npm run db:seed (optional) npm run db:rollback (optional)
Test (ML suggestions direct):
curl -X POST http://localhost:8000/v1/suggest \
-H "Content-Type: application/json" \
-d '[{"id":"e1","from":"invoices@cfe.mx","subject":"Your electricity bill is ready","date":"2025-11-18T02:32:11.000Z","isRead":false,"category":"promotions","attachmentSizeMb":12.4}]'
- Open API docs
- Fastify API -> http://localhost:3000/docs
- FastAPI ML Service -> http://localhost:8000/docs
Documentation Index¶
| Section | Description |
|---|---|
| Design Document | Technical architecture and key decisions |
| Architecture Diagram | System data-flow diagrams |
| API Reference | REST endpoints and examples |
| Quickstart Guide | Run the project locally in minutes |
| Local Operations | Local environment setup (Docker/Host) |
| Google OAuth | Google OAuth configuration |
| Database Migrations | Sequelize migration workflow |
| Seeders Guide | Load initial or reference data |
| Deploy to Cloud Run | Cloud Build + Cloud Run deployment steps |
| Testing | Jest testing guide |
| Contribution Guide | Collaboration and commit standards |
| Events Contract | Event names, payloads, semantics and consumers |
| ADR Index | Architecture decisions and tradeoffs |
| Documentation Rules | Project-wide rules: canonical doc ownership, language/tone policy, and update protocols. |
| README Guide | README structure and maintenance guidance for the repository. |
| Project State Protocol | PROJECT_STATE template and update rules |
| Project State Fill Guide | Shared workspace contract and repo-specific rules for filling PROJECT_STATE.md. |
| Workflow | Development workflow |
| Git Hygiene | Working tree protocol |
| Documentation Styles | Visual and writing conventions for rendered technical documentation. |
| Roadmap | High-level roadmap placeholder |
| Scrum | Scrum process placeholder |
Technology Stack¶
| Layer | Technology | Purpose |
|---|---|---|
| Frontend | React + Vite | Dashboard and user control panel |
| Backend API | Fastify (Node.js) | Core business logic + REST services |
| ML Microservice | FastAPI (Python) | NLP classification engine |
| Database | PostgreSQL | Structured data storage |
| Infrastructure | Docker + Cloud Run | Reproducible and scalable deployments |
Maintainers¶
Maintained by Gilberto Tovar Email: contacto@gilbertotovar.com Web: www.gilbertotovar.com
Last updated: January 2026 — Architecture Team