MailPilot ✈️

AI-Controlled Gmail Client — Built for the Processity.ai hiring challenge.

Unlike a chatbot that just talks, MailPilot's AI controls the UI. It opens compose windows, fills fields, navigates folders, applies filters, and sends emails — all visible in real-time.

---

✨ Key Features

Feature	Description
🔐 Google OAuth	Secure Gmail integration with readonly, send, and modify scopes
📨 Inbox & Sent	Two-column dashboard with list view + detail pane
✍️ Compose	Slide-out drawer with To, CC, Subject, and rich body fields
🤖 AI Assistant	CopilotKit sidebar powered by Gemini — natural language → UI actions
🛡️ Human-in-the-Loop	AI must request confirmation before sending emails
🔄 Real-time Sync	SSE push notifications for instant inbox updates
🎯 Smart Filtering	AI-driven search, unread filters, and keyword matching
📱 Mobile Responsive	Adaptive layout with full-screen detail overlay on small screens
🧪 Mock Mode	Works fully offline — no Google credentials needed to evaluate

---

🏗️ Architecture

User → CopilotKit Sidebar → Gemini LLM → Function Calling
                                              ↓
                                    TypeScript Actions Layer
                                              ↓
                                       Zustand Store
                                              ↓
                                     React UI Re-renders

The AI never manipulates the DOM directly. Every action updates the global Zustand state, which React renders reactively. This makes the system deterministic, testable, and predictable.

---

🛠 Tech Stack

• Framework: Next.js 16 (App Router)
• Language: TypeScript
• State: Zustand
• Styling: Tailwind CSS v4
• UI Components: shadcn/ui
• AI: CopilotKit + Google Gemini
• Auth: NextAuth.js v5 (Auth.js)
• Gmail: Google APIs Client Library
• Testing: Vitest

---

🚀 Quick Start

1. Clone & Install

git clone https://github.com/Utkarsh9571/mailpilot.git
cd mailpilot
npm install

2. Configure Environment

Copy the example environment file:

cp .env.example .env.local

For Mock Mode (no Google account needed):

• Just add your GEMINI_API_KEY from Google AI Studio
• Leave AUTH_GOOGLE_ID and AUTH_GOOGLE_SECRET blank

For Live Gmail Mode:

• Follow the complete setup guide in SETUP_REQUIRED.md

3. Run

npm run dev

Open http://localhost:3000.

4. Test

npm run test:run

---

💬 AI Commands to Try

Command	What Happens
"Go to sent folder"	Navigates to /sent view
"Compose email to john@example.com with subject Hello"	Opens compose drawer, fills fields
"Send this email"	Triggers human-in-the-loop confirmation dialog
"Show only unread emails"	Applies unread filter to the list
"Open the latest email from Sarah"	Finds matching email, opens detail view
"Reply to this saying I'll review it today"	Opens reply draft with pre-filled content
"Search for meeting"	Filters emails by keyword

---

📁 Project Structure

src/
├── actions/          # Pure TS functions (compose, send, filter, navigate...)
├── app/              # Next.js App Router pages & API routes
│   ├── api/          # Backend endpoints (gmail, copilot, auth, realtime)
│   ├── inbox/        # Inbox page
│   ├── sent/         # Sent page
│   └── email/[id]/   # Email detail page
├── components/       # React UI components
│   ├── assistant/    # CopilotKit bindings & confirmation dialog
│   ├── mail/         # Navbar, list, detail, compose, filters
│   └── ui/           # shadcn/ui primitives
├── services/         # Gmail API / Mock data service layer
├── store/            # Zustand state stores
└── types/            # TypeScript interfaces

---

📋 Documentation

• SETUP_REQUIRED.md — Full Google Cloud setup walkthrough
• TESTING.md — Manual QA verification checklist

---

License

MIT