How arunmadhavan-dev/gmailcopilot works
1. This is a Manifest V3 Chrome extension for Gmail, not a standalone web app. The core runtime is split between a Gmail-injected content script, a background service worker, and a floating React UI rendered inside Gmail.
2. The visible product surface is the floating assistant window in src/floating-ui and src/content. The content script mounts the assistant trigger and overlay into Gmail, while src/overlay ensures the UI is isolated with Shadow DOM so Gmail styles do not leak in or out.
3. The UI layer is mostly self-contained: React components, hooks, and a small client for extension messaging. Zustand is used for shared UI state, and Framer Motion handles open/close animation. The UI does not talk directly to Gmail or AI APIs; it asks the background worker to do that.
4. The background service worker in src/background is the main orchestration boundary. It receives runtime messages, routes them through specialized handlers, and owns privileged operations such as authentication, Gmail API access, and AI action execution. This is the main “backend” of the extension.
5. Authentication and Gmail access are separated into their own modules under src/gmail and src/background/services. Google OAuth is handled with the Chrome Identity API, token persistence/refresh is centralized in tokenService, and Gmail API operations live behind API wrappers like threads/profile access. The README’s “Load Inbox Threads” path is a proof that this boundary works.
6. The AI subsystem under src/ai is structured as a pipeline rather than one monolithic model call. User text is parsed into intent, classified into categories, optionally clarified, enriched with Gmail context, then executed through an engine registry/factory/executor. This makes action selection and execution explicit and testable.
7. The AI action set is intentionally small and Gmail-specific. The main handlers are searchEmails, archiveEmails, deleteEmails, and clarify, which suggests the product focuses on inbox triage and safe operations rather than open-ended chat. Ambiguous or low-confidence requests are routed toward clarification instead of immediate action.
8. Groq is the LLM provider abstraction in src/ai/groqClient, with prompt text, schemas, and JSON repair helpers supporting structured outputs. The presence of a workers/groq-proxy.js file suggests there is also an edge/proxy option for AI traffic, likely to keep credentials out of the extension runtime.
9. Confidence and safety are first-class parts of the AI design. src/ai/confidence, src/ai/schemas.ts, and the parser/error-handling utilities indicate that the system validates model output and gates execution based on confidence, which matters because the assistant can take destructive actions like deleting emails.
10. Query understanding is augmented with Gmail context. The src/ai/query modules and floating UI hooks like useGmailContextLabel imply the assistant can incorporate the current mailbox/context when interpreting search or action requests, improving relevance over pure natural-language parsing.
11. The repo also includes execution support for multi-step or batch behavior. Modules under src/ai/execution and src/ai/engine indicate there is a structured path from parsed intent to one or more concrete Gmail operations, with feedback hooks for refining future behavior or user response handling.
12. Tooling is strongly test-oriented. Unit tests live under src/test, end-to-end extension tests are under e2e, and coverage artifacts exist for the AI and Gmail modules. The build/test stack is Vite/Vitest plus Playwright, which fits an extension with both UI and browser-integration concerns.
13. From an architecture diagram perspective, the key boundaries are: Gmail page context, isolated overlay UI, extension background worker, Gmail API/OAuth, and the AI provider. The main data flow is user input in the floating UI → runtime message to background → AI parsing/execution and/or Gmail API call → result returned to the UI for display or follow-up clarification.
Main entry points: index.ts AI pipeline · runtimeMessageHandler.ts Runtime router · authHandlers.ts Auth handlers · executor.ts Execution engine
Components 24
Extension runtime
Chrome extension surfaces and orchestration boundaries inside Gmail.
- Content script · Mounts the assistant trigger and overlay into the Gmail page.
src/content/index.tsx - Shadow overlay · Creates an isolated host and injects overlay styles so Gmail CSS does not leak.
src/overlay/ensureOverlayHost.ts - Background worker · Manifest V3 service worker that receives messages and coordinates privileged work.
src/background/index.ts - Runtime router · Routes extension messages to AI, auth, and Gmail handlers.
src/background/handlers/runtimeMessageHandler.ts - Auth handlers · Handles login and token-related runtime requests.
src/background/handlers/authHandlers.ts - Gmail handlers · Handles privileged Gmail operations requested by the UI or AI layer.
src/background/handlers/gmailHandlers.ts - AI handlers · Coordinates AI intent and action requests inside the background worker.
src/background/handlers/aiHandlers.ts
AI pipeline
Intent parsing, confidence gating, execution planning, and provider access.
- AI pipeline · End-to-end intent parsing, classification, context enrichment, confidence checks, and execution.
src/ai/index.ts - Intent parser · Turns user text into structured intent and error-handled model output.
src/ai/parsers/intentParser.ts - Classifier · Assigns requests to Gmail-specific action categories.
src/ai/classification/classifier.ts - Context enrich · Augments requests with mailbox and thread context for better relevance.
src/ai/query/enhancer.ts - Confidence gate · Scores model output and blocks low-confidence or risky execution.
src/ai/confidence/calculator.ts - Execution engine · Resolves actions through registry, factory, and executor layers.
src/ai/engine/executor.ts - AI actions · Concrete Gmail-specific handlers such as search, archive, delete, and clarify.
src/ai/handlers/searchEmails.ts - Groq client · Provider abstraction for structured LLM requests and JSON repair.
src/ai/groqClient/client.ts - Groq proxy · Optional proxy path for AI traffic outside the extension runtime.
workers/groq-proxy.js
Gmail access
OAuth and Gmail API wrappers used by background actions.
- Token service · Centralizes Google OAuth token persistence and refresh.
src/background/services/tokenService.ts - Gmail auth · Wraps Chrome Identity-based OAuth flow for Gmail access.
src/gmail/auth/index.ts - Gmail API · Thread and profile access behind Gmail API helpers.
src/gmail/api/index.ts
Floating UI
React assistant UI injected into Gmail with isolated overlay support.
- Assistant window · Floating assistant window rendered inside Gmail.
src/floating-ui/FloatingAssistant.tsx - UI panels · Input, status, Gmail context, and results panels for the assistant.
src/floating-ui/components/AssistantWindow.tsx - UI hooks · Connects the UI to commands, assistant data, and Gmail context labels.
src/floating-ui/hooks/useAssistantData.ts - UI runtime client · Sends extension messages from the floating UI to the background worker.
src/floating-ui/services/runtimeClient.ts - UI store · Shared state for the floating assistant experience.
src/state/uiStore.ts
Connections 23
- Content script → Shadow overlay: injects · Content script creates the isolated overlay host inside Gmail.
- Content script → Assistant window: mounts · Content script mounts the floating assistant UI into the page.
- Assistant window → UI panels: renders · Assistant shell composes the visible panels and controls.
- Assistant window → UI hooks: uses · UI shell reads assistant state and command hooks.
- UI hooks → UI runtime client: sends · Hooks invoke the runtime client for extension messaging.
- UI runtime client → Background worker: messages · UI requests are forwarded to the background worker.
- Background worker → Runtime router: routes through · Service worker delegates incoming messages to the router.
- Runtime router → Auth handlers: auth · Authentication-related messages go to auth handlers.
- Runtime router → Gmail handlers: gmail · Gmail operations are routed to Gmail handlers.
- Runtime router → AI handlers: ai · AI requests are routed to AI handlers.
- Auth handlers → Token service: uses · Auth flows persist and refresh tokens centrally.
- Auth handlers → Gmail auth: oauth · Auth handlers invoke Chrome Identity-based Gmail login.
- Gmail handlers → Gmail API: calls · Privileged mailbox operations go through Gmail API wrappers.
- Gmail API → Token service: authenticates via · API access relies on the shared token service.
- AI handlers → AI pipeline: invokes · Background AI requests enter the structured AI pipeline.
- AI pipeline → Intent parser: parses · Pipeline starts by turning text into structured intent.
- AI pipeline → Classifier: classifies · Parsed intent is mapped to Gmail-specific action categories.
- AI pipeline → Context enrich: enriches · Request context is augmented with mailbox/thread state.
- AI pipeline → Confidence gate: checks · Confidence gating determines whether to act or clarify.
- AI pipeline → Execution engine: executes · Approved intents are turned into executable actions.
- Execution engine → AI actions: dispatches · Execution resolves to concrete Gmail action handlers.
- Execution engine → Groq client: queries · Some pipeline steps rely on the Groq provider abstraction.
- Groq client → Groq proxy: optional proxy · AI traffic can be routed through the proxy worker.