{"id":32940369,"url":"https://github.com/gtovar/email-cleaner-fastify","last_synced_at":"2026-04-11T09:03:21.959Z","repository":{"id":323270698,"uuid":"1092602608","full_name":"gtovar/email-cleaner-fastify","owner":"gtovar","description":"AI-powered Gmail cleaner built with Fastify (Node.js), FastAPI (Python ML) and n8n automation — documented with MkDocs Material.","archived":false,"fork":false,"pushed_at":"2025-11-09T06:12:22.000Z","size":176,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"docs/bootstrap","last_synced_at":"2025-11-09T07:13:31.561Z","etag":null,"topics":["ai-classification","automation","documentation","email-cleaner","fastapi","fastify","github-actions","gmail","machine-learning","microservices","mkdocs","mkdocs-material","monorepo","n8n","nodejs","python"],"latest_commit_sha":null,"homepage":"https://gtovar.github.io/email-cleaner-fastify/","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/gtovar.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":"docs/roadmap.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-08T23:45:01.000Z","updated_at":"2025-11-09T06:28:15.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/gtovar/email-cleaner-fastify","commit_stats":null,"previous_names":["gtovar/email-cleaner-fastify"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/gtovar/email-cleaner-fastify","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gtovar%2Femail-cleaner-fastify","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gtovar%2Femail-cleaner-fastify/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gtovar%2Femail-cleaner-fastify/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gtovar%2Femail-cleaner-fastify/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gtovar","download_url":"https://codeload.github.com/gtovar/email-cleaner-fastify/tar.gz/refs/heads/docs/bootstrap","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gtovar%2Femail-cleaner-fastify/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":284013226,"owners_count":26932440,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-11-12T02:00:06.336Z","response_time":59,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-classification","automation","documentation","email-cleaner","fastapi","fastify","github-actions","gmail","machine-learning","microservices","mkdocs","mkdocs-material","monorepo","n8n","nodejs","python"],"created_at":"2025-11-12T10:00:36.320Z","updated_at":"2025-11-12T10:01:45.841Z","avatar_url":"https://github.com/gtovar.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"📘 Full docs: https://gtovar.github.io/email-cleaner-fastify/\n\n# 🧩 Email Cleaner \u0026 Smart Notifications\n\n[![Docs](https://img.shields.io/badge/docs-MkDocs%20Material-brightgreen)](https://gtovar.github.io/email-cleaner-fastify/)\n[![Pages](https://github.com/gtovar/email-cleaner-fastify/actions/workflows/docs.yml/badge.svg)](../../actions/workflows/docs.yml)\n\n\nAn intelligent system that automatically classifies your emails, prioritizes what truly matters, and alerts you when action is needed.  \nBuilt with **Fastify (Node.js)** for backend logic, **FastAPI (Python)** for machine learning, and **n8n** for smart automation.\n\n---\n\n## 🚀 Overview\n\nManaging dozens of emails daily can easily lead to **decision fatigue** and **loss of focus**.  \nThis system connects securely to Gmail, classifies messages with ML models, and filters what deserves your attention.\n\n---\n\n## 🧠 Core Features\n\n- **Smart Classification** — NLP-based categorization of incoming emails.  \n- **Priority Notifications** — Only alerts you for messages that matter.  \n- **Seamless Gmail Integration** — OAuth2-based secure connection.  \n- **Multi-service Architecture** — Node.js backend + Python ML microservice.  \n- **Automation-ready** — n8n workflows for Telegram or Slack notifications.\n\n---\n\n## 🧱 Architecture Overview\n\n| Layer           | Technology         | Purpose                          |\n| --------------- | ------------------ | -------------------------------- |\n| Frontend        | React + Vite       | Web interface and control panel  |\n| Backend API     | Fastify (Node.js)  | Business logic and orchestration |\n| ML Microservice | FastAPI (Python)   | Email classification engine      |\n| Database        | PostgreSQL         | Data persistence                 |\n| Infrastructure  | Docker + Cloud Run | Deployment and scalability       |\n\n---\n\n## ⚙️ Setup Instructions\n\n\u003e ⚠️ **Requirements:** Node.js ≥ 20.0  •  Python ≥ 3.10  •  Docker (optional)  \n\u003e Ensure you have both environments active before running the backend and ML microservice.\n\n### 1. Clone the Repository\n\n```bash\ngit clone https://github.com/gtovar/email-cleaner-fastify.git\ncd email-cleaner-fastify\n```\n\n### 2. Environment Setup\n\nCopy the environment example and fill in your Gmail credentials:\n\n```bash\ncp .env.example .env\n```\n\n### 3. Install Dependencies\n\n**Backend:**\n```bash\nnpm install\n```\n\n**ML Microservice:**\n```bash\ncd python/classifier\npython -m venv venv\nsource venv/bin/activate\npip install -r requirements.txt\n```\n\n### 4. Run the Services\n\n**Fastify Backend:**\n```bash\nnpm run dev\n# http://localhost:3000\n```\n\n**Python Classifier (FastAPI):**\n```bash\nuvicorn main:app --reload --port 8000\n# http://localhost:8000/docs\n```\n\n### 5. Database\n```bash\nnpm run db:migrate\nnpm run db:seed      # opcional\n# rollback:\nnpm run db:rollback  # opcional\n```\n\n### 6. Docker (local)\n\n```bash\n  docker compose -f ops/docker-compose.yml up --build\n```\n\n### Smoke test\n```bash\ncurl -s http://localhost:3000/api/v1/health/db\ncurl -s http://localhost:3000/api/v1/notifications/summary -H \"Authorization: Bearer dummy\"\ncurl -s http://localhost:3000/api/v1/notifications/history -H \"Authorization: Bearer dummy\"\n```\n\n## Repository layout\n\n- src/                    # Fastify app (API v1)\n- python/classifier/      # FastAPI microservice (ML)\n- migrations/             # Sequelize migrations \u0026 seeds\n- ops/\n  └─ docker-compose.yml   # Orquestación local (DB, n8n, Fastify, FastAPI)\n- docs/                   # Fuente de la documentación (MkDocs)\n- .github/workflows/      # CI/CD (GitHub Actions)\n- README.md               # Guía principal (fuente de verdad junto con docs/)\n\n### Environment variables\n| Variable | Descripción | Obligatoria | Ejemplo |\n|---|---|---:|---|\n| DATABASE_URL | Cadena de conexión PostgreSQL | Sí | postgres://user:pass@localhost:5432/email_cleaner |\n| DB_HOST | Host de la base | No* | 127.0.0.1 |\n| DB_PORT | Puerto DB | No* | 5432 |\n| DB_USERNAME | Usuario DB | No* | postgres |\n| DB_PASSWORD | Password DB | No* | secret |\n| DB_DATABASE | Nombre DB | No* | email_cleaner |\n| GOOGLE_CLIENT_ID | OAuth 2.0 Client ID | Sí | xxx.apps.googleusercontent.com |\n| GOOGLE_CLIENT_SECRET | OAuth 2.0 Client Secret | Sí | supersecret |\n| GOOGLE_REDIRECT_URI | Redirect (OAuth) | Sí | http://localhost:3000/oauth/google/callback |\n| INTERNAL_JWT_SECRET| Inter-service / Security | No | xxxxx|\n| FASTAPI_URL | URL del microservicio ML | Sí | http://localhost:8000 |\n| PORT | Puerto del backend | Sí | 3000 |\n| N8N_WEBHOOK_URL | Webhook para pruebas | No | http://localhost:5678/webhook/telegram-test |\n| TELEGRAM_BOT_TOKEN | Telegram | No | xxxxx |\n\n\u003e *Usa `DATABASE_URL` o los `DB_*`. No ambos a la vez.\n⚠️ Los endpoints que consultan Gmail (`/mails`, `/suggestions`) requieren un token Google válido.\nPara probar sin OAuth real, use el flujo de **Notificaciones** con un token dummy (`Authorization: Bearer dummy`).\n\n## 🧠 Especificación oficial de la API\nLa documentación de la API se genera directamente desde el código (esquemas definidos en las rutas y en `src/index.js`) y se muestra en **/docs** al ejecutar el servidor.\n\n---\n\n### OAuth modes\n- `OAUTH_MODE=mock` → flujo simulado (recomendado si aun no tienes configurado GCP OAuth)\n- `OAUTH_MODE=google` → requiere configurar GCP OAuth (ver docs/operations/oauth-google.md).\n  - `GOOGLE_CLIENT_ID`\n  - `GOOGLE_CLIENT_SECRET`\n  - `GOOGLE_REDIRECT_URI` (p. ej., `http://localhost:3000/oauth/google/callback`)\n  - Pasos detallados: ver `docs/operations/oauth-google.md`.\n\n\u003e Nota: El modo `mock` se implementará en una iteración futura. Por ahora solo se documenta el comportamiento deseado para asegurar reproducibilidad en local sin secretos.\n\n\n## 🧪 Testing the Pipeline\n\nTo test classification end-to-end:\n\n```bash\ncurl -X POST http://localhost:3000/api/v1/emails/classify -H \"Content-Type: application/json\" -d '{\"from\": \"invoices@cfe.mx\", \"subject\": \"Your electricity bill is ready\", \"body\": \"Due date: November 15. Amount: $350.\"}'\n```\n\nExpected result:\n```json\n{\n  \"category\": \"Finance/Utilities/CFE\",\n  \"action\": \"archive\",\n  \"confidence\": 0.93\n}\n```\n\n**Trigger notification test:**  \nTests Telegram notification webhook from n8n flow.\n\n```bash\ncurl -X POST http://localhost:5678/webhook/telegram-test\n```\n\n---\n\n## 📦 Related Documentation\n\n| File                     | Description                           |\n| ------------------------ | ------------------------------------- |\n| [Design Document.md](docs//DESIGN_DOCUMENT.md) | Technical architecture and key decisions |\n| [API Reference.md](docs/API_REFERENCE.md) | REST endpoints and examples |\n| [architecture.md](docs/architecture.md) | REST endpoints and examples |\n| [despliegue-cloudrun.md](docs/despliegue-cloudrun.md) | Deployment guide for Google Cloud Run | \n| [migraciones.md](docs/migraciones.md) | Sequelize migration workflow |\n| [seeders.guia.md](docs/seeders.guia.md) | Load initial or reference data |\n\n📘 **Full documentation:** [https://gtovar.github.io/email-cleaner-fastify/](https://gtovar.github.io/email-cleaner-fastify/)\n\n---\n\n## 🧰 Tech Stack Summary\n\n- **Backend:** Node.js (Fastify), PostgreSQL  \n- **ML Service:** Python (FastAPI, scikit‑learn)  \n- **Infra:** Docker, Cloud Run, Secret Manager  \n- **Notifications:** n8n + Telegram integration  \n- **CI/CD:** GitHub Actions (build + deploy + lint)  \n- **Monitoring:** ELK Stack / Prometheus (optional phase 4)\n\n---\n\n## 🧾 Maintainers\n\nMaintained by **Gilberto Tovar**  \n📧 contacto@gilbertotovar.com  \n🌐 [www.gilbertotovar.com](https://www.gilbertotovar.com)\n\n---\n\n## 🧩 Developer Tools\n\n**pre-commit hook:** updates the \"Last updated\" footer automatically.\n\n```bash\nsed -i \"s/Last updated:.*/Last updated: $(date '+%B %Y')/\" README.md\n```\n\n---\n\n**Last updated:** November 2025\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgtovar%2Femail-cleaner-fastify","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgtovar%2Femail-cleaner-fastify","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgtovar%2Femail-cleaner-fastify/lists"}