# arunmadhavan-dev/gmailcopilot architecture

> Architecture diagram of the GitHub repository arunmadhavan-dev/gmailcopilot, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/arunmadhavan-dev/gmailcopilot
- Repository: https://github.com/arunmadhavan-dev/gmailcopilot

## Overview

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: [`src/ai/index.ts`](https://github.com/arunmadhavan-dev/gmailcopilot/blob/main/src/ai/index.ts) (AI pipeline), [`src/background/handlers/runtimeMessageHandler.ts`](https://github.com/arunmadhavan-dev/gmailcopilot/blob/main/src/background/handlers/runtimeMessageHandler.ts) (Runtime router), [`src/background/handlers/authHandlers.ts`](https://github.com/arunmadhavan-dev/gmailcopilot/blob/main/src/background/handlers/authHandlers.ts) (Auth handlers), [`src/ai/engine/executor.ts`](https://github.com/arunmadhavan-dev/gmailcopilot/blob/main/src/ai/engine/executor.ts) (Execution engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Extension runtime"]
  node_content["Content script<br/>gmail injector<br/>[index.tsx]"]
  node_overlay["Shadow overlay<br/>dom isolation"]
  node_background["Background worker<br/>orchestrator<br/>[index.ts]"]
  node_runtime_msgs["Runtime router<br/>message dispatch"]
  node_auth_handlers["Auth handlers<br/>auth boundary<br/>[authHandlers.ts]"]
  node_gmail_handlers["Gmail handlers<br/>gmail boundary<br/>[gmailHandlers.ts]"]
  node_ai_handlers["AI handlers<br/>ai boundary<br/>[aiHandlers.ts]"]
end

subgraph group_ai["AI pipeline"]
  node_ai_pipeline["AI pipeline<br/>intent flow<br/>[index.ts]"]
  node_intent_parser["Intent parser<br/>nlp parse<br/>[intentParser.ts]"]
  node_classifier["Classifier<br/>intent categories<br/>[classifier.ts]"]
  node_context_enhancer["Context enrich<br/>gmail context<br/>[enhancer.ts]"]
  node_confidence["Confidence gate<br/>safety checks<br/>[calculator.ts]"]
  node_engine["Execution engine<br/>action runner<br/>[executor.ts]"]
  node_handlers["AI actions<br/>gmail actions<br/>[searchEmails.ts]"]
  node_groq_client["Groq client<br/>llm provider<br/>[client.ts]"]
  node_groq_proxy["Groq proxy<br/>edge proxy<br/>[groq-proxy.js]"]
end

subgraph group_gmail["Gmail access"]
  node_token_service["Token service<br/>oauth tokens<br/>[tokenService.ts]"]
  node_gmail_auth["Gmail auth<br/>chrome identity<br/>[index.ts]"]
  node_gmail_api["Gmail API<br/>api wrappers<br/>[index.ts]"]
end

subgraph group_ui["Floating UI"]
  node_ui_shell["Assistant window<br/>react shell"]
  node_ui_components["UI panels<br/>react components"]
  node_ui_hooks["UI hooks<br/>state hooks"]
  node_ui_runtime["UI runtime client<br/>messaging client<br/>[runtimeClient.ts]"]
  node_ui_store["UI store<br/>zustand state<br/>[uiStore.ts]"]
end

node_content -->|"injects"| node_overlay
node_content -->|"mounts"| node_ui_shell
node_ui_shell -->|"renders"| node_ui_components
node_ui_shell -->|"uses"| node_ui_hooks
node_ui_hooks -->|"sends"| node_ui_runtime
node_ui_runtime -->|"messages"| node_background
node_background -->|"routes through"| node_runtime_msgs
node_runtime_msgs -->|"auth"| node_auth_handlers
node_runtime_msgs -->|"gmail"| node_gmail_handlers
node_runtime_msgs -->|"ai"| node_ai_handlers
node_auth_handlers -->|"uses"| node_token_service
node_auth_handlers -->|"oauth"| node_gmail_auth
node_gmail_handlers -->|"calls"| node_gmail_api
node_gmail_api -->|"authenticates via"| node_token_service
node_ai_handlers -->|"invokes"| node_ai_pipeline
node_ai_pipeline -->|"parses"| node_intent_parser
node_ai_pipeline -->|"classifies"| node_classifier
node_ai_pipeline -->|"enriches"| node_context_enhancer
node_ai_pipeline -->|"checks"| node_confidence
node_ai_pipeline -->|"executes"| node_engine
node_engine -->|"dispatches"| node_handlers
node_engine -->|"queries"| node_groq_client
node_groq_client -.->|"optional proxy"| node_groq_proxy

click node_content "https://github.com/arunmadhavan-dev/gmailcopilot/blob/main/src/content/index.tsx"
click node_overlay "https://github.com/arunmadhavan-dev/gmailcopilot/blob/main/src/overlay/ensureOverlayHost.ts"
click node_background "https://github.com/arunmadhavan-dev/gmailcopilot/blob/main/src/background/index.ts"
click node_runtime_msgs "https://github.com/arunmadhavan-dev/gmailcopilot/blob/main/src/background/handlers/runtimeMessageHandler.ts"
click node_auth_handlers "https://github.com/arunmadhavan-dev/gmailcopilot/blob/main/src/background/handlers/authHandlers.ts"
click node_gmail_handlers "https://github.com/arunmadhavan-dev/gmailcopilot/blob/main/src/background/handlers/gmailHandlers.ts"
click node_ai_handlers "https://github.com/arunmadhavan-dev/gmailcopilot/blob/main/src/background/handlers/aiHandlers.ts"
click node_token_service "https://github.com/arunmadhavan-dev/gmailcopilot/blob/main/src/background/services/tokenService.ts"
click node_gmail_auth "https://github.com/arunmadhavan-dev/gmailcopilot/blob/main/src/gmail/auth/index.ts"
click node_gmail_api "https://github.com/arunmadhavan-dev/gmailcopilot/blob/main/src/gmail/api/index.ts"
click node_ui_shell "https://github.com/arunmadhavan-dev/gmailcopilot/blob/main/src/floating-ui/FloatingAssistant.tsx"
click node_ui_components "https://github.com/arunmadhavan-dev/gmailcopilot/blob/main/src/floating-ui/components/AssistantWindow.tsx"
click node_ui_hooks "https://github.com/arunmadhavan-dev/gmailcopilot/blob/main/src/floating-ui/hooks/useAssistantData.ts"
click node_ui_runtime "https://github.com/arunmadhavan-dev/gmailcopilot/blob/main/src/floating-ui/services/runtimeClient.ts"
click node_ui_store "https://github.com/arunmadhavan-dev/gmailcopilot/blob/main/src/state/uiStore.ts"
click node_ai_pipeline "https://github.com/arunmadhavan-dev/gmailcopilot/blob/main/src/ai/index.ts"
click node_intent_parser "https://github.com/arunmadhavan-dev/gmailcopilot/blob/main/src/ai/parsers/intentParser.ts"
click node_classifier "https://github.com/arunmadhavan-dev/gmailcopilot/blob/main/src/ai/classification/classifier.ts"
click node_context_enhancer "https://github.com/arunmadhavan-dev/gmailcopilot/blob/main/src/ai/query/enhancer.ts"
click node_confidence "https://github.com/arunmadhavan-dev/gmailcopilot/blob/main/src/ai/confidence/calculator.ts"
click node_engine "https://github.com/arunmadhavan-dev/gmailcopilot/blob/main/src/ai/engine/executor.ts"
click node_handlers "https://github.com/arunmadhavan-dev/gmailcopilot/blob/main/src/ai/handlers/searchEmails.ts"
click node_groq_client "https://github.com/arunmadhavan-dev/gmailcopilot/blob/main/src/ai/groqClient/client.ts"
click node_groq_proxy "https://github.com/arunmadhavan-dev/gmailcopilot/blob/main/workers/groq-proxy.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_content,node_overlay,node_background,node_runtime_msgs,node_auth_handlers,node_gmail_handlers,node_ai_handlers toneBlue
class node_ai_pipeline,node_intent_parser,node_classifier,node_context_enhancer,node_confidence,node_engine,node_handlers,node_groq_client,node_groq_proxy toneAmber
class node_token_service,node_gmail_auth,node_gmail_api toneMint
class node_ui_shell,node_ui_components,node_ui_hooks,node_ui_runtime,node_ui_store toneRose
```

## Components

### Extension runtime

Chrome extension surfaces and orchestration boundaries inside Gmail.

- [Content script](https://github.com/arunmadhavan-dev/gmailcopilot/blob/main/src/content/index.tsx): gmail injector · Mounts the assistant trigger and overlay into the Gmail page. · `src/content/index.tsx`
- [Shadow overlay](https://github.com/arunmadhavan-dev/gmailcopilot/blob/main/src/overlay/ensureOverlayHost.ts): dom isolation · Creates an isolated host and injects overlay styles so Gmail CSS does not leak. · `src/overlay/ensureOverlayHost.ts`
- [Background worker](https://github.com/arunmadhavan-dev/gmailcopilot/blob/main/src/background/index.ts): orchestrator · Manifest V3 service worker that receives messages and coordinates privileged work. · `src/background/index.ts`
- [Runtime router](https://github.com/arunmadhavan-dev/gmailcopilot/blob/main/src/background/handlers/runtimeMessageHandler.ts): message dispatch · Routes extension messages to AI, auth, and Gmail handlers. · `src/background/handlers/runtimeMessageHandler.ts`
- [Auth handlers](https://github.com/arunmadhavan-dev/gmailcopilot/blob/main/src/background/handlers/authHandlers.ts): auth boundary · Handles login and token-related runtime requests. · `src/background/handlers/authHandlers.ts`
- [Gmail handlers](https://github.com/arunmadhavan-dev/gmailcopilot/blob/main/src/background/handlers/gmailHandlers.ts): gmail boundary · Handles privileged Gmail operations requested by the UI or AI layer. · `src/background/handlers/gmailHandlers.ts`
- [AI handlers](https://github.com/arunmadhavan-dev/gmailcopilot/blob/main/src/background/handlers/aiHandlers.ts): ai boundary · 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](https://github.com/arunmadhavan-dev/gmailcopilot/blob/main/src/ai/index.ts): intent flow · End-to-end intent parsing, classification, context enrichment, confidence checks, and execution. · `src/ai/index.ts`
- [Intent parser](https://github.com/arunmadhavan-dev/gmailcopilot/blob/main/src/ai/parsers/intentParser.ts): nlp parse · Turns user text into structured intent and error-handled model output. · `src/ai/parsers/intentParser.ts`
- [Classifier](https://github.com/arunmadhavan-dev/gmailcopilot/blob/main/src/ai/classification/classifier.ts): intent categories · Assigns requests to Gmail-specific action categories. · `src/ai/classification/classifier.ts`
- [Context enrich](https://github.com/arunmadhavan-dev/gmailcopilot/blob/main/src/ai/query/enhancer.ts): gmail context · Augments requests with mailbox and thread context for better relevance. · `src/ai/query/enhancer.ts`
- [Confidence gate](https://github.com/arunmadhavan-dev/gmailcopilot/blob/main/src/ai/confidence/calculator.ts): safety checks · Scores model output and blocks low-confidence or risky execution. · `src/ai/confidence/calculator.ts`
- [Execution engine](https://github.com/arunmadhavan-dev/gmailcopilot/blob/main/src/ai/engine/executor.ts): action runner · Resolves actions through registry, factory, and executor layers. · `src/ai/engine/executor.ts`
- [AI actions](https://github.com/arunmadhavan-dev/gmailcopilot/blob/main/src/ai/handlers/searchEmails.ts): gmail actions · Concrete Gmail-specific handlers such as search, archive, delete, and clarify. · `src/ai/handlers/searchEmails.ts`
- [Groq client](https://github.com/arunmadhavan-dev/gmailcopilot/blob/main/src/ai/groqClient/client.ts): llm provider · Provider abstraction for structured LLM requests and JSON repair. · `src/ai/groqClient/client.ts`
- [Groq proxy](https://github.com/arunmadhavan-dev/gmailcopilot/blob/main/workers/groq-proxy.js): edge 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](https://github.com/arunmadhavan-dev/gmailcopilot/blob/main/src/background/services/tokenService.ts): oauth tokens · Centralizes Google OAuth token persistence and refresh. · `src/background/services/tokenService.ts`
- [Gmail auth](https://github.com/arunmadhavan-dev/gmailcopilot/blob/main/src/gmail/auth/index.ts): chrome identity · Wraps Chrome Identity-based OAuth flow for Gmail access. · `src/gmail/auth/index.ts`
- [Gmail API](https://github.com/arunmadhavan-dev/gmailcopilot/blob/main/src/gmail/api/index.ts): api wrappers · 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](https://github.com/arunmadhavan-dev/gmailcopilot/blob/main/src/floating-ui/FloatingAssistant.tsx): react shell · Floating assistant window rendered inside Gmail. · `src/floating-ui/FloatingAssistant.tsx`
- [UI panels](https://github.com/arunmadhavan-dev/gmailcopilot/blob/main/src/floating-ui/components/AssistantWindow.tsx): react components · Input, status, Gmail context, and results panels for the assistant. · `src/floating-ui/components/AssistantWindow.tsx`
- [UI hooks](https://github.com/arunmadhavan-dev/gmailcopilot/blob/main/src/floating-ui/hooks/useAssistantData.ts): state hooks · Connects the UI to commands, assistant data, and Gmail context labels. · `src/floating-ui/hooks/useAssistantData.ts`
- [UI runtime client](https://github.com/arunmadhavan-dev/gmailcopilot/blob/main/src/floating-ui/services/runtimeClient.ts): messaging client · Sends extension messages from the floating UI to the background worker. · `src/floating-ui/services/runtimeClient.ts`
- [UI store](https://github.com/arunmadhavan-dev/gmailcopilot/blob/main/src/state/uiStore.ts): zustand state · Shared state for the floating assistant experience. · `src/state/uiStore.ts`

## Connections

- 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.
