$ show Gururagavendra/gmail-cleaner
Gmail Cleaner is a self-hosted, privacy-focused web application for bulk Gmail management. It allows users to unsubscribe from mailing lists, delete emails by sender, mark emails as read, archive, and manage labels—all via a FastAPI backend with a vanilla JavaScript frontend. The architecture follows a modular service layer: each Gmail operation (scan, delete, mark-read, unsubscribe, etc.) lives in its own file under `app/services/gmail/`, coordinated by an in-memory `AppState` singleton. Background tasks handle long-running operations, and the frontend polls status endpoints to show progress. Authentication uses Google OAuth 2.0 with two modes (local desktop web server and manual URL copy for Docker). The tool is designed to run 100% locally, with no external data collection, and uses batch Gmail API requests (100 per call) for efficiency. The codebase includes comprehensive unit tests, integration test plans, and CI/CD via GitHub Actions.
The LLM identified 4 files worth highlighting for reuse:
Central module that re-exports all Gmail service functions (scan, delete, mark_read, archive, labels, important, download, unsubscribe). Demonstrates a clean service layer facade, decoupling the API layer from Gmail API implementation details. Reusable as a template for modularizing external API clients.
Defines `AppState`, a singleton-like in-memory state holder for tracking scan results, delete progress, mark-read status, etc. Each operation type has a dedicated dict with reset methods. This pattern is directly extractable for any application requiring lightweight, non-persistent background task state with polling endpoints.
Handles the full OAuth 2.0 flow for Google Gmail API, including credential loading from file or environment variable, token storage, and service object generation. The `get_gmail_service()` function encapsulates the entire auth lifecycle. Reusable as a reference implementation for Google API authentication in Python, with explicit support for both local and containerized environments.
Provides utility functions for building Gmail batch requests, constructing query filters (combining date, size, sender, label, category), and parsing batch responses. The `build_query()` function and batch request helper are reusable for any Gmail API project needing efficient bulk operations.