Gmail Plugin Implementation Plan

Status: FREEZE — scope à part / plus tard (2026-07) — keep this plan and any existing plugin scaffolding; do not implement in cleanup MRs. Reopen only with an explicit dedicated MR. Source map: APP_CLEANUP_MAP.md. Priority index: PRIORITES.md.

Historical plan below (Google Workspace Add-on in Gmail, not an inbox embedded inside Aaperture). Kept for reference only.

Product Decision

We are not building a Gmail inbox inside Aaperture.

We are building a Google Workspace Add-on for Gmail so users can work from Gmail and use Aaperture as the CRM/action engine behind it.

What this means

• No /gmail workspace inside the Aaperture web app.
• No internal email client or mirrored inbox as the main product surface.
• Gmail is the user-facing workspace.
• Aaperture provides:
  • CRM matching
  • lead/contact/session actions
  • next-step recommendations
  • Iris assistance

Goals

When a user opens an email thread in Gmail, the Aaperture panel should let them:

• identify the sender against CRM contacts
• see the linked lead/contact/session if one exists
• create or link a contact
• create or link a pipeline lead
• link a session
• ask Iris what to do next
• generate a useful reply/follow-up suggestion

Non-goals for MVP

• no full inbox replacement
• no Gmail compose/send feature
• no bidirectional mailbox sync
• no Chrome extension as the primary path
• no fuzzy name matching as a first-pass matcher
• no automatic silent conversion of emails into CRM objects

Recommended Architecture

Surface

• gmail-addon/ in the monorepo
• implementation target: Google Workspace Add-on
• technology target for MVP:
  • Apps Script entrypoint for Gmail host integration
  • lightweight add-on UI/cards
  • Aaperture backend APIs for business logic

Backend role

Aaperture remains the source of truth for:

• contacts
• pipeline leads
• sessions
• Iris
• audit trail
• permissions

The add-on sends Gmail context to Aaperture and receives structured CRM/action data back.

User Flow

1. User opens a thread in Gmail.
2. Gmail loads the Aaperture add-on side panel.
3. The add-on extracts thread context:
   • thread id
   • message id
   • sender/recipients
   • subject
   • snippet or short normalized body
4. The add-on calls Aaperture backend.
5. Aaperture returns:
   • matched contact
   • linked lead
   • linked session
   • suggested next step
   • Iris prompt/result if requested
6. User executes an action from Gmail.

MVP Scope

1. Authentication

• Google Workspace Add-on authentication flow
• secure user binding to an Aaperture account
• no duplicate auth model if existing Google identity can be reused cleanly

2. Context ingestion

• parse Gmail message/thread context
• normalize sender email
• normalize subject/snippet/body excerpt

3. Deterministic CRM matching

• exact email match first
• Gmail canonicalization:
  • +alias
  • dot-insensitive Gmail local part
  • googlemail.com -> gmail.com

4. CRM actions

• create contact
• link contact
• create pipeline lead
• link pipeline lead
• link session
• open relevant entity in Aaperture

5. Iris support

• ask Iris for:
  • next best step
  • reply angle
  • follow-up draft
• return concise, ready-to-use results inside the add-on

Backend API Plan

Create a dedicated backend surface such as backend/src/gmail-addon/.

MVP endpoints

• POST /gmail-addon/context
• POST /gmail-addon/match-contact
• POST /gmail-addon/create-contact
• POST /gmail-addon/create-lead
• POST /gmail-addon/link-session
• POST /gmail-addon/ask-iris

Input payload shape

{
  "threadId": "gmail-thread-id",
  "messageId": "gmail-message-id",
  "from": { "email": "lead@example.com", "name": "Lead Name" },
  "to": [{ "email": "studio@example.com", "name": "Studio" }],
  "cc": [],
  "subject": "Wedding inquiry for June 2027",
  "snippet": "Hello, we are looking for...",
  "bodyExcerpt": "Hello, we are looking for a photographer for..."
}

Output payload shape

{
  "matchedContact": null,
  "linkedLead": null,
  "linkedSession": null,
  "nextStep": {
    "title": "Create a lead",
    "reason": "This sender is new and looks like a qualified inquiry."
  },
  "availableActions": [
    "create_contact",
    "create_lead",
    "ask_iris"
  ]
}

Gmail Add-on UI Plan

The add-on panel should stay compact and operational.

Card structure

1. Contact
   • matched / unmatched
   • quick create / link
2. Pipeline
   • linked lead or create lead
   • status if already linked
3. Session
   • linked session or quick link
4. What to do now
   • best next action
   • short reason
5. Iris
   • ask for follow-up
   • ask for next step
   • ask for reply draft

UX rules

• clear wording only
• no internal CRM jargon in the Gmail UI
• every action must help the user move forward immediately
• avoid dead buttons or empty opens

Milestones

Milestone 0: Foundation

• document product decision
• create add-on technical skeleton
• define backend contract
• define auth strategy

Milestone 1: Gmail Add-on bootstrap

• scaffold gmail-addon/
• create manifest / Apps Script host integration
• render a basic Gmail thread side panel
• show raw thread context

Milestone 2: Backend context endpoint

• create gmail-addon backend module
• accept thread context payload
• return normalized sender + CRM match result

Milestone 3: CRM actions

• create contact
• create lead
• link session
• return direct app URLs for open actions

Milestone 4: Iris integration

• ask Iris for next step
• ask Iris for follow-up draft
• return concise client-ready output

Milestone 5: Hardening

• auth/session edge cases
• audit trail
• permission checks
• error states
• telemetry

Testing Scenarios

• open a Gmail thread from an unknown sender
• match an existing contact by exact email
• match a Gmail alias via canonicalization
• create a new contact from Gmail
• create a lead from Gmail
• link an existing session
• ask Iris for next step
• ask Iris for a reply suggestion
• handle backend error cleanly
• handle unauthenticated/expired add-on session cleanly

Risks

• Google Workspace Add-on constraints are stricter than a normal web app
• auth between Gmail host and Aaperture must be designed carefully
• Apps Script/card UI is less flexible than a React app
• over-scoping into full mailbox sync would derail the MVP

Decision Log

• 2026-04-07: reject the “Aaperture-hosted Gmail inbox” direction
• 2026-04-07: keep monorepo, but build a Gmail-native add-on surface
• 2026-04-07: prefer Google Workspace Add-on over Chrome extension for MVP

Recommended Next Step

Start with:

1. add-on technical skeleton in gmail-addon/
2. backend module backend/src/gmail-addon/
3. first contract: POST /gmail-addon/context
4. simple panel showing:
   • sender
   • matched contact
   • best next action