Save strategy, readiness and audit docs from inbound media

2026-06-14 02:11:12 +00:00
parent 87d6cc14ec
commit a6f28668d3
15 changed files with 1436 additions and 0 deletions
@@ -0,0 +1,83 @@
+# AI / Email Parsing Setup Assessment
+
+This report assesses the Email Intake and AI parsing setup for SaaS Stage 1.
+
+## Current State
+
+Email Intake exists under `/enquiries/email-intake` with backend routes under `/api/email-intake`. It supports:
+
+- IMAP mailbox polling
+- mailbox browser
+- intake logs
+- AI parsing/reparse
+- trusted senders
+- filters
+- operational categories
+- create enquiry from email
+- link email to project/job/quote/enquiry
+- apply project update
+
+Required env vars in route map:
+
+- `IMAP_HOST`
+- `IMAP_USER`
+- `IMAP_PASSWORD`
+- `OPENAI_API_KEY`
+
+## Who Performs Parsing?
+
+Current evidence indicates BoundHQ's platform performs parsing using server-side AI credentials, not customer-provided API keys. That is the correct Stage 1 model.
+
+## Customer API Keys
+
+| Option | Stage 1 recommendation |
+|---|---|
+| BoundHQ-owned AI key | Use now |
+| Customer-owned OpenAI key | Defer |
+| Per-customer model/provider selection | Defer |
+
+Customer-owned keys add support burden and do not move first-customer onboarding.
+
+## Setup Steps
+
+1. Confirm customer consent for mailbox connection and AI parsing.
+2. Create mailbox/app password or forwarding mailbox.
+3. Configure IMAP host/user/password for the tenant.
+4. Configure trusted sender/domain rules.
+5. Poll manually once.
+6. Review parsed logs.
+7. Create one enquiry from an email.
+8. Confirm bad/noisy messages can be ignored/filtered.
+
+## Privacy Considerations
+
+- Emails may contain personal data, job details, addresses, quotes, and attachments.
+- Parsed content must stay inside the customer's tenant.
+- AI prompts/responses should avoid storing unnecessary sensitive data.
+- Customer must know that AI parsing can make mistakes and requires review.
+- The product needs a plain consent statement before enabling auto-polling.
+
+## Tenant Isolation Requirements
+
+Before Stage 1 self-serve use, verify:
+
+- intake logs include tenant/business scope
+- settings and filters are tenant-specific
+- mailbox credentials are not shared across businesses
+- linked records cannot cross tenants
+- AI parsing logs do not leak another tenant's content
+
+## Failure Modes
+
+| Failure | Customer impact | Required behavior |
+|---|---|---|
+| IMAP login fails | No emails imported | Show clear setup error, no retry storm |
+| OpenAI key missing | Emails not parsed | Queue/log with "AI unavailable" |
+| AI parse wrong | Wrong enquiry details | Human review before commit |
+| Duplicate email | Duplicate enquiry | Detect UID/message-id |
+| Large attachment | Slow/fail processing | Keep email log, flag attachment issue |
+| Tenant mismatch | Data leak | Block and alert |
+
+## Readiness Verdict
+
+Email Intake is a strong Stage 1.5 differentiator. It should not block first customer launch. For the first customer, enable it only as a BoundHQ-assisted setup after core quote/job/invoice flow is working.