A modern, intelligent email management application built with React.js that integrates with Gmail API, featuring AI-powered categorization, priority classification, smart search, and email summarization.

New to the project? Start here:

1. QUICK_START.md - 5-minute quick setup guide
2. SETUP_GUIDE.md - Complete detailed setup instructions

• Node.js (v18 or higher) - Download
• Python (v3.8 or higher) - Download
• Google Gemini API Key - Get one here

npm install

Create .env.local in the root directory:

VITE_GEMINI_API_KEY=your_gemini_api_key_here
VITE_EMAIL_INTELLIGENCE_API_BASE=http://localhost:8000

# Optional: Gmail Proxy Service (Redis cache for faster performance)
# Set to http://localhost:3001 to enable, or leave empty to disable
# Requires Redis and Proxy Service to be running (see SETUP_GUIDE.md)
VITE_GMAIL_PROXY_URL=http://localhost:3001

cd email-intel-service
python3 -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -r requirements.txt
python train_priority_model.py  # First time only

Terminal 1 (AI Service):

cd email-intel-service
source venv/bin/activate
python -m uvicorn main:app --reload --host 0.0.0.0 --port 8000

Terminal 2 (Redis - Optional but Recommended):

# macOS: brew services start redis
# Linux: sudo systemctl start redis
# Or Docker: docker run -d -p 6379:6379 redis:7-alpine

Terminal 3 (Proxy Service - Optional, requires Redis):

cd gmail-proxy-service
npm install  # First time only
npm start

Terminal 4 (Frontend):

npm run dev

Note: Redis and Proxy Service are optional. The app works with just AI Service and Frontend, but Redis cache provides 10-50x faster performance. See REDIS_CACHE_SETUP.md for details.

Navigate to: http://localhost:5173

# Create .env file with VITE_GEMINI_API_KEY
docker-compose up --build

This will start all services:

• Frontend (port 5173)
• AI Service (port 8000)
• Proxy Service (port 3001) - Redis cache
• Redis (port 6379) - Cache storage

Access at: http://localhost:5173

• SETUP_GUIDE.md - Complete setup instructions with troubleshooting
• QUICK_START.md - Quick 5-minute setup guide
• PROJECT_SUMMARY.md - Complete project overview and features
• FUNCTIONS_REFERENCE.md - All functions documented
• ENVIRONMENT_VARIABLES.md - Complete environment variables reference
• REDIS_CACHE_SETUP.md - Redis cache setup and usage guide
• REDIS_CACHE_EXAMPLES.md - How Redis cache helps with examples

• 🤖 AI-Powered Classification: Automatic priority (High/Medium/Low) and category labeling
• 📧 Gmail Integration: Full OAuth 2.0 integration with Gmail API
• 🔍 AI Search: Natural language search queries
• 📝 Email Summarization: One-line AI summaries for each email
• ⚡ Performance: IndexedDB caching, incremental sync (90%+ API reduction)
• 🚀 Redis Cache: Server-side caching for 10-50x faster responses (optional)
• 🎨 Modern UI: Gmail-like interface with dark/light themes
• 📱 Responsive: Works on desktop and mobile
• 🔄 Background Sync: Automatic 30-second sync
• 💾 Offline Support: Works with cached data

• Frontend: React 19 + Vite (Port 5173)
• AI Service: Python FastAPI microservice (Port 8000)
• Proxy Service: Node.js Express with Redis caching (Port 3001, optional)
• Cache: Redis (Port 6379, optional) + IndexedDB (browser)
• AI: DistilBERT model + Google Gemini API
• Storage: IndexedDB (browser) + localStorage
• APIs: Gmail API, Gemini API

┌──────────┐      ┌──────────────┐      ┌──────┐      ┌──────────┐
│ Frontend │─────▶│ Proxy Service│─────▶│Redis │      │Gmail API │
│  (5173)  │      │   (3001)     │      │(6379)│      │          │
└──────────┘      └──────────────┘      └──────┘      └──────────┘
      │                     │                                │
      └─────────────────────┴────────────────────────────────┘
                    (fallback to direct Gmail API)

┌──────────┐
│AI Service│
│  (8000)  │
└──────────┘

Note: Proxy Service and Redis are optional. The app works without them but with better performance when enabled.

# Frontend development
npm run dev

# Build for production
npm run build

# Preview production build
npm run preview

Mailflow-AI/
├── src/                    # React frontend
├── email-intel-service/    # Python AI microservice
├── gmail-proxy-service/    # Node.js Redis proxy service (optional)
├── .env.local             # Environment variables (create this)
├── package.json           # Node.js dependencies
├── docker-compose.yml     # Docker configuration (includes Redis + Proxy)
└── README.md             # This file

See SETUP_GUIDE.md for detailed troubleshooting guide.

Common issues:

• Port conflicts: Change ports in commands or .env files
• API errors: Check your Gemini API key
• Connection errors: Ensure services are running
• Redis/Proxy issues: See REDIS_CACHE_SETUP.md for troubleshooting

This project is for educational/demonstration purposes.

• Google Gmail API
• Google Gemini API
• Hugging Face Transformers
• React Community

For detailed setup instructions, see SETUP_GUIDE.md