Empire Teas CRM — Project PRD
Status: live contract — Gate 1 passed-with-risks 2026-07-07 Last updated: 2026-11-20 (Rev 107 — see
project-prd-history.md) Reviewed by: Dinil (Gate 1); Rev 8–12 approval pending — Dinil; Rev 21 approved — Tharinda, 2026-09-07
The single source-of-truth product requirements document for this engagement. Verified by /forge-prd-check (Gate 1) before the team commits to delivering against it.
Gate Status
Snapshot of engagement-readiness gates. Updated automatically by
/forge-prd-check,/forge-arch-probe,/forge-decomposein full mode. Detailed run history lives inengagement-gate-runs.md. Structured state and accepted risks/spikes live intracker.yamlundersetup.*.
| Gate | Status | Last Run | Risks / Spikes | Detail |
|---|---|---|---|---|
1. PRD Readiness (/forge-prd-check) |
⚠️ passed-with-risks | 2026-07-07 | 2 risks | Run 1 |
2. Architecture & Feasibility (/forge-arch-probe) |
⚠️ passed-with-risks-and-spikes | 2026-08-06 | 1 risk, 1 spike (2 stood down) | Run 2 · Run 1 |
3. Decomposition (/forge-decompose) |
✅ passed | 2026-09-17 | — (no risk path) | Run 1 — 89 features, 2 phases |
Status legend: ⏳ not-started · 🚧 in-progress · ✅ passed · ⚠️ passed-with-risks · ⚠️ passed-with-spikes · ⚠️ passed-with-risks-and-spikes · ❌ failed
Problem Statement
Empire Teas (Pvt) Ltd is a top-five Sri Lankan tea exporter shipping ~14 million kg/year to 70+ countries across two commercial lines: bulk tea (raw made tea sold by weight to importers/blenders) and private label (shelf-ready product manufactured under the buyer’s own brand). Their front-office sales process — buyer inquiries, private-label product development, sample development and dispatch, quotation, follow-up, and export coordination — is relationship-heavy, sample-driven, and spans multiple internal teams (sales, tea tasters/R&D, QA, export documentation, finance). No generic CRM models this workflow natively.
Today this process runs on Pipedrive plus spreadsheets, email, and WhatsApp. The result is measurable revenue leakage: 200+ leads sit unreviewed in Pipedrive, follow-ups are missed, sample and quote status is not visible end-to-end, and dormant reorder-ready accounts go silent. Pipedrive’s structural limits make it a poor long-term fit — automated emails send only from an individual rep’s synced mailbox (not a shared company address), automation is hard plan-gated, and its native AI offers no tea-domain context (grades, certifications, private-label workflow, export docs). [research: initial-findings.md §5.3, pipedrive-crm-notes.md]
Empire Teas is separately migrating to a new ERP for transactional operations (inventory, production, procurement, finance, sales orders). That ERP is the transaction backbone and is out of scope for this project. The opportunity is the front-office productivity layer around it: a purpose-built sales CRM that (a) replaces Pipedrive without losing any capability the team relies on, (b) models the tea export / private-label workflow as first-class, and © embeds human-in-the-loop AI into the repetitive text/document work (inquiry capture, lead triage, account briefing, quote readiness, export-doc checklists) — with a human approving every action and setting all pricing.
This project builds that CRM. It is a custom application (not a configured SaaS) because every high-value requirement — multi-round sample approval gating, two truly independent pipelines, certification-mismatch detection, and tea-domain AI calling Claude directly — requires custom development on Zoho/Odoo/Pipedrive anyway, at the same effort but on a platform Empire Teas would not own. [research: competitive-landscape.md §5.1] The scope explicitly includes replicating the core Pipedrive feature set the team uses day-to-day (email in the CRM, calendar/contact sync, configurable pipelines with weighted forecasting and idle-deal “rotting”, a sellable-item list (Pipedrive’s products — modelled here as buying standards, Rev 27), outreach sequences, spreadsheet import/export, list views with their own search, saved filters and bulk actions (global search across all records was dropped in Rev 60), file attachments, and admin-configurable custom fields) so that migrating off Pipedrive loses nothing. [source: Pipedrive official documentation research, 2026-07-07]
Industry / Domain Context
Sri Lanka tea trade. Sri Lanka (Ceylon) is the world’s 4th-largest tea producer and was 2nd in export earnings globally (2020); 2024 export revenue was USD 1.435 billion. Exporters like Empire Teas operate at the trade & export layer: they source made tea (via the weekly Colombo Tea Auction or direct purchase), blend, pack under own brands or private label, and ship worldwide. The Colombo auction price is the weekly-fluctuating baseline cost of tea — which is why quotes carry expiry dates (typically 30 days): a price viable today may not survive next week’s auction. [research: sri-lanka-tea-industry.md §1, §4, §10]
“Ceylon Tea” is a legally protected designation. To be labelled Ceylon Tea, a product must be 100% grown and manufactured in Sri Lanka and meet SLTB quality standards — even 95% Sri Lankan tea cannot claim it. This is why Empire Teas’ Kenya-origin tea (launched 2017) is marketed as a separate African-origin brand (Akina) and never as Ceylon Tea. [research: sri-lanka-tea-industry.md §3, §11]
Tea grades. Buyers always specify grades. Grade families run from whole-leaf (OP, FOP, TGFOP) → broken (BOP, FBOP, BP) → fannings (BOPF — the main teabag grade) → dust (D1, PD). Two processing systems: Orthodox (whole/broken, higher value) and CTC (Crush-Tear-Curl; fannings/dust for teabags, higher volume). Grade drives pricing, sourcing, and which auction lots are relevant. [research: sri-lanka-tea-industry.md §5]
Market → grade → certification patterns. Middle East (largest volume) wants BOPF/Dust/BOP and requires Halal (plus GMP specifically for Iran); Russia/CIS wants strong BOP/BOPF; Europe (premium) wants OP/FOP and requires EU Organic / Rainforest Alliance / Fairtrade / BRCGS or IFS Food; Japan requires JAS; North America requires FDA facility registration / USDA NOP / Kosher. Empire Teas holds an unusually complete certification stack covering all these markets. [research: sri-lanka-tea-industry.md §7, §12]
Export regulation. Every shipment is authorised by the Sri Lanka Tea Board (SLTB) and cleared through ASYCUDA via a CUSDEC declaration. The standard export document set includes Commercial Invoice, Packing List, Bill of Lading / Airway Bill, Certificate of Origin, Phytosanitary Certificate, SLTB Export Authorisation, Lion Logo Certificate (if marketed as Ceylon Tea), plus destination- and certification-specific documents (organic certs matched to batch/lot, EU pesticide MRL lab reports, GMP for Iran, etc.). This regulatory workflow is operational (ERP/export team) — the CRM references the correct document set per destination + certification but does not submit to SLTB/ASYCUDA. [research: sri-lanka-tea-industry.md §8]
Incoterms. Quotes are priced under a specific Incoterm; CIF (Cost, Insurance, Freight to destination port) is dominant in Ceylon tea trade, with FOB Colombo common for bulk. The same tea at FOB Colombo vs CIF Hamburg is a different price, so every quote must capture its Incoterm. [research: sri-lanka-tea-industry.md §9]
Private label is the complex line. A private-label deal runs a long, multi-team, multi-round cycle: inquiry → qualification → product brief → sample development (2–5 rounds common) → sample dispatch/feedback → artwork & packaging approval → compliance/certification check → quote → negotiation → order → ERP handoff. Bulk is short and price-driven (weeks, 3–4 stages). These are fundamentally different pipelines with different fields, stages, and alert thresholds. [research: sri-lanka-tea-industry.md §10, tea-export-domain-notes.md]
AI in this domain. The tea-tech AI narrative in Sri Lanka today is operational (leaf grading, auction image classification) — a sales-productivity AI story is fresh and complementary. The right AI pattern here is human-in-the-loop: LLMs read/extract/summarise/draft/classify/check-completeness on repetitive text, and a human reviews before anything is saved, sent, or acted on. AI must never autonomously set price, approve compliance, clear export, or release quality. [research: ai-in-workflows.md §1–2, §4, competitive-landscape.md §2.5]
Business Specifics
- Company: Empire Teas (Pvt) Ltd — third-generation family business (~25 years), HQ in Angoda (Colombo), Sri Lanka. Current Tea Master/leader: Lushantha de Silva. Among Sri Lanka’s top-five tea exporters; 2024/25 Presidential Export Award (Merit). [research: initial-findings.md §2.1]
- Scale: ~14M kg/year to 70+ countries; confirmed key markets include Turkey, Russia, Ukraine, Guinea. International offices: Sri Lanka (HQ), Kenya (since 2017), Netherlands, Shanghai, Spain. [research: initial-findings.md §2.1–2.2]
- Commercial lines: Bulk tea (highest volume) and Private label (higher complexity/margin). Supporting: sourcing/tasting, blend development, custom packaging, export logistics. [research: initial-findings.md §2.3]
- Own brands: Thurson Teas (Ceylon heritage), Hyson Teas (modern connoisseur), Akina Teas (African/Kenya origin), Ceylon Wild Harvest (organic spices, not tea); plus Tea Avenue lifestyle café brand. These are Empire’s own retail brands — distinct from the private-label line (where the product carries the buyer’s brand). These own-branded goods are sold through this B2B sales pipeline (confirmed 2026-07-22), so Buying Standard and Deal carry a first-class
brandattribute (OQ-20 resolved, Rev 4; carried by the standard since the catalog was removed — Rev 27). [research: initial-findings.md §2.3] - Current tooling: Pipedrive CRM (plan tier unknown). Reps work inside the Pipedrive inbox today (send/receive email in-CRM), so email-in-CRM is a day-one parity requirement (F20). Sample/quote/communication data also lives in Excel, email, and WhatsApp. 200+ unreviewed leads. Record volumes for migration were counted from the Pipedrive exports (§F4, OQ-6, Rev 44). Team size, the active Pipedrive user count and which paid Pipedrive add-ons are in use (LeadBooster chatbot/live chat, Campaigns, Data Enrichment, any LinkedIn tool) are not yet confirmed; no Pipedrive audit is coming, so they are asked of Empire directly (OQ-22, OQ-23). [research: initial-findings.md §3, discovery-questions.md Tier 6; source: Pipedrive doc research 2026-07-07]
- ERP: Empire runs IFS as its current ERP and is separately adopting a new ERP (targeted ~2027) as the transaction backbone. V1 scope (per AD #10): the CRM→ERP handoff ships as a manual document on the
ErpHandoffServiceseam. Automated integration is a separately-priced follow-on; if it is later commissioned and the APIs prove unavailable, the handoff stays the manual document. Since 2026-11-12 (Rev 92): Empire is replacing IFS with an ERP not yet chosen, so any automated integration waits until Empire names that ERP and gives its details (OQ-2). [research: initial-findings.md §5.3, discovery-questions.md Tier 1 Q2 / Tier 5] - Certification stack (held): Lion Logo (SLTB), ISO 9001:2025, FSSC 22000, BRCGS, IFS Food, GMP (Iran), SMETA/Sedex, EU Organic, USDA NOP, JAS, Halal, Kosher, Rainforest Alliance, Fairtrade, FDA facility registration. [research: initial-findings.md §2.4]
Scope and Boundaries
The reference system is Pipedrive (the CRM being replaced) and the client-approved prototype (.forge/design/prototypes/crm/), which demonstrates the intended look, modules, and behavior for the tea-domain workflows. The Pipedrive-parity features (F20–F26; F27–F30 were dropped in Rev 66) are grounded in Pipedrive’s official documentation so migration loses nothing the team relies on. In-scope features are described one paragraph each in §Functional Surface.
In Scope (V1)
Grouped by delivery theme (loose sequencing in §Phasing). Each carries a priority (P0 = must-have to replace Pipedrive / core value; P1 = high-value domain, AI & parity; P2 = enhancement).
Core CRM — system of record (replaces Pipedrive):
- F1 — Accounts (organizations + contacts) — P0. 360° customer records: profile, certifications required, preferred packaging, Incoterms, contacts, communication timeline, linked deals/samples/quotes, past orders (ERP), LTV, dormancy; a contacts page that includes contacts with no account (Rev 56). [prototype §2.4]
- F2 — Pipeline / Deals (independent pipelines, Kanban, drag-and-drop) — P0. Private Label (10 stages) and Bulk (4 stages) boards; deal cards with value, volume, certs, owner, age-in-stage alerting; deal detail. Pipelines are admin-configurable (F24). [prototype §2.3, §2.8]
- F3 — Activities (tasks, follow-ups, reminders) — P0. Grouped Overdue/Today/Upcoming/Completed, filters, mark-done, activity types (call/meeting/task/deadline/email/lunch + custom), linked to accounts/deals/leads. [prototype §2.7]
- F4 — Pipedrive data migration — P0. One-time import of leads, contacts (Pipedrive people), and organizations (accounts), with dedup/cleaning and original-ID preservation. Pipedrive notes, activities and custom fields are not migrated (lead decision, 2026-09-28 — Rev 44); a custom field’s value is still read where the import needs it to fill a typed field, as
Person - Trade Fairsfills a lead’s source. Deals and deal history are not migrated: Empire chose a fresh start on deals in the new system (2026-09-13); historical deals remain in Pipedrive as the record. (The “lose nothing on migration” promise is unaffected — this is Empire’s informed election, and open leads/accounts, the backlog they actually need to work, carry over.) [research: initial-findings.md §5.4, discovery-questions.md Tier 6] - F5 — Authentication, users, roles & ownership — P0. Per-user Microsoft login for pre-created users, configurable role-based access, record ownership, reassignment and per-record sharing (AD #34, AD #35). [prototype §6 implicit]
Tea-domain workflows:
- F6 — Sample tracking (multi-round lifecycle) — P1. 7-state lifecycle board + management table; multi-round per deal; courier/tracking; overdue-feedback nudges; “where it’s stuck” reasons. [prototype §2.5]
- F7 — Quotes with 8-item readiness checklist + approval gate — P1. Quote records, aging, revision history, line items drawn from the account’s buying standards (F26); submission blocked until the 8-item checklist passes and a human approves pricing/margin. [prototype §2.6]
- F8 — Product briefs (private label) — P1. Structured internal brief (tea type, blend, origin, packaging, pack size, certs, target market) with blocking open-questions before R&D/packaging handoff. [prototype §2.8]
- F9 — Certification mismatch check — P1. Cross-checks buyer-required certifications (account) against the certifications held by the deal’s buying standards (F26) and flags what’s missing. [prototype §2.8; research: competitive-landscape.md §5.1]
- F10 — Export documentation checklist — P1. Generates the required document set per destination country + the standard’s held certifications (base + country-specific + cert-specific docs), toggleable as assembled. [prototype §2.8; research: sri-lanka-tea-industry.md §8]
AI productivity layer (human-in-the-loop throughout):
- F11 — Lead Triage with AI research, scoring & drafted replies — P1. Inbound-inquiry queue where every lead is researched against public sources before it is scored (Rev 30; when the research cannot run, the lead is scored from the inquiry first and scored again once its research completes — Rev 83), then given AI priority (P1–P3) + confidence, a hot/cold status from how recently the buyer last wrote (not AI — Rev 55), AI summary, spam/duplicate detection, recommended next action, editable AI-drafted follow-up generated when a person asks (Rev 56); approve/convert/archive actions. Includes recovering the 200+ Pipedrive backlog. [prototype §2.2; research: ai-in-workflows.md §8 UC1–2]
- F12 — AI inquiry extraction from email — P1. Extract structured fields (buyer, country, grade, volume, certs, Incoterm, destination, timeline) from inbound inquiry text into a CRM draft for human confirmation; unknown fields returned null, never guessed. [research: ai-in-workflows.md §8 UC2]
- F13 — AI account briefing — P1. Pre-meeting synthesis of an account, made when a person asks (last state, open items, suggested next move, a re-engagement prompt on a dormant account). [prototype §2.4; research: ai-in-workflows.md §8 UC3]
- F14 — AI quote assistant — P1. Flags missing quote inputs and risk (never sets price); it does not surface comparable past quotes (F7-e dropped, Rev 61). [prototype §2.6; research: ai-in-workflows.md §8 UC5]
- F15 — AI dashboard: morning briefing + “what’s stuck” + ranked leads — P1. Personalized daily narrative and blocker read across leads/opps/samples/quotes, with click-through. [prototype §2.1]
Visibility & handoff:
- F17 — Dashboard & operational KPIs — P0. Response-time, follow-ups due, samples overdue, quotes aging, dormant high-value accounts; pipeline-by-stage funnel (Private Label / Bulk); weighted forecast (from F24 stage probability). [prototype §2.1, §2.7]
- F18 — Stale/aging alerts & dormant-account detection — P1. Per-pipeline stale-deal thresholds (the “rotting” idle-deal flag, configured per stage in F24), quote aging, dormant reorder-ready accounts. [prototype §2.1; research: discovery-questions.md Q20–Q21, Q26]
- F19 — CRM→ERP handoff on Won — P1. On a Won deal, produce a structured handoff document (manual path) with a readiness checklist (quote approved, certs verified, brief complete). Automated API sync deferred pending ERP API confirmation. [prototype §2.8 ERP handoff]
CRM parity & communication (Pipedrive baseline the team relies on — grounds the “nothing lost on transition” promise):
- F20 — Email in the CRM (two-way sync + send + templates + tracking) — P0. Two-way email sync (Microsoft 365 via Microsoft Graph — the only provider in V1 scope) so mail auto-links to contacts/deals/leads; compose/send/reply/reply-all/forward with formatted text from a deal/contact and an in-CRM inbox, and attaching files (F20-h) (Rev 68); reusable email templates (pre-built + custom, team-shareable) with merge fields; open/link tracking; scheduled send. F20 itself sends one email at a time — bulk sending is not part of F20’s scope; it is the separate feature F37 (Phase 2; its weekly price broadcast, F37-a, is accepted with Phase 1 — Rev 100), which builds on F20’s send path, templates and tracking rather than changing them. Reps confirmed working inside Pipedrive’s inbox today → day-one parity. AI drafting reuses F11/F12 (Claude, tea-voice, HITL). Unreplied customer email (F44, Rev 92, Phase 1): an email from a customer or a lead that is linked to its record and has had no reply after one working day (an administrator can change the wait) creates a follow-up for the person who received it, with Reply (compose, from a template or an AI draft) and No Reply Needed; nothing is sent without a person. [source: Pipedrive doc research 2026-07-07 — email sync, templates, group email; Empire’s ask at the progress meeting of 2026-11-10]
- F21 — Activity calendar & calendar sync — P1. Calendar view of activities (day/week/list) with activity-type filters and drag-to-reschedule; two-way sync with the user’s Microsoft 365 calendar (via Microsoft Graph — the only provider in V1 scope, per Rev 7/AD #16) so external events show alongside CRM activities. Extends F3. [source: Pipedrive doc research — activity calendar, calendar sync]
- F22 — Contact sync (from the user’s Outlook contacts) — P2. Read the contacts in the user’s connected Microsoft 365 account (Graph — the only provider in V1 scope, per Rev 7/AD #16), one way into the CRM, and offer the ones the CRM does not hold on a per-user review list, so contacts don’t have to be typed in one by one, and fill only empty fields on contacts it already holds. Matches by every email address, so a person already in the CRM under any of their addresses is not added again. [source: Pipedrive doc research — contact sync; Rev 107]
- F23 — Data import & export (CSV/Excel) — P1. Ongoing spreadsheet import (leads/contacts/orgs/deals/buying standards/activities) with header→field mapping onto existing fields (custom fields are created first under F34 — creating them on import was dropped, Rev 63), and merge-or-create dedup; and CSV/Excel export of list views. Broader than the one-time F4 migration (e.g. trade-fair lead lists). [source: Pipedrive doc research — spreadsheet import]
- F24 — Configurable pipelines (admin stages + probability + rotting) — P1. Admin-creatable pipelines with named, ordered stages; per-stage win probability (0–100%) driving a weighted forecast; per-stage rotting (idle-deal threshold in days; deal turns red when untouched longer, clock resets on activity/note/email/edit). Seeded with the two tea pipelines (Private Label / Bulk) as defaults. Rotting is the mechanism behind F18 stale alerts. [decision 2026-07-07; source: Pipedrive doc research — pipelines, stage probability, rotting]
- F25 — Outreach sequences — P1. Multi-step email + task cadences enrolled on a deal/lead, using templates in steps; AI generates each step’s email (tone/length, tea context) for human approval (HITL). Drives re-engagement of the 200+ triaged leads and dormant accounts (ties to F11/F18). [source: Pipedrive doc research — sequences; research: ai-in-workflows.md §8 UC7]
- F26 — Buying standards & weekly pricing (deal line items) — P1. No separate products catalog (Rev 27): the client-specific Buying Standard — a unique, never-reused running number on one account — is the sellable record for bulk and private label alike, carrying tea grade, origin, brand and held certifications. Standards are created, edited and archived (archiving keeps the price history and removes the standard from quoting and the weekly round; numbers are never reused). Attach standards to a deal with quantity + discount; line items roll up into deal value. The standards book is the single source of truth for the F9 certification-mismatch check and F7 quote line items, and the Tea Room prices each standard weekly (§F26). [source: Pipedrive doc research — products, replaced by the standard-number model; prototype PR #88]
- F32 — List/table views, saved filters & bulk actions — P1. Every core entity has a sortable, column-configurable list/table view (alongside its board/detail views), saved filtered views (personal or shared), and bulk actions on a selection — edit a field, reassign owner, add activity, enrol in a sequence, archive, or export to CSV/Excel (with F23). [source: Pipedrive doc research — list views/filters]
- F33 — File attachments — P1. Attach files to any core record (deals, accounts, contacts, leads — Rev 85 — quotes, samples, product briefs) — central for private label, where artwork, packaging mock-ups, buyer POs, spec sheets, and certification PDFs must live with the deal. Files show uploader/date/size; uploads are type/size-validated and access-scoped. [source: Pipedrive doc research — files]
- F34 — Admin custom fields — P1. Admins define custom fields per entity (account/contact/deal/lead/quote/buying standard/sample — text/number/date/single-or-multi-select/etc.) on top of the typed tea-domain schema, so the team can add fields later without a code change (Pipedrive custom fields are not migrated — Rev 44). Custom fields appear on forms, list views (F32), filters, and import mapping (F23). [decision 2026-07-07; source: Pipedrive doc research — custom fields]
- F37 — Bulk email — P1, Phase 2 (F37-a, the weekly price broadcast, built early and accepted with Phase 1 — Rev 100; F37-b started early in Phase 1 on 2026-11-19, and moves back to Phase 2 if it is not done by the end of Empire’s Phase 1 UAT round — Rev 102). Committed to Empire on 2026-10-09 (Rev 57), after a stretch candidate since 2026-09-16 (Rev 28). Two parts, built in this order: (a) weekly price broadcast (F37-a) — this week’s prices to every customer at once, as a batch of per-account emails, each carrying only that customer’s own standards: the per-account send this week’s prices action (F26 + F20) repeated under one confirmation. (b) bulk email to a saved contact list (F37-b) — one message, composed from an F20 template, to the contacts of a saved list (F32, by market, customer type, tag or custom field), for newsletters, product promotions and trade-fair invitations, with a summary for each send (sent, delivered, opened, clicked) built on F20’s open/link tracking. (b)'s consent, unsubscribe, suppression and sending-address questions (OQ-62) were decided by the delivery team on 2026-11-19 under the lead’s rule of 2026-11-13 (Rev 103), and Empire is asked to confirm them at the Phase 1 hand-over: each email goes from the mailbox of the person who confirms the send, through Microsoft Graph, one email per contact, at most 20 a minute as F37-a does, and at most 5,000 recipients in any 24 hours counted with the sender’s price broadcasts, so replies reach that person; every contact on the list receives it unless they have unsubscribed — there is no opt-in tick, and every email carries Empire’s postal address and an unsubscribe link that needs no sign-in and opens a page with one Unsubscribe button (a link that unsubscribed on opening would be triggered by mail security scanners); bounce reports in the sender’s mailbox are read, so a bounced address shows not delivered, delivered is the number sent less the number bounced, and an unsubscribed or bounced address is left out of later bulk sends. A shared sending address (through SES) is not built; Empire can ask for it as a change. Scope discipline: F37 is the send, not a campaign product — no segmentation builder, no campaign reporting across sends, no template designer beyond F20’s templates (that was F28, dropped in Rev 66). Commercial note: the issued proposal does not cover bulk sending, so this is added scope; Empire was told on 2026-10-09 that Phase 2’s features will be prioritised with them at or before the Phase 1 hand-over, which is where the compensating descope is agreed (R-ARCH-001, L-001). [
discovery/meeting-notes/2026-10-09-kavindu-bulk-email.md; Rev 28; Rev 57]
Trade-show capture companion (own application):
- F36 — Trade-show lead capture app (companion PWA) — P1. A standalone capture app in its own repository (
forge-et-pwa) at its own URL (AD #20/#22): photograph a business card / scan a badge QR on the exhibition floor, one at a time (a capture whose upload fails is kept on the phone and sent again when the app is open with a connection — Rev 64), AI card reading into structured fields, research/scoring on theAIProviderseam (human-reviewed), and in-app lead notifications — no email and no WhatsApp (AD #42, Rev 94). A captured lead reaches the CRM only after a person reviews it in the app (Rev 95): converting it creates the CRM lead through the F11 intake with first-class source tracking, owned by whoever converted it; rejecting it keeps it in the capture app only. Using the app needs its own permission,capture.use(Rev 95). Full scope (Option C, decided 2026-08-18); the reduced capture-and-feed shape is retained as a descope lever at the capture-app checkpoint, which the Statement of Work of 2026-09-29 holds during Phase 2, date to be set; since the app moved to Phase 1 on 2026-11-11 (Rev 91), the checkpoint is proposed for Fri 2026-11-20, Phase 1’s build target, to be confirmed with Empire. Builds from the working prototype published read-only asforge-et-pwa-poc. Confirmed and added 2026-09-09 (Rev 23): badge QR scanning is needed; an existing-client check during the scan (is this organisation or person already a customer, and how often does Empire deal with them — needs an account/contact lookup from the app). The same-day generic follow-up email to people met at the stand, also asked for that day, was dropped on 2026-10-11 (Rev 63, §Out of Scope). Campaign planning is already present in the POC and is not a new ask. Planning before a show is in Phase 1 (Rev 96, the lead’s decision of 2026-11-12): the app’s Plan tab holds a show’s campaign, the exhibitors loaded from the show’s list or added by hand, each researched and ranked by the AI, and the rep’s visit notes and visited marks — built in F36-a (the screens and data) and F36-c (the research and ranking). A campaign can carry an optional focus that the AI ranks its exhibitors and captured leads for, on top of the standard rules, and a converted lead keeps the app’s ranking as its CRM priority (Rev 101). [proposal §4;architecture.md § Trade-Show Capture App; OQ-48; OQ-55]
Out of Scope
Explicitly not built in this project (negative-space exclusions — a comparable CRM/CTRM might include these, but this project will not):
- ERP functionality — inventory, production, procurement, warehouse, finance, invoicing, confirmed sales orders. Won’t-build reason: the ERP is the client’s transaction backbone; building these would create a parallel mini-ERP, an explicit anti-goal. [research: tea-export-domain-notes.md, initial-findings.md §11]
- Estate/plantation & manufacturing operations (green-leaf intake, withering/rolling/fermentation/drying/grading, factory ops). Won’t-build reason: Empire Teas operates at the trade/export layer, not cultivation/manufacturing; this is tea-ERP territory. [research: sri-lanka-tea-industry.md §1]
- Auction bidding / tea-grading AI (Colombo auction participation, leaf image grading). Won’t-build reason: covered by dedicated platforms (OKLO SmartAuction, SLTB); potential partners, not our scope. [research: competitive-landscape.md §2.3, §2.5]
- Native mobile apps (iOS/Android). Won’t-build reason: V1 is responsive web — the CRM plus the F36 capture PWA as the mobile surface; native apps are a later decision, not required to replace Pipedrive’s core web use. (See Deferred.)
- Generic no-code automation builder (Pipedrive/Zapier-style user-configurable trigger→action rule builder). Won’t-build reason: the valuable automations are domain-specific and built in (F18 stale/rotting alerts, F6 sample nudges, F9 cert checks, F25 sequences); a general rule-builder is unnecessary complexity for this team. [research: initial-findings.md §5.3] (Note: outreach sequences F25 and configurable pipelines F24 are specific, bounded features — not the open-ended automation builder.)
- Third-party integration marketplace (Slack/Teams/Trello/Mailchimp/QuickBooks/PandaDoc, etc.). Won’t-build reason: only ERP, inbound email/calendar/contacts, Claude and the lead-research web search are relevant (LinkedIn and data enrichment, F30 and F29, were dropped in Rev 66); a marketplace is Pipedrive-scale surface with no Empire Teas demand.
- Marketing suite — drip-nurture platform beyond outreach sequences, ad-campaign management, landing pages, lead-gen sourcing. Won’t-build reason: this is a sales-operations CRM, not a marketing platform. (Newsletter email Campaigns and a website Chatbot/Live Chat are Pipedrive paid add-ons; they were deferred on 2026-08-20 and dropped on 2026-10-11, and are excluded by the Pipedrive add-on bullet below (Rev 66). The plain bulk send, F37, is in scope.)
- WhatsApp integration — out of V1 (team decision, Tharinda, 2026-09-11; confirmed by Dinil; PRD Rev 23). WhatsApp is not integrated in any form — not as a notification channel (AD #20), not for buyer messaging, not for logging existing threads; Empire’s 2026-09-09 ask for WhatsApp alongside email is recorded and declined for V1. (The bulk-email half of this exclusion was lifted on 2026-09-16 — Empire confirmed bulk sending as an important and useful requirement, and it became a stretch candidate, F37, committed to Phase 2 on 2026-10-09 (Rev 57, §In Scope). WhatsApp is unaffected and stays out.)
- Direct SLTB / ASYCUDA / Customs submission. Won’t-build reason: regulatory submission is the export team’s operational responsibility; the CRM references the correct document set but does not file it. Integration feasibility is unverified. [research: sri-lanka-tea-industry.md §8, competitive-landscape.md §7]
- Autonomous AI decisions — AI setting/approving final price, approving compliance, clearing export, releasing quality, or auto-sending to buyers/ERP. Won’t-build reason: these are binding commercial/compliance commitments; human accountability is a hard governance requirement. [research: tea-export-domain-notes.md, ai-in-workflows.md §4]
- Self-service user creation — auto-provisioning a user on their first Microsoft sign-in, and invitation emails (Rev 37, AD #34). Won’t-build reason: Empire’s administrator (the holder of
settings.manage—access.manageuntil Rev 79) pre-creates every user with their one role, and sign-in succeeds only for an active pre-created user. An auto-provisioned user would have no role to land in, and an invitation flow would add a mail dependency to user administration; the administrator tells the person to sign in instead. - Synchronising users from Empire’s Entra directory — creating, changing or deactivating CRM users automatically from Entra (Rev 37, AD #34). Won’t-build reason: in-app deactivation is the offboarding control. Empire disabling a person’s Entra account is the backstop, because Microsoft then refuses the next sign-in before it reaches the CRM; it does not end a CRM session already open (that runs until it expires), so deactivating in the CRM is the step that takes effect at once.
- A shared inbox inside the CRM —
info@connected as an unowned mailbox with its own visibility and assignment rules (formerly F20-e; left V1 on 2026-09-24, Rev 37). Won’t-build reason: the accepted proposal scopes mailboxes as each user connecting their own; in V1info@inquiries are forwarded to a rep, whose own synced mailbox brings them in, orinfo@is added as an ordinary CRM user if it is a licensed mailbox that can sign in (§F20; OQ-52, OQ-54). - An audit-viewer screen (Rev 37, AD #36). Won’t-build reason: the audit trail is recorded in the database from the start (§Observability and Audit); in V1 it is queried there on request rather than browsed in the CRM.
- Hard delete of users (Rev 37, AD #34). Won’t-build reason: users are deactivated and reactivated, never deleted, so every record they owned, shared or changed stays attributable to them.
- Global search — one search box across accounts, contacts, deals, leads, quotes, buying standards and samples (formerly F31; left V1 on 2026-10-11, Rev 60). Won’t-build reason: each list screen carries its own search over its own records, and a user looking for a record goes to that list; the revised app frame has no top bar to hold a global box. The issued proposal names global search, so the departure is a post-issue note on it.
- The AI product-brief assistant — drafting a product brief from a rep’s rough notes (formerly F16; left V1 on 2026-10-11, Rev 61). Won’t-build reason: it was the first descope lever under R-ARCH-001; a rep fills the brief (F8) by hand, and F8-b’s open-questions gate still checks it. The issued proposal names it in the AI layer, so the departure is a post-issue note on it.
- AI matching of similar past quotes (formerly F7-e; left V1 on 2026-10-11, Rev 61). Won’t-build reason: a rep finds earlier quotes on the account and in the quote list; the quote assistant (F14) flags missing inputs and does not compare quotes.
- A separate price-lookup page (formerly F26-e; left V1 on 2026-10-11, Rev 61). Won’t-build reason: the Standards book (F26-b) already finds a standard by number or client with its published price, the account page shows an account’s standards, and the Tea Room’s weekly round (F26-f) shows the build-up and, under History, each standard’s published prices (F26-f FR-22); every past price stays in the effective-dated rows (AD #14).
- Creating custom fields during an import (formerly F23-c; left V1 on 2026-10-11, Rev 63). Won’t-build reason: an administrator creates the field first (F34), then imports; the import maps columns to fields that exist.
- The capture app’s same-day follow-up email — one generic email to each person met at the stand, sent from the capture app the same day (formerly F36-f; left V1 on 2026-10-11, Rev 63; Empire’s ask of 2026-09-09). Won’t-build reason: it needed its own sender and approval design (OQ-60, now closed). The same message can go to a show’s contacts as one bulk email to a saved contact list (F37-b, Phase 2), or a rep emails a lead from the CRM (F20).
- A full offline mode in the capture app — a background queue that stores captures and sends them on its own when a connection returns (formerly F36-e; left V1 on 2026-10-11, Rev 64). Won’t-build reason: the proposal does not name it, Empire never answered whether the halls lack connectivity (Q23 of the 2026-09-03 requirements questions), and iPhone browsers do not support background sync. (
client/open-questions.mdQ9 told Empire that working with no signal was agreed; the keep-and-retry below keeps that promise’s substance — no capture is lost — and Q9 carries a dated note.) F36-a instead keeps a capture whose upload fails, shows it as not sent, and sends it again when the app is open with a connection, so no card is lost. - The Pipedrive paid add-on equivalents — a website chatbot and live chat (formerly F27), an email-campaign product with a segmentation builder, campaign reports across sends, a drag-and-drop editor and subscriber management (formerly F28), purchased data enrichment (formerly F29), a LinkedIn integration (formerly F30), and sales goals and targets (formerly F35). Deferred from V1 on 2026-08-20; dropped on 2026-10-11, and not planned after V1 either (Rev 66). Won’t-build reason: none is expected to add enough for Empire to justify building it. Two things stay in scope and are not affected: bulk email (F37-a, the weekly price broadcast, and F37-b, one message to a saved list) and the AI lead research that reads public sources (F11-c, F36), which is not purchased enrichment. The issued proposal lists these add-ons as intended for a later phase pending the Pipedrive audit, so the change is recorded as a post-issue note on it. If Empire turns out to rely on one of them today, it goes through the change process (R-13).
Deferred (Post-V1)
Distinct from out-of-scope — these are intended later, gated by a trigger.
| Item | Target phase / trigger |
|---|---|
| Automated CRM↔ERP API sync (create sales order on Won; sync order/shipment/invoice status back) | When the client confirms the new ERP and that it exposes an API (Tier-1 Q2). Until then, F19 ships the manual handoff-document path. |
| Automated tea-auction price feed (pull auction reference prices in to assist the weekly bulk-pricing workflow — never auto-sets a price) | Post-V1 follow-on. A public API is confirmed available (2026-08-03) and architecture.md § Weekly Bulk Pricing Subsystem already carries the AuctionPriceProvider seam, so this is an implementation behind an existing interface, not a redesign. V1 weekly pricing stays manual (Tea Room publishes). Named in the accepted proposal’s deferred list; see also §Integration Points. Distinct from auction bidding, which is out of scope permanently. |
| RAG knowledge/compliance assistant (answer cert/SOP/country-requirement/packaging questions from Empire’s own documents) | When document sources are digitised and API-accessible (Tier-4 Q33). Most technically complex use case; later phase. [research: ai-in-workflows.md §2 Technique 4, §8 UC6] |
| Automated inbound-email trigger (auto-fire inquiry extraction on new mail) | When the automated-trigger design is settled — Graph change-notification volume, per-call AI cost, and the human-review queue shape. (The inbound channels themselves are settled: per-rep Microsoft 365 inboxes; info@ inquiries reach the CRM only when forwarded to a rep’s synced mailbox in V1 — OQ-14, revised by Rev 37.) V1 F12 runs on paste/forward-in manual trigger; F20 email sync provides the raw feed. |
| Multilingual AI extraction (Arabic/Turkish/Russian inquiry parsing) | When inbound-language mix is confirmed and prompts tested per language (Tier-4 Q31). V1 targets English. |
| Native mobile apps | Post-V1, if field/trade-fair usage demands beyond responsive web and the F36 capture PWA. |
| Multi-office data partitioning & cross-office visibility (SL / Kenya / NL / Shanghai / Spain) | If the client requires per-office data partitioning — records belonging to an office, walled off from other offices — beyond ownership, the reporting hierarchy and a region tag. V1 is single-instance with ownership. Distinguish from the reporting hierarchy (who reports to whom), which is in V1 scope since Rev 21 / AD #30 — a manager’s team scope follows the org chart, not the office; an office is still only a tag. |
| Sub-brand catalog & brand-management surface | The basic brand attribute on a buying standard and a deal (Thurson/Hyson/Akina/CWH) is in scope — OQ-20 resolved yes, Empire sells own-branded goods through this CRM (the attribute moved from Product to Buying Standard at Rev 27). What stays deferred is the richer brand-management surface (sub-brand catalog, per-brand reporting). |
| Courier/tracking API integration (live sample-shipment tracking) | Post-V1; V1 stores courier + tracking number as manual fields. |
| Granular visibility groups (arbitrary named groups of users sharing visibility, independent of the org chart) | If the client needs record visibility beyond what F5 provides. V1 covers access by configurable role + ownership + the reporting hierarchy (reach down the reporting line, widened to every record by an entity’s all key — Rev 43 / AD #37) + per-record sharing (Rev 29, revised Rev 37 / AD #35) + a region tag. Ad-hoc visibility groups that cut across the reporting line stay deferred. |
Reference-System Classification
Every major Pipedrive capability the client relies on, classified per the project constitution (§4). This guarantees the promise that the new CRM loses nothing the team depends on. Replicate = same behavior, new stack; Redesign = behavior improved/tea-specific; Defer = intended later (trigger noted); Discard = not needed. [research: pipedrive-crm-notes.md, competitive-landscape.md §3.1; source: Pipedrive doc research 2026-07-07]
| # | Pipedrive capability | Classification | Notes |
|---|---|---|---|
| P-01 | Organizations | Replicate | → F1 Accounts (enriched with tea-domain fields). |
| P-02 | People / contacts | Replicate | → F1 Account contacts. |
| P-03 | Deals + visual pipeline (Kanban, drag-drop) | Replicate | → F2. Same drag-drop stage-change UX. |
| P-04 | Pipelines & stages (admin-creatable, configurable) | Replicate + Redesign | → F2/F24. Admin-configurable stages (Pipedrive parity) seeded with two purpose-built tea pipelines (Private Label 10-stage / Bulk 4-stage) as defaults. [decision 2026-07-07] |
| P-05 | Leads inbox (unqualified) | Redesign | → F11 Lead Triage with AI scoring/dedup/drafts on top. Manual add + convert-to-deal preserved. |
| P-06 | Activities & follow-ups | Replicate | → F3. Activity types (call/meeting/task/deadline/email/lunch + custom). |
| P-07 | Date-based reminders / rotting | Replicate | → F3/F18/F24. Rotting = per-stage idle threshold configured in F24. |
| P-08 | Notes | Replicate | → F1 timeline/notes. |
| P-09 | Custom fields | Replicate + Redesign | Tea-domain attributes (grade, certs, packaging, Incoterm, volume units) are first-class typed fields; F34 adds an admin custom-field builder so admins can add fields without a code change; F23 import maps onto existing fields (creating fields on import was dropped, Rev 63). Pipedrive custom fields are not migrated (Rev 44). |
| P-10 | Reports & dashboards | Redesign | → F17 domain dashboard + weighted forecast (F24) + filterable, exportable list views (F32/F23); relied-upon Pipedrive reports inventoried via OQ-26. No separate ad-hoc report builder in V1 (decision 2026-07-07). |
| P-11 | Workflow automations (generic trigger/action builder) | Redesign / Discard | Domain automations built in (F18 stale/rotting alerts, F6 sample nudges, F9 cert checks); F25 sequences cover cadences. The open-ended no-code rule-builder is discarded. |
| P-12 | Email sync (two-way) & communication history | Replicate | → F20. Reps live in the Pipedrive inbox today → send/receive/reply in-CRM, mail auto-links to contacts/deals. Our build can also send automation from a shared address — an improvement over Pipedrive’s per-mailbox-only sending. |
| P-13 | Email templates, merge fields, tracking, group email | Replicate | → F20 for templates, merge fields and tracking; group email → F37 (committed to Phase 2 on 2026-10-09, Rev 57; its price broadcast, F37-a, accepted with Phase 1, Rev 100). |
| P-14 | Email sequences (cadences) | Replicate | → F25 (with AI-drafted steps). |
| P-15 | Calendar sync (Google/Outlook, two-way) | Replicate | → F21. |
| P-16 | Contact sync (auto-pull from email account) | Redesign | → F22. Pipedrive creates People automatically and can sync both ways; F22 reads one way, from Outlook into the CRM, offers new contacts on a per-user review list instead of creating them, and fills only empty fields on contacts the CRM already holds, so personal address-book entries stay out of the shared CRM (Rev 107). |
| P-17 | Spreadsheet import / export (CSV/Excel) | Replicate | → F23 (+ one-time migration F4). |
| P-18 | Stage probability / weighted forecast | Replicate | → F24/F17. |
| P-19 | Smart Docs / quotes | Redesign | → F7 Quote module with readiness gate + human pricing approval + buying-standard line items (F26); no CPQ auto-pricing. |
| P-20 | Products catalog | Redesign | → F26 as the Buying Standards book — no separate catalog (Rev 27): the client-specific standard is the sellable record for bulk and private label, carrying tea grade/origin/held-certs and the brand attribute (OQ-20 — confirmed); feeds F9 + F7. |
| P-21 | Native AI (email writer, sales assistant, Insights) | Redesign | Replaced by tea-domain Claude AI (F11–F15, F20/F25 drafting; F16 dropped, Rev 61) with HITL; Pipedrive AI has no domain context. [initial-findings.md §5.3] |
| P-22 | API / webhooks | Redesign | Own backend API; Claude called directly from backend. |
| P-23 | Chatbot & Live Chat (LeadBooster add-on) | Discard (Rev 66) | → F27, deferred from V1 on 2026-08-20 and dropped on 2026-10-11 (§Out of Scope). |
| P-24 | Email Campaigns (paid add-on) | Discard (Rev 66) | → F28, deferred from V1 on 2026-08-20 and dropped on 2026-10-11 (§Out of Scope). The plain bulk send is F37 (§In Scope gives each part’s phase). |
| P-25 | Data enrichment (Premium/Ultimate + 3rd-party) | Discard (Rev 66) | → F29, deferred from V1 on 2026-08-20 and dropped on 2026-10-11 (§Out of Scope). The AI lead research (F11-c) is not affected. |
| P-26 | LinkedIn (third-party only — not native) | Discard (Rev 66) | → F30, deferred from V1 on 2026-08-20 and dropped on 2026-10-11 (§Out of Scope); not a parity requirement. |
| P-27 | Marketplace / 500+ integrations | Discard | Only ERP + email/calendar/contacts + Claude are relevant (LinkedIn and enrichment were dropped in Rev 66). |
| P-28 | Projects | Discard | Not used in Empire Teas’ sales workflow. |
| P-29 | Mobile apps | Defer | Responsive web in V1; native apps deferred. |
| P-30 | Global search | Redesign (Rev 60) | → per-list search on each list screen (F1-b, F11-b, F5-c, F32-d, F32-a — Rev 84). The single search box across every record type (F31) was dropped on 2026-10-11 (§Out of Scope). |
| P-31 | List views / saved filters / bulk actions | Replicate | → F32 (+ export via F23). |
| P-32 | File attachments | Replicate | → F33. |
| P-33 | Sales goals / targets | Discard (Rev 66) | → F35, deferred from V1 on 2026-08-20 and dropped on 2026-10-11 (§Out of Scope). |
| P-34 | Visibility groups | Redesign | Covered by F5 role + ownership + the reporting hierarchy + per-record sharing + region scoping (AD #35); granular visibility groups deferred. |
Phasing / Sequencing Intent
Loose ordering — architecture (Gate 2) and decomposition (Gate 3) firm this up. Dependencies drive sequencing within/across phases; “clean core data before AI” is the load-bearing rule. [research: ai-in-workflows.md §6]
| Phase | Theme | Features | Rationale / dependency |
|---|---|---|---|
| P0 — Core CRM, email & migration | Replace Pipedrive; nothing lost | F5, F1, F2, F3, F17, F4, F20 | Foundation. Auth/users → accounts/contacts → deals/pipeline → activities → dashboard → email-in-CRM (reps live there today) → migrate clean data (global search, F31, was dropped in Rev 60). Everything else depends on these entities existing. F23 moved to P1c — see the reconciliation note below. |
| P1a — Domain workflows & pipeline config | Model the real sales process | F6, F8, F26, F9, F10, F7, F24, F18 | Depends on Accounts + Deals (P0). Buying standards (F26) feed the cert-check (F9) + quote line items (F7); pipeline config (F24) sets stages/probability/rotting; samples/briefs/export-docs/quotes attach to deals; stale/dormant alerts (F18) sit here because proposal § 7 names them in 1a explicitly — they ride F24’s thresholds and the Foundation scheduler. F19 moved to P1c — see the reconciliation note below. |
| P1b — AI productivity & outreach | Human-in-the-loop AI | F11, F12, F13, F14, F15, F25 (F16, the product-brief assistant, was dropped in Rev 61) | Depends on clean core data (P0) + domain entities (P1a). Lead triage + inquiry extraction (fed by F20 email) → briefings → quote assistant → dashboard AI → sequences for re-engagement. |
| P1c — Sync & parity conveniences | Reduce manual entry; close parity gaps | F21, F22, F32, F33, F34, F23, F19 | Calendar + contact sync (depend on F20 connections); list/table views + saved filters + bulk actions; file attachments; admin custom fields; spreadsheet import/export (F23) and the ERP handoff document (F19) — both moved here 2026-08-06 to match the proposal’s paying phase boundaries. |
| Capture stream (parallel) | Trade-show capture companion | F36 | Parallel third work-stream, delivered in Phase 1 since 2026-11-11 (Rev 91; Gate 3 had placed it alongside the Phase 2 work), scope unchanged; feeds F11 once a person converts each captured lead (Rev 95); the descope lever to capture-and-feed is decided at the capture-app checkpoint, which the Statement of Work of 2026-09-29 holds during Phase 2, now proposed for Fri 2026-11-20, to be confirmed with Empire (client/project-timeline.md §2). |
| Post-V1 — Enhancements | Polish & later value | The items in §Deferred (Post-V1), as their triggers clear (F27–F30 and F35 were dropped in Rev 66) | Non-blocking; scheduled after V1 core is adopted. |
Re-grouped at Gate 3 (2026-09-17) — this supersedes the consolidation below for what ships in which phase. Phase 1 is users and roles, accounts and leads (with the lead and account AI), email and templates, follow-up tasks, record sharing and the weekly prices; deals, the tea-export workflow, dashboards, the remaining AI and parity are Phase 2. The capture app, placed in Phase 2 at Gate 3, moved to Phase 1 on 2026-11-11 (Rev 91). Parity work that needs no deals was then built early and accepted with Phase 1: email open and click tracking and scheduled send, the weekly price broadcast, and list views, attachments and custom fields on accounts, contacts and leads (Rev 90, Rev 92, Rev 100); further Phase 2 work is started early in Phase 1 and joins it only when done, otherwise moving back to Phase 2 at the end of Phase 1’s UAT round (Rev 102; the production environment, F38-i, keeps its own rule). The same scope in a different order: the live assignment is each feature’s
delivery_phaseintracker.yaml(summarised infeatures.md § Delivery Plan), and the proposal records it in its 17 September 2026 post-issue note.Delivery consolidation (2026-08-18): for acceptance, delivery groups the four build buckets above as Phase 1 = P0 + P1a and Phase 2 = P1b + P1c, with a client UAT round after each phase (
client/project-timeline.md). Scope per bucket is unchanged; the proposal’s finer labels remain the mapping key. (The enhancements bucket above was relabelled Post-V1 so “Phase 2” is unambiguous.)
Phase reconciliation (2026-08-06) — F19 and F23 moved to align with the issued proposal.
This table previously placed F23 (spreadsheet import/export) in P0 and F19 (ERP handoff document) in P1a.
project-proposal.md § 6places both in Phase 1c. That is not a loose internal grouping to overrule: § 6 and § 17 tie milestone acceptance and payment to those phase boundaries, so the proposal’s phasing governs and Gate 3 must assigndelivery_phaseaccordingly.Two consequences to carry into decomposition, neither of them blocking:
- The import engine is still built in P0. The proposal keeps “the Pipedrive migration” in Phase 0, and F4 shares F23’s engine. So P0 builds the engine to serve F4’s one-time migration; F23 in P1c is the work of exposing it as a general-purpose, user-facing import/export tool (header mapping onto existing fields, merge-or-create dedup, list-view export; custom-field creation on import was dropped, Rev 63). Splitting it that way satisfies both documents — do not read “F23 is P1c” as “no import code until P1c.”
- Deals can reach Won before F19 exists. With the handoff document in P1c, a deal closing during P1a/P1b has no generated handoff. That is the proposal’s sequencing, and it is survivable — the ERP handoff is a manual document path in V1 anyway (AD #10) — but the team should expect to hand off the first Won deals by hand, and should say so to the client rather than discover it live.
Domain Model
Key Entities
| Entity | Description | Key Relationships |
|---|---|---|
| User | A CRM user, pre-created by Empire’s administrator (the holder of settings.manage; access.manage until Rev 79) — no self-sign-up, auto-provisioning or invitation email; sign-in succeeds only when the Microsoft-verified email matches exactly one active user (Rev 37 / AD #34). Holds exactly one role, mandatory from creation (Rev 24 / AD #32; no role is predefined — Empire’s administrator creates every role from the catalog, and the six confirmed roles are the recommended day-one set). Deactivated and reactivated, never deleted. Owns records; their own mailbox and calendar are connected at sign-in when their role holds email.manage (Rev 74). May name a manager — the reporting hierarchy that decides whose records a manager reaches (AD #37). The first user in every environment is seeded by a Flyway migration, holding the editable IT Admin role, with an email set per environment (AD #34). |
1:N owns Leads, Accounts, Deals, Quotes, Samples; 1:N is assigned Activities; 1:N MailboxConnection (own mailbox; typically one); N:1 manager (self-reference, nullable); N:1 Role (mandatory, one role per user); 1:N Record shares (as the user a record is shared with). |
| MailboxConnection | A granted Microsoft 365 mailbox/calendar/contacts connection (Graph), per user only: each user’s own mailbox is connected (automatically at sign-in when their role holds email.manage, Rev 74), and no role can read another person’s mailbox (AD #34). There is no unowned (shared) connection in V1 — info@ is handled by forwarding to a rep (OQ-52, OQ-54 resolved, Rev 37; the shared inquiries inbox, F20-e, left V1 on 2026-09-24). |
N:1 User; 1:N Emails; feeds calendar (F21) and contact (F22) sync. |
| Record share | One row per record shared with one user (Rev 29, revised Rev 37 / AD #35), in a single record_share table: a nullable foreign key per shareable entity type — account_id and lead_id in Phase 1, deal_id and quote_id when those entities land — with a check that exactly one is set; the user it is shared with, the user who shared it, and when; unique per (record, user). No array columns. A share carries no access level — it widens reach, never authority (§Multi-Tenancy / Org Hierarchy). Built by F5-f. |
N:1 User (shared with); N:1 User (shared by); N:1 one of Account / Lead (later Deal / Quote). |
| Audit event | One row per write or security event (Rev 37 / AD #36), in a single audit_event table written in the same transaction as the change: who (a user, or SYSTEM for background jobs), what, which record, when, and the change. Append-only; reads are not recorded; kept indefinitely in V1; no viewer screen in V1. Built by F39, which also decides how the SYSTEM actor is stored. |
N:1 User (the actor, when a person acts); optionally N:1 the record it concerns. |
| Account (Organization) | A buyer company. Carries type, country/region, required certifications, preferred packaging, Incoterms, LTV, dormancy. | N:1 owner (required — AD #35); 1:N Record shares; 1:N Contacts; 1:N Deals; 1:N Samples/Quotes/Activities/TimelineEvents/Orders/Emails; N:N Certifications (required). |
| Contact (Person) | An individual at an account (role, a main email address and any others — Rev 77). May be added from a user’s Outlook contacts (F22). | N:1 Account; 1:N Emails/Activities. |
| Lead | An inbound, pre-qualification inquiry with AI priority/confidence/summary/draft reply (generated on request and not kept, Rev 56, Rev 73) and spam/duplicate tag, plus a first-class lead source (Website, Trade Fair, Referral, Email, Other) set on creation. Lives in the triage inbox, not a pipeline stage. Empire uses both leads and deals in Pipedrive today, with this split: a lead is an inquiry not yet qualified, kept in the inbox; a deal is one a rep has decided to pursue, worked on a pipeline; a lead becomes a deal only when a person converts it (OQ-5, Rev 51). | Converts to a Deal (+ Account/Contact). N:1 matched Account / Contact (optional, before conversion). N:1 owner (nullable only for import edge cases; an unowned lead is visible only to all-scope holders — AD #35); 1:N Record shares; N:N Sequences (enrollment). |
| Deal (Opportunity) | A sales opportunity on a pipeline, at a stage, with value, volume, buying-standard line items, held certifications, age-in-stage, rotting flag, stage-probability-weighted value. | N:1 Account; N:1 Pipeline+Stage; N:1 owner; 1:1 ProductBrief (private label); 1:N Samples; 1:N Quotes; N:N Buying Standards (line items — Rev 27); N:N Sequences (enrollment). |
| Pipeline | An admin-configurable board of ordered Stages. Seeded with Private Label + Bulk defaults. | 1:N Stages; 1:N Deals. |
| Stage | A step in a pipeline with a name, win probability (0–100%) and a rotting threshold (idle days). | N:1 Pipeline; 1:N Deals (current). |
| Product Brief | Structured internal spec for a private-label deal + blocking open questions. | 1:1 Deal (private label). |
| Removed — Rev 27 (2026-09-15). There is no separate products catalog: the Buying Standard (next row) is the sellable record for bulk and private label, and everything this row carried moves onto it — tea grade, origin, held certifications, the brand (OQ-20), cost and price history. The pricing rules stand, now stated on the standard: prices maintained in USD with other currencies as display conversions (OQ-43); one price per standard, changing weekly (Rev 23); no formal volume tiers (OQ-45); each price holds until the next weekly auction — a single clock shared with the quote — with a manual override (OQ-33). | — (the shipped product table, catalog package and product.* permission keys are retired by the backend hand-off recorded in Rev 27). |
|
| Buying Standard | The sellable record — for bulk and private label alike (Rev 27, replacing the catalog). A client-specific specification (a grade/blend a client buys, e.g. BOP1, POSOS, or a private-label item) identified by a unique running number never reused across clients (OQ-42 confirmed 2026-08-03), carrying tea grade, origin, brand (OQ-20) and held certifications, a per-standard cost, and a lifecycle — created, edited and archived (archiving keeps the price history and removes the standard from quoting and the weekly round). A client holds many (Empire’s list runs to ~35,000 numbers ever issued, ~1,450 priced in a current week — workbook seen 2026-09-11). One weekly price attaches to each standard — it does not vary by customer or destination market (Rev 23, revising the OQ-38 answer; market remains a customer attribute and a quote field, never a price key). Whether private-label standards join the weekly round or stay priced per quote is OQ-61. | N:1 Account (client); N:N Deals (line items w/ qty+discount); N:N Certifications (held); 1:N weekly prices; referenced by Quote line items (F7) and the cert-check (F9). |
| Sample | A physical sample for a deal, with round number, lifecycle state, owner (taster), courier/tracking, due date, outcome. | N:1 Deal; N:1 Account; N:1 owner. |
| Quote | A priced offer for a deal/account, with the readiness checklist, status, aging, gross-profit % (computed from the standard’s cost), a payment-terms field (LC / Open Account / DA / CAD / advance — set per customer by finance, OQ-10 confirmed), Incoterm/currency/destination, line items, and version revisions. Quotes at or above the required gross-profit % floor submit without special approval; sub-floor quotes require Managing Director approval (OQ-40 confirmed) — delivered as the quote.approve_sub_floor key, which the recommended configuration gives to the Managing Director’s role only (Rev 37 / AD #34). |
N:1 Account/Deal; N:1 owner (an active owner always — Rev 23); 1:N Revisions; N:N Buying Standards (line items). |
| Activity (Task) | A follow-up/reminder/task of a type (call/meeting/task/deadline/email/lunch/custom), with due date/time and status, linked to an account/deal/lead; appears on the calendar (F21). | N:1 Account/Deal/Lead; N:1 assignee (an active user who holds the record’s manage key and reaches it; the assignee gives no reach of its own). |
| Email / Message | A synced or CRM-sent email linked to a contact/deal/lead; tracks opens/clicks; may be AI-drafted (F11/F20). | Many links per email, one per record — an Account, Contact or Lead, and a Deal from Phase 2 (Rev 104); N:1 MailboxConnection; uses an EmailTemplate. |
| Email Template | A reusable, team-shareable email body with merge fields. | Used by Emails and Sequence steps. |
| Sequence | A multi-step outreach cadence (email + task steps) enrolled on deals/leads. | 1:N Steps; N:N Deals/Leads (enrollments); Steps use EmailTemplates. |
| Timeline Event / Communication | A dated event on an account (lead/order/sample/call/quote/note/email). | N:1 Account. |
| Note | Free text a user writes on a record (Pipedrive notes parity), with its author and, once edited, who edited it and when (Rev 59). Any user who may manage the record may add, edit or delete any note on it, and every change is audited (AD #34, AD #36). A deleted note is marked deleted and kept, never removed; it disappears from every screen and its timeline entry goes. An account’s notes appear on its timeline; a contact’s and a lead’s do not. Pipedrive notes are not migrated (Rev 44). Built by F1-e (accounts, contacts) and F11-f (leads). | N:1 Account, Contact or Lead (exactly one owning record governs its reach — the account when set); N:1 User (author). |
| Tag | A label that groups and filters records, kept per entity type — account, contact, lead or deal — as Pipedrive’s labels are, with a name unique within its type regardless of case, and an optional colour from the design system’s badge tones (Rev 38, Rev 59). Required by F1 (grouping and filtering, Rev 23) and consumed by F32’s saved filters. The list of tag names is readable by any signed-in user; tagging a record is part of managing that record; renaming or retiring a name is configuration. A tag is retired, never deleted: it stays on the records that carry it and is no longer offered (Rev 59). | N:N Accounts, N:N Contacts (F1-a); N:N Leads (F11-a); N:N Deals (F2-a). |
| Order | A past/confirmed order (ERP-sourced, read-only reference). | N:1 Account. Source of record = ERP. |
| Certification | Reference entity (EU Organic, Halal, JAS, BRCGS, FDA, …). | N:N Accounts (required); N:N Buying Standards (held). |
| Export Document Rule | Config/reference: base docs, per-country docs, per-certification docs — drives F10. | Referenced by the export-doc checklist. |
| File Attachment | An uploaded file (artwork/PO/spec/cert PDF) linked to any core record. Uploader, date, size, type; validated, and recorded as not scanned while virus scanning is switched off (Rev 58). | N:1 any record (Deal/Account/Contact/Lead/Quote/Sample/Brief; Lead added Rev 85); N:1 uploader. |
| Custom Field Definition | An admin-defined field (name, type, options) attached to an entity (F34). | 1:N field values across records of that entity. |
| Saved View | A named, filtered/sorted list view (personal or shared) over an entity (F32). | N:1 owner; per entity. |
| Reference lists | Countries/markets, regions, packaging formats, Incoterms, currencies, buyer types, couriers, activity types, tea grades. | Referenced across Accounts/Deals/Quotes/Samples/Buying Standards. |
| Captured lead (capture app, F36) | A business card or badge captured at a show, held in the capture app with its card reading, research and booth note until a person converts or rejects it (Rev 95); a rejected one stays in the app only (Rev 97). | N:1 capturing User; N:1 Capture campaign (optional); N:1 Lead once converted. |
| Capture campaign (capture app, F36) | One trade show the reps plan and work: a name and the show’s first and last day, archived and restored (Rev 96, Rev 97). Not the dropped marketing Campaign below. | 1:N Exhibitors; 1:N Captured leads. |
| Exhibitor (capture app, F36) | A company exhibiting at a show, loaded from the show’s list or added by hand, with its stand, a visit note and a visited mark, researched and ranked (Rev 96, Rev 97). | N:1 Capture campaign. |
| (Not built) Campaign, Chatbot Playbook, Goal/Target | Marketing newsletter (F28) — not the capture app’s Capture campaign above —, website chat playbook (F27), and sales goals (F35) — not modeled; all three were dropped in Rev 66. F37-b (committed to Phase 2, Rev 57; started early in Phase 1, Rev 102) needs a minimal send record, per-recipient delivery and tracking states, and a list of addresses left out of bulk sends (unsubscribed or bounced) — a fraction of F28’s Campaign entity. There is no per-contact consent state (Rev 103, resolving OQ-62). | — |
Lifecycle States
- Lead:
new → approved | converted | archived, andarchived → new(restore). Archive / nurture is thearchivedstatus — there is no separate nurture status; archive is allowed fromnewandapproved, never fromconverted, and restore returns an archived lead tonew. AI attributes: priorityP1|P2|P3(three levels — Rev 55), tagnull|SPAM|DUPLICATE, confidence 0–100. [prototype §5] - Captured lead (capture app):
to_review → converted | rejected, andrejected → to_review(moved back);convertedis final and creates the Lead, atnew(Rev 95, Rev 97). - Deal — Private Label pipeline (10 default stages):
New inquiry → Qualified buyer → Brief captured → Sample requested → Sample dispatched → Sample feedback → Artwork approval → Quote submitted → Negotiation → Won (→ ERP handoff). Exit:Lost/Dormant. Stages are admin-editable (F24). [prototype §5] - Deal — Bulk pipeline (4 default stages):
New inquiry → Quote submitted → Negotiation → Won (→ ERP handoff). Exit:Lost. [prototype §5] - Deal freshness (per F24 rotting):
fresh → rotting(turns red when untouched beyond the stage’s rotting threshold; resets on activity/note/email/edit). - Sample (7 states):
Requested → Blended/Prepared → Dispatched → Delivered → Feedback due → Feedback received → Outcome. Multi-round per deal. [prototype §5] - Quote:
Draft (inputs incomplete) → Awaiting margin approval → Submitted → (in negotiation) → Won | Lost. Submission gated on the 8-item readiness checklist + human pricing approval. [prototype §2.6, §5] - Activity:
open (overdue | today | upcoming) → done,done → open(reopen). [prototype §5; F3-a spec FR-V3] - Sequence enrollment:
enrolled → active → completed | failed | unenrolled(a sequence locks to deals-only or leads-only once first used). [source: Pipedrive doc research — sequences] - Email:
draft (may be AI-generated) → (scheduled →) sent → opened → clicked(tracking states, for an email the rep chose to track; nodeliveredstate for a single email — F20-g, Rev 89) /received. A scheduled email:scheduled → sent | cancelled | failed. - CRM→ERP handoff (on Won):
pending → generated/sent(manual document path in V1). [prototype §2.8]
Glossary
| Term | Meaning |
|---|---|
| Bulk tea | Raw made tea sold by weight (kg/MT) to importers/blenders/brands who reprocess or rebrand. Empire’s highest-volume line. |
| Private label | Empire manufactures tea under the buyer’s own brand (their logo/design), shelf-ready. Higher complexity/margin. |
| Made tea | Processed, dried, graded tea (vs green leaf). |
| Tea grade | Size/form classification of the dried leaf (OP, BOP, BOPF, Dust, etc.) — drives price, use, sourcing. |
| Orthodox / CTC | Two processing methods. Orthodox = whole/broken leaf (higher value); CTC (Crush-Tear-Curl) = fannings/dust for teabags (higher volume). |
| BOPF | Broken Orange Pekoe Fannings — the main Sri Lankan teabag grade. |
| Colombo Tea Auction | Weekly auction where exporters buy made tea; sets the fluctuating baseline cost of tea. |
| Incoterm | Trade term defining who pays freight/insurance and where risk transfers (EXW, FOB, CFR, CIF). |
| CIF / FOB | CIF = Cost, Insurance & Freight to destination port (dominant in Ceylon tea). FOB = Free On Board at Colombo. |
| Ceylon Tea | Legally protected designation — 100% grown & manufactured in Sri Lanka, SLTB standards. Kenya-origin tea cannot use it. |
| SLTB | Sri Lanka Tea Board — authorises every export shipment; issues Lion Logo, GMP, export authorisation. |
| Lion Logo | SLTB trademark certifying 100% Pure Ceylon Tea packed in Sri Lanka. |
| CUSDEC / ASYCUDA | Customs Export Declaration submitted through Sri Lanka’s national customs system (ASYCUDA). |
| MOQ | Minimum Order Quantity. |
| LC / DA / DP | Payment terms: Letter of Credit / Documents against Acceptance / Documents against Payment (+ Open Account). |
| Phytosanitary certificate | Plant-health export certificate required by many destinations. |
| MRL | Maximum Residue Limit — pesticide residue thresholds (strict in EU, esp. organic). |
| Sample round | One iteration of the develop→dispatch→feedback cycle; private-label deals commonly run 2–5 rounds. |
| Product brief | Internal structured spec turning a buyer’s private-label request into R&D/packaging instructions. |
| Certification mismatch | When a buyer requires a certification the quoted buying standard does not hold — flagged before quoting. |
| ERP handoff | The point a Won deal’s data is passed to the ERP (which owns confirmed orders onward). |
| Tea taster | Qualified professional who assesses/blends tea; a registered role required of SLTB-registered exporters. |
| Quality season | The window when a region produces its best tea (varies by region/monsoon). |
| Dormant account | A customer with no contact/order beyond a threshold (e.g. >90 days) — a reorder-recovery target. |
| Stage probability | Per-stage % likelihood a deal is won; produces a weighted forecast (a $10k deal in a 40% stage counts $4k). [Pipedrive parity] |
| Rotting | An idle-deal flag: a deal untouched longer than its stage’s rotting-days threshold turns red; the clock resets on any update. [Pipedrive parity] |
| Sequence | A multi-step, scheduled outreach cadence (emails + tasks) enrolled on a deal/lead. [Pipedrive parity] |
| Merge field | A placeholder in an email template auto-filled from deal/contact/org fields. [Pipedrive parity] |
Users and Access
Roles
| Role | Description | Primary Capabilities |
|---|---|---|
| Sales Rep | Owns leads, accounts, deals, quotes, and their email for their book of business; is assigned activities. Day-to-day CRM driver. | Create/manage own leads/accounts/deals/quotes, and the activities on the records they own or that are shared with them; send email + use templates/sequences; request samples; use AI drafts (approve/send); prepare quotes (cannot approve pricing). |
| Sales Manager / Lead | Sales Rep capabilities plus team oversight. Reps quote freely at or above the required gross-profit % floor; sub-floor quotes escalate to the Managing Director. | All Sales Rep actions across the team; reassign owners; full pipeline/dashboard/forecast visibility; quote oversight (the sub-floor margin-override approval is the Managing Director’s — see note). |
| R&D / Sample Owner (Taster) | Owns the sample development lifecycle; reads product briefs. | Manage samples (prepare → dispatch → deliver → log feedback → outcome); read product briefs; log blend notes; cannot manage quotes/pricing. |
| Administrator | System configuration and reference data. | Manage users, roles and the reporting line; configure pipelines (stages/probability/rotting), reference data (certifications, export-document rules, dropdown lists — in V1 the account dropdown lists are fixed in code and changed by a small developer release, with no administration screen; the certification list is a table), email templates, and sequences — all under one key, settings.manage, which opens every page of the CRM’s Settings page (Rev 79: it absorbed the separate access.manage); run/oversee data migration & import; full data access. |
| Tea Room (Pricing) | The pricing team (a distinct group, confirmed 2026-08-03). Sets and publishes the weekly bulk prices and owns pricing configuration. | Set/publish weekly bulk prices per client-specific buying standard; create, edit and archive standards (bulk and private label — Rev 27) and set their costs; read pipelines/quotes for pricing context; read-oriented on other sales records. |
| Executive / Management (read-only) | Oversight without edit rights (confirmed 2026-08-03). | Read-only across dashboards, pipeline, forecast, quotes, and reports. |
| Managing Director (recommended role, created by Empire’s administrator — not seeded; Rev 19, restated Rev 37) | The MD’s own access: oversight plus the one approval authority the client reserved to the MD (OQ-40). | The Executive read-only view plus quote.approve_sub_floor, the key that approves sub-floor quotes; the sole holder of that key by recommended configuration, not by a code rule (AD #34); configures nothing, sets no price. |
V1 roles (confirmed 2026-08-03): Sales Rep, Sales Manager, R&D/tea taster, Administrator, Executive/Management read-only (confirmed, OQ-47), and a distinct Tea Room role — the pricing team that sets and publishes the weekly bulk prices, confirmed as a separate group needing its own access (OQ-39). QA/Compliance and Export-Documentation Coordinator are not separate V1 roles (covered by Sales Manager + Admin). Pricing approval is a gross-profit-% floor gate: reps quote freely at or above the required margin; sub-floor quotes require Managing Director approval (OQ-40). The client also asked for granular permission levels — read-only, edit, AI-use, and execute — layered on these roles (OQ-47); since Rev 37 (AD #34, 2026-09-24) that is met by a
viewand amanagekey per entity plus a short list of special keys, with no category axis (§Permission keys). One consequence is stated plainly: an outward action on a record is no longer grantable apart from managing that record, except where it has a key of its own (price.publish,quote.approve_sub_floor, andemail.managefor sending from one’s own mailbox). These six roles are the recommended day-one roles, not a fixed role set and not seeded data: a fresh installation ships with the Flyway-seeded IT Admin role and one user holding it (AD #34), and Empire’s administrator creates every other role from the code-declared permission catalog (Altrium supervising at go-live). The Primary Capabilities column above describes the recommended configuration. The confirmations above (who exists, the pricing rule, the AI rule) stand; the mapping is Empire’s to edit.
Per-Role Capability Matrix
Status since Rev 21 (AD #30), restated at Rev 24 (AD #32) and Rev 37 (AD #34): this matrix is the recommended day-one configuration for the six roles — not fixed truth, not a template and not seeded data. The system ships with one Flyway-seeded, editable IT Admin role holding
settings.manage(access.manageuntil Rev 79) and one user holding it, whose email is set per environment; Empire’s administrator creates each other role by hand from the permission catalog (Altrium supervising at go-live). Nothing in code ties a cell to a role: every cell below is a set of catalog keys — an “all” cell includes the entity’sallkey (AD #37) — and the holder ofsettings.managecan change any of them. The matrix still matters: it is what Empire signs off as the starting point and what training assumes.
Actions: Create · Read · Update · Delete · Approve · Cfg (configure). Each cell is expressed in the catalog of §Permission keys: R is the entity’s view key; C, U, archive, reassign, share and A on a record are the entity’s manage key, unless the cell names a special key; Cfg is settings.manage. Reach (§Multi-Tenancy / Org Hierarchy; Rev 43, AD #37): “own” and “team” are the one reporting-line rule, as it applies to a user with nobody below them (records they own or that are shared with them) and to a manager (records owned by, or shared with, them or anyone below them in the reporting tree); “all” = the role also holds the entity’s all key — every record, unowned ones included. Blank or — = no access.
Permission keys
The four levels the client asked for (OQ-47) — read-only, edit, AI-use and execute — are met since
Rev 37 (AD #34, 2026-09-24) by a minimal catalog, with no category axis. (Rev 17 fixed the
levels per role; Rev 21 made the level each permission’s category; Rev 24 reduced the categories to
read / edit / execute; Rev 37 removes the axis.) Each business entity has two keys:
<entity>.view (read-only) and <entity>.manage (create, edit and every action on the
entity — archive, share, remove a share, reassign the owner, and AI-assisted drafting on it).
manage implies view. Each entity that has an owner has a third key, <entity>.all, which
widens the holder’s view or manage on that entity from the records the reporting line reaches to
every record (§Multi-Tenancy / Org Hierarchy); it means nothing without one of the two. Separate keys
exist only for a short list of special actions. The catalog is code — each module declares its keys
with label, description and UI group — and the grants are data: (role, permission_key), with no
scope (Rev 43, AD #37; from Rev 21 to Rev 42 each scoped key was granted at own, team or
all). The authoritative key list is FS-6 Appendix A (F5-l adds the all keys to it); the V1 set is:
| Key | all key? |
Covers | Phase |
|---|---|---|---|
settings.manage |
no | Everything on the CRM’s Settings page. Configuration: reference data (the tags and the certification list included), shared templates, the AI feature switches (AD #19) and imports; pipelines and custom fields in Phase 2. And all user, role and reporting-line administration: create, edit, deactivate and reactivate users; assign each user’s role and manager; create, rename, edit and delete roles; the effective-permissions viewer, audit access and runtime log-level changes (Rev 79 — the separate access.manage key was folded in on 2026-10-26) |
1 |
lead.view / lead.manage |
lead.all |
Leads and their children | 1 |
account.view / account.manage |
account.all |
Accounts and their contacts, notes, tasks, attachments and timeline; and the account’s buying standards with only the final published USD price (default awaiting the lead’s confirmation — Rev 37) | 1 |
email.manage |
no | The holder’s own mailbox only — connect, read, send, drafts. There is no email.view, and no key reaches another person’s mailbox |
1 |
email.bulk_send |
no | Send one message to the contacts of a saved contact list from the holder’s own mailbox, and follow and stop their own bulk sends (F37-b). A role holds it only beside email.manage; held by no role until an administrator grants it (Rev 103) |
2 (started early) |
buying_standard.view / buying_standard.manage |
no | The standards book, the published prices and the full price build-up — costs, margins, the floor and the LKR figures (there is no separate cost key); manage edits standards, costs and the floor, and imports the weekly workbook |
1 |
price.publish |
no | Publish the weekly prices. A role holds it only beside buying_standard.view or buying_standard.manage, because publishing happens on the Pricing page (Rev 71) |
1 |
capture.use |
no | Full use of the trade-show capture app (F36): capturing, planning a show, and reviewing, converting and rejecting captured leads — converting also needs lead.manage (Rev 96); no finer capture-app key (Rev 95) |
1 |
deal.view / deal.manage |
deal.all |
Deals, with their ERP handoff, product briefs and export documents | 2 |
quote.view / quote.manage |
quote.all |
Quotes | 2 |
quote.approve_sub_floor |
no | Approve a quote below the margin floor | 2 |
sample.view / sample.manage |
sample.all |
Samples | 2 |
Retired at Rev 37. The separate administration keys (user.*, role.*, hierarchy.edit,
permission.view_effective, audit.view, platform.loggers.write) fold into access.manage, itself
folded into settings.manage at Rev 79;
contact.* into account.*; attachment.* into the parent record’s key; certification.* into
reference data (any signed-in user reads the list, settings.manage edits it, and an account’s own
required certifications are edited under account.manage); mailbox.read, email.send and any
email.view into email.manage; cost.*, price.view and margin_floor.* into
buying_standard.*; pipeline.*, custom_field.*, reference_data.* and ai_settings.* into
settings.manage. No keys at all for dashboards and reports (each tile shows only what the
entity keys reach), search (filtered the same way), tasks (a task follows its record), reading
reference data (any signed-in user), or exports (an export follows view and is audited). There is
no read-only user-list key: every signed-in user reads a minimal directory of active users’ names
and role names for the share, owner and manager pickers, and the full user list is behind
settings.manage.
Where the AI sits (Rev 24, restated Rev 37 — replaces the AI-use level of Rev 17 / Rev 21).
Two kinds of AI work exist, and neither is a permission of its own:
- AI the system runs on its own — lead scoring and triage, inquiry extraction on intake, the
morning briefing, duplicate and spam detection. Nobody “invokes” these, so
there is nothing to grant: the result is visible to whoever holds the
<entity>.viewkey that reaches the record it belongs to, and the only control is the per-feature{model, enabled}switch (AD #19), set undersettings.manage. - AI a user invokes on a record — draft a reply or an email, the account briefing (Rev 76, AD #32), the quote assistant. The ability to ask for the draft is implied by the record’s
managekey (drafting an email:email.manage; an account briefing:account.manage): whoever may send an email may ask for a draft of one; whoever may edit a quote may ask the quote assistant to check it. There is no separate AI grant, so nobody can hand out “AI” detached from the action it serves, and a view-only role never triggers AI work.
The human-in-the-loop invariant is unchanged and still structural: the AI layer only ever
produces a proposal; committing it — sending, approving, publishing, handing off — is an action a
person performs under a manage key or a special key. The AI holds no permission at all, so there
is no path by which an AI feature performs an outward action.
Special keys, and the Managing Director
Some authority does not decompose into view or manage on an entity — sub-floor quote approval
(OQ-40) is the V1 example. These are special keys granted to roles: quote.approve_sub_floor is
granted to whichever role Empire’s administrator decides holds that authority.
Who holds it is configuration; how it is checked is not. An authorization check names the
permission it needs, never the role that happens to carry it — F7 checks quote.approve_sub_floor,
never user.role == ADMIN. See AD #26.
Recommended configuration (Rev 19, restated Rev 37 — Rev 19 superseded the 2026-08-21
Administrator default): quote.approve_sub_floor is held by a Managing Director role — the
Executive read-only keys plus this one special key — and that role is held by the Managing Director’s
account alone. In the recommended configuration, Administrators and Sales Managers do not hold
it. The approval record carries the approver’s name and email, so who approved what is never in
doubt. The client stated this on 2026-08-03 (“special approval from the Managing Director”) and the
issued proposal commits to it (“approved by the Managing Director”); since Rev 37 (AD #34) that
commitment is met by configuration, not by a code rule — nothing in code stops the holder of
settings.manage granting the key to another role, their own included, and every such grant is
recorded in the audit trail (AD #36). Pending client confirmation — see the client question set
(Q3), which asks Empire to confirm the MD-only arrangement, to name a deputy for absences if they
want one, and to say whether the MD also needs a day-to-day working role.
The Managing Director role is created by Empire’s administrator like every other role; nothing
but IT Admin is seeded (AD #34). Every alternative stays one configuration change away — giving the
key to a deputy’s role during an absence, adding it to another role, or adding day-to-day
permissions to the MD’s own role (a user holds one role, so the MD’s role carries whatever the MD
needs). What the design forbids is only F7 learning the answer as a role test — because
role == MANAGING_DIRECTOR would have to be found and rewritten if any of those changes ever happen.
Separation of duties is configuration only (Rev 37 — replaces the Rev 19 note). In the recommended configuration the Tea Room sets the margin floor and only the Managing Director approves below it, so no single account in that configuration can lower the floor and then approve a quote against the lower figure. Nothing in code enforces this: self-escalation is unlimited, and the holder of
settings.managemay grant any key to any role, their own included (AD #34). The audit trail (AD #36) is the control — every grant, floor change and approval can be attributed afterwards. The one cost of the recommended arrangement is availability: while the MD is away, below-floor quotes wait unless a deputy’s role has been given the key (a grant, audited).
The Tea Room and Executive role contents need no definition here (OQ-53 closed, Rev 37). The lead’s position: every role is Empire’s configuration, and Empire may not create these roles at all, or may name them differently. Tea Room and Executive / Management are described in prose above but have no column in the matrix. As optional advice only: the Tea Room holds
buying_standard.view,buying_standard.manageandprice.publish— plus a lead’s or deal’sviewkey if reps are to pull the Tea Room onto a specific record for pricing input, because a share is offered only to users whose role can view that entity (AD #35); the Executive holds every entity’sviewkey and, where the entity has one, itsallkey (AD #37), with or withoutbuying_standard.view(the costs and margins). No per-role breakdown is owed by the client.
| Resource | Sales Rep | Sales Manager | R&D / Sample Owner | Administrator |
|---|---|---|---|---|
| Lead | C, R, U (own); triage-approve/convert/archive (own); reassign (own) — hand a lead they own, or that is shared with them, to a colleague | C, R, U, D (team); reassign | R (own — the leads shared with them¹) | C, R, U, D (all); Cfg triage rules |
| Account | C, R, U, archive (own); reassign (own) — hand an account they own, or that is shared with them, to a colleague | C, R, U, archive (team); reassign | R | C, R, U, archive (all) |
Contact (governed by account.view / account.manage) |
C, R, U, archive (own account) | C, R, U, archive (team) | R | C, R, U, archive (all) |
| Deal (Opportunity) | C, R, U (own); move stage (own) | C, R, U, D (team); move any in the team; reassign | R (own — the deals shared with them¹) | C, R, U, D (all) |
| Pipeline / Stage config (probability, rotting) | R | R | R | Cfg (create/edit pipelines, stages, probability, rotting) |
| Product Brief | C, R, U (own deal) | C, R, U (all) | R (all); comment | C, R, U, D (all) |
| Buying Standard (the sellable record — Rev 27) | R — an account’s standards with the final USD price only³; attach to own deal (qty/discount) | R (as Sales Rep³); attach (all) | R (as Sales Rep³) | R (all) — the whole book, costs and margins included (buying_standard.view); create/edit/archive is buying_standard.manage, recommended for the Tea Room (§Roles) |
| Sample | C (request), R (own deal), U (limited) | C, R, U (all) | R, U (all: prepare/dispatch/deliver/feedback/outcome) | C, R, U, D (all) |
| Quote | C, R, U (own); submit at/above the gross-profit floor; sub-floor routes to MD approval | C, R, U (all); oversight (sub-floor margin-override approval is the Managing Director’s, by recommended configuration) | R (own — the quotes shared with them¹) | C, R, U, D (all) |
| Activity (Task) / Calendar (a task follows its record’s key) | C, R, U (own); mark done | C, R, U, D (all); assign | C, R, U (own) | C, R, U, D (all) |
| Email / Message | Own mailbox: connect, read, send, drafts (email.manage); R the mail linked to records they reach |
Own mailbox (email.manage); R the mail linked to records they reach — never a colleague’s mailbox; bulk email to a saved contact list (email.bulk_send, Rev 103) |
R the mail linked to records they reach | Own mailbox (email.manage); R the mail linked to records they reach; Cfg AI switches; bulk email to a saved contact list (email.bulk_send, Rev 103) |
| Email Template | Use the shared templates and any own personal templates in the compose dialog (email.manage); create and edit none — since Rev 79 writing a template, personal ones included, needs settings.manage |
As Sales Rep | As Sales Rep | As Sales Rep; C, U, D the shared templates and their own personal templates (settings.manage, Rev 72; personal templates need email.manage beside it, Rev 79) |
| Sequence | C, R, U (own); enroll own deals/leads | C, R, U (all) | R | C, R, U, D (all); Cfg |
| Timeline / Communication | C, R (own account) | C, R (all) | R (on records they reach) | C, R, U, D (all) |
| Export-doc checklist | R, U (own deal: toggle assembled) | R, U (all) | R | R, U (all); Cfg doc rules |
| Certification-mismatch check | R (own deal) | R (all) | R | The certification list: Cfg; a standard’s held certifications: buying_standard.manage; an account’s required certifications: account.manage |
| AI outputs (summaries/drafts/scores) | R; A to send/apply (own) | R; A (all) | R; A (sample feedback drafts) | R; Cfg AI settings |
| Dashboard / Reports / Forecast | R (own + team) | R (all) | R (sample-scoped) | R (all) |
| Data import/export (CSV/Excel) | Export (what they can view; audited) | Export (what they can view; audited); import only with Cfg² | — | Import (Cfg); export (what they can view; audited); Cfg mappings |
| ERP handoff document | Generate (own Won deal) | Generate (all) | — | Generate (all); Cfg handoff template |
| File attachment (follows the parent record’s key) | C, R, U, D (own record’s files) | C, R, U, D (all) | R (on records they reach); add or change files where they hold the parent’s manage key (samples) |
C, R, U, D (all) |
| Saved view / list view | C, R, U, D, share (own); R (shared) | C, R, U, D, share (own); R (shared) | C, R, U, D, share (own); R (shared) | C, R, U, D, share (own); R (shared); D (a deactivated owner’s shared view) |
| Custom field definition | R (use) | R (use) | R (use) | C, R, U, archive and restore (never delete — Rev 88), Cfg |
| Reference data (certs, doc rules, dropdowns, activity types, tea grades) | R | R | R | C, R, U, D, Cfg — except the account dropdowns (customer type, region, packaging, Incoterms), fixed in code in V1 (OQ-65, Rev 36) |
| Users & roles | — (the minimal name-and-role directory only) | — (the minimal name-and-role directory only) | — (the minimal name-and-role directory only) | settings.manage (Rev 79; access.manage before): create, edit, deactivate and reactivate users (never delete); set each user’s role and manager; create, rename, edit and delete roles |
Cells the minimal catalog cannot express as first written (Rev 37, AD #34). The matrix was drawn for a model with separate actions per role; the catalog has only
viewandmanageper entity. The cells above are restated where the model can express them. Four distinctions follow; the first two are recommended-role advice (role contents are Empire’s configuration — OQ-53), and the last two are defaults awaiting the lead:
- ¹ R&D “linked” visibility. “Linked” is not a reach. The R&D cells now read
viewwithout the entity’sallkey, which for a taster with nobody below them means the records shared with them — a rep shares the deal behind a sample, for example. The alternative is to add the entity’sallkey (AD #37). Either is a setting Empire’s administrator chooses in the role editor, not a code change.- ² Import by Sales Managers. Imports need
settings.manage, which also covers all configuration, so a Sales Manager who may import may also configure. The advice is that a Sales Manager role does not holdsettings.manage; Empire’s administrator may decide otherwise. Export needs no extra key.- ³ Standards and prices. Reading the whole standards book, with costs, margins, the floor and the LKR build-up, needs
buying_standard.view; a role with onlyaccount.viewsees an account’s own standards with the final published USD price, on the account page. This split is the delivery team’s default, awaiting the lead’s confirmation.D(delete) given to one role and not to another on the same entity (Lead, Deal, Quote, Sample, Product Brief, Email Template, Sequence, File attachment, Timeline).<entity>.managecovers every action on the entity, so a Sales Rep and a Sales Manager who both hold it can differ only in reach (the reporting line, or the entity’sallkey — AD #37), not in whether they may delete. Accounts and contacts are archive-only (OQ-64, Rev 36). The default for the other business records — leads, deals, quotes, samples and product briefs — is the same: archive, not delete (proposed to Empire inclient/roles-and-permissions.md, footnote 7); sequences, file attachments and timeline entries are settled at their own feature’s spec. Notes are deleted by marking, not removed (F1-e, Rev 59): a deleted note is hidden everywhere and kept. Email templates are deleted the same way (F20-d, Rev 72): a deleted template leaves every list and is kept, and the weekly-prices template cannot be deleted. A personal template is its owner’s alone, and no key reaches another user’s. A hard delete anywhere is a lead decision at that spec, and a change request if Empire asks for one.
Governance invariant (all roles): AI never auto-acts. Every AI-drafted email/action (including sequence steps) requires a human Approve before it sends or saves; quote pricing follows the gross-profit-% floor — reps quote at or above it, and sub-floor quotes require Managing Director approval (OQ-40) — delivered as the quote.approve_sub_floor key, held by the Managing Director’s role in the recommended configuration (AD #34); compliance/export/quality decisions are human-owned. [research: ai-in-workflows.md §4; prototype AI principle]
⚠️ Sequencing correction (2026-08-06): the completion trigger below said “at spec time.” That is too late —
architecture.mdbuilds the(role, resource, permission-level)authorization model in Foundation slice 6, which runs before any feature spec. Designing that model against a matrix missing 2 of 6 roles is the expensive failure mode. The two missing columns must be completed before Foundation slice 6 starts. (Surfaced by the Gate 2 dry-run, 2026-08-06.) Now tracked with an owner as OQ-53 inproject-prd-signals.md, alongside the undefined permission-level semantics that the same slice depends on;tracker.yamlmarks slice FS-6 blocked by it.Matrix note (2026-08-03): the grid above shows the four original role columns. Three access facts confirmed on 2026-08-03 are folded into the role descriptions above and finalised as full columns before Foundation slice 6 (see the correction above): Tea Room (sets/publishes weekly prices, owns pricing config, otherwise read-oriented), Executive (read-only across dashboards/pipeline/quotes/reports), and the Managing Director margin-override approval for sub-floor quotes. Access is additionally scoped by the granular permission levels the client requested — read-only / edit / AI-use / execute (OQ-47).
Rev 21 note (2026-09-07, AD #30): the two notes above were written for a fixed
(role, resource, level)model. Under the configurable model the “missing columns” (OQ-53b) are the recommended Tea Room and Executive role contents (no templates since Rev 24 / AD #32), still an outstanding client input but no longer model-shape: the model is(role, permission_key, scope)over a code-declared catalog, and Foundation slice 6 builds the catalog and the grant store — not a fixed matrix. The Managing Director is a role Empire’s Administrator creates holding the one named permission (AD #26 unchanged; it was a seeded template from Rev 21 until Rev 24 / AD #32 removed templates).Rev 37 note (2026-09-24, AD #34): the three notes above predate the minimal catalog. The model is
(role, permission_key, scope)over a catalog ofview/managekeys per entity plus a short list of special keys (§Permission keys), with no category axis and no read-only / edit / AI-use / execute levels; the only seeded role is the editable IT Admin, and the Managing Director holds the special keyquote.approve_sub_floorby recommended configuration.Rev 43 note (2026-09-27, AD #37): the grant loses its scope. The model is
(role, permission_key): a key’s reach comes from the reporting line, and an entity’sallkey widens it to every record (§Multi-Tenancy / Org Hierarchy).
Multi-Tenancy / Org Hierarchy
Single-tenant, single-organization (Empire Teas). No multi-tenant SaaS partitioning. Access control is by role + record ownership + the reporting hierarchy + per-record sharing (Rev 21, Rev 29, Rev 37; AD #34, AD #35). Every user may name a manager (app_user.manager_id, a nullable self-reference), set by the holder of settings.manage. A key on an entity that has an owner reaches records by one fixed rule, with no scope to choose (Rev 43 / AD #37; from Rev 21 to Rev 42 each such key carried its own own / team / all scope, set per permission):
- By default — records whose owner, or any active user they are shared with, is the user or anyone below them in the reporting tree, through every level (recursive). For a user with nobody below them, that is the records they own or that are shared with them (what
ownmeant); for a manager it adds their whole team’s (whatteammeant). - With the entity’s
allkey (lead.all,account.all;deal.all,quote.allandsample.allin Phase 2) — every record, unowned records included, with no walk of the hierarchy. Theallkey widens whichever ofviewormanagethe role holds on that entity, and a role cannot hold it without one of them.
Whether a manager may edit their team’s records or only view them follows from the role’s key: manage edits what the user reaches, view reads it. Two things the earlier per-permission scope allowed are given up for a role editor with no scope to set (AD #37): a role cannot reach further with view than with manage on the same entity, and a user with people below them always reaches those people’s records. Setting a user’s manager is therefore an access decision — it lets the manager reach that user’s records wherever the manager’s role holds the entity’s key. No key reaches another person’s mailbox: email.manage covers the holder’s own mailbox only, a fixed rule rather than a setting, and the mail linked to a record follows that record’s reach. A user holds exactly one role (Rev 24 / AD #32), so there is no cross-role union to resolve.
Record sharing (Rev 29, revised Rev 37 / AD #35; Empire 2026-09-09). Each lead and account — and, when they land, each deal and quote — has one owner, and can be shared with named colleagues. It covers what the reporting line structurally cannot: peer-to-peer and cross-line access (a rep sharing with another region’s rep, or onto the Tea Room). The invariant is that a share widens reach, never authority: a share carries no access level of its own, and a user may act on a record only when their role holds the needed key and the record is in their reach — through the reporting line, the entity’s all key, or a share to them. Shares roll up the reporting tree: a manager reaches the records shared with anyone below them. Sharing is transitive — someone who reached a record through a share may share it on — and sharing, removing a share and reassigning the owner all need the entity’s manage key, so a view-only user can do none of them; anyone whose role holds the entity’s manage and who reaches the record, by any of those paths, may do all three — its owner or a colleague it was shared with, a manager above either of them, or a holder of the entity’s all key (Rev 46, lead confirmation 2026-09-30). The share picker offers only active users whose role holds the entity’s view key and who do not already reach the record; users who already reach it are not listed (existing shares appear in the record’s shared-with list, with Remove), and users whose role cannot see that entity are not listed either. Reassigning the owner needs a new owner who is active and holds the entity’s view key; existing shares survive, and the previous owner loses reach unless the record is shared back. Children follow their parent’s reach — contacts, notes, tasks, attachments, timeline and record-linked email follow their account or lead. Every share, share removal and reassignment is audited (AD #36) and displayed on the record (a per-user effective-permissions view cannot enumerate per-record shares). One visibility rule, covering the reporting line, the all key and shares, serves both the list queries and the single-record check, built once as a substrate (F5-f) before the lead, account and deal list read-paths.
Unowned records. Only a lead can lack an owner (its owner is nullable for import edge cases). An unowned record is visible only to holders of lead.all, and it cannot be shared (Rev 49), and F11 gives it an Unassigned filter, with no separate queue. Since Rev 44 no planned V1 path leaves a lead unowned — the import gives every lead to the import owner (§F4) — so the rule is a safeguard, and F11-b keeps the filter as one (lead, 2026-09-30; Rev 46). Deactivation and the hierarchy. A user who has direct reports cannot be deactivated until the reports have another manager, and a user who owns any record — a lead or account now, a deal, quote or sample in Phase 2 — cannot be deactivated until those records are reassigned (§F5). Deactivated users stay in the reporting tree, and shares to them stay, shown as deactivated and removable. A share to a deactivated user is inert (Rev 49): it gives reach to nobody — not the recipient, not their managers — and it counts again if the user is reactivated. Records shared with a user do not block their deactivation; only records they own do. (OQ-56 resolved, Rev 37.)
Distinct from the deferred granular visibility groups (arbitrary named groups — see Deferred), which stay out of V1. Decision records: AD #35, and .forge/design/data/record-sharing-model.md (written for Rev 29; AD #35 revises its sharing rules). client/roles-and-permissions.md §2 put the Rev 29 position to Empire and was re-revised to AD #35 in Rev 37; Empire was told of the change in the progress update of 6 October 2026 (client/weekly-updates/2026-10-06.md, items 3 and 4; engagement-log.md § 2026-10-08). A lightweight team/region tag (e.g. Sri Lanka / Kenya / Netherlands / Shanghai / Spain) may still group records for filtering and dashboards. Multi-office data partitioning (records walled off per office) remains deferred (see Deferred) pending discovery Tier-1 Q3 — the reporting hierarchy is an org chart, not an office wall. [research: initial-findings.md §2.2, discovery-questions.md Tier 1 Q3]
Functional Surface
One paragraph per feature (F1–F26, F31–F34 and F36; F16 and F31 are kept as dropped stubs — Revs 60 and 61), grounded in the prototype, R&D research, and Pipedrive documentation.
F1 — Accounts (Organizations + Contacts)
A 360° customer record. The list shows active customers with a “Dormant” badge, type, country, LTV, and last-contact age. The detail view carries: an AI account briefing (F13); a profile grid (customer type, region, required certifications, preferred packaging, Incoterms); contacts (name, role, email); a color-coded communication timeline (lead/order/sample/call/quote/note/email); linked open opportunities, private-label product briefs, samples, and quotes; and past orders sourced from the ERP (read-only, “via ERP”). Accounts are the hub every other domain entity attaches to. Accounts and contacts carry tags/labels for grouping and filtering (Pipedrive labels parity; asked for 2026-09-09 — Rev 23), which F32’s saved filters use. A contacts page lists every contact the user can reach, with a search, including contacts with no account (Pipedrive people with no organisation, and contacts synced later); a user opens and edits a contact and attaches it to an account (F1-f, Phase 1 — Rev 56). [prototype §2.4]
F2 — Pipeline / Deals
Kanban boards, one per pipeline, toggled by pipeline (Private Label / Bulk by default; pipelines are admin-configurable via F24). Deal cards show company, country · product, value + volume, certification chips, owner avatar, and an age-in-stage / rotting indicator that dots red (past the stage’s rotting threshold) / gold / green. Cards drag between stages (updates stage, resets the rotting clock, toasts confirmation). Clicking a card opens the Deal Detail drawer with metrics, buying-standard line items (F26), held certifications, sample-round history, the certification-mismatch check (F9), the export-documentation checklist (F10), the product brief (F8), and the ERP handoff (F19) once Won. Board headers show open value, weighted forecast (F24), and won-this-quarter. Deals are created with title/value/currency/owner/person/org/pipeline+stage/expected-close/label + custom fields, and can move between pipelines. [prototype §2.3, §2.8; Pipedrive doc research — deals]
F3 — Activities (tasks, follow-ups, reminders)
A grouped list of follow-ups and reminders across accounts, opportunities, and leads, bucketed Overdue / Today / Upcoming / Completed with filter pills. Activity types include call/meeting/task/deadline/email/lunch plus admin-defined custom types. Each row shows a type dot, title, type · record (account, deal or lead) · assignee, a due chip, and a Mark done action; overdue rows are highlighted. Activities also render on the calendar (F21). This is how the CRM stops follow-ups from being missed — the #1 stated Pipedrive pain. [prototype §2.7; research: discovery-questions.md Q22; Pipedrive doc research — activities]
F4 — Pipedrive Data Migration
A one-time migration importing leads, contacts (Pipedrive people) and organizations from Pipedrive into the new data model — deals and deal history are not migrated (Empire’s fresh-start election, 2026-09-13, recorded in §Scope > F4; corrected here at Rev 32), and Pipedrive notes, activities and custom fields are not migrated (lead decision, 2026-09-28 — Rev 44). The migration runs more than once: a first load before the parallel run, and a final run after the data freeze that adds what was created in Pipedrive in between and never overwrites a record already changed in the CRM. Because Pipedrive data quality is a stated risk, migration cleans while importing: dedupe, normalize (countries, buyer types, volume units, company-name variants), classify/route spam and dead leads (via F11 AI triage) to archive/nurture rather than importing blindly, and preserve original Pipedrive IDs and source attribution for audit. Migration approach confirmed (OQ-21): migrate every lead, organization and person, preserve original Pipedrive IDs, and let AI triage flag junk after import rather than dropping records beforehand. Record volumes, counted from the Pipedrive exports of 2026-09-28: 692 leads, 4,235 organizations and 4,977 people (OQ-6, resolved at Rev 44). Every imported lead and account is owned at first by one named Empire user — Kavindu Anthony in production — who reassigns them (lead decision, 2026-09-28); the Pipedrive owner’s name is kept on each record for that purpose. Rev 47 (lead decisions, 2026-09-30): both runs stay. The import owner of a run is the signed-in user who runs it unless the run names another, and their role holds lead.manage, account.manage, lead.all and account.all. They hand the records out with the bulk “change owner” action on the lead and account lists, which comes forward to Phase 1 for this (F32-c); a later run never takes a record back from its new owner. The kept Pipedrive owner name is never shown on a record or in an everyday list — only that hand-out filters by it. The parallel run begins on a date agreed with Empire once the migration is ready (late in Phase 1 at the earliest). Relied-upon reports and automations are asked of Empire directly, since no Pipedrive audit is coming (OQ-26). Uses the same import engine as F23. [research: initial-findings.md §5.4, ai-in-workflows.md §6, discovery-questions.md Tier 6]
F5 — Authentication, Users, Roles & Ownership
Per-user login with configurable role-based access (the six recommended roles per §Users — Sales Rep / Sales Manager / R&D-Sample Owner / Admin / Tea Room / Executive — plus the Managing Director role) and record ownership, sharing and reassignment. Underpins the capability matrix, the pricing-approval permission, mailbox/calendar connections, and the audit trail of who did/approved what (AD #36). Rev 37 (AD #34, AD #35) settles the mechanics that OQ-51 and OQ-56 held open.
Sign-in. Sign-in is via each user’s company Microsoft account only (AD #28, refining AD #5: Google and local email/password dropped 2026-09-04), so credential resets live in Empire’s Microsoft 365, not the CRM. After a successful Microsoft sign-in, the verified email must match exactly one active user, or sign-in is refused (AD #34). Users are pre-created: there is no auto-provisioning and no invitation email; Empire’s administrator creates the user and tells the person to sign in. The CRM does not synchronise users from Entra in V1: in-app deactivation is the offboarding control, and Empire disabling a person’s Entra account is the backstop (Microsoft then refuses the next sign-in, though a CRM session already open runs until it expires — deactivating in the CRM ends it at once).
User administration and configuration are one permission. The holder of settings.manage does all user, role and reporting-line administration, and nobody else does any of it (Rev 79: the separate access.manage key was folded into settings.manage on 2026-10-26, because Users and Roles are pages of the CRM’s Settings page and settings.manage opens every one of them): create and edit users; assign each user’s single role, mandatory from creation, and change it later; set each user’s manager; deactivate and reactivate users — never delete them; and create, rename, edit and delete roles. This is the surface proposal §9 commits to training on. Changing a user’s email clears their Microsoft identity link, so the next sign-in re-links by the new address. Deactivation refuses future sign-ins and ends the user’s open sessions at once, and releases their mailbox connection. It is refused, with the reason and the list, when the user is deactivating themselves; when it would leave no active holder of settings.manage; while the user has direct reports (give them another manager first); and while the user owns any record — lead, account, deal, quote or sample (reassign those records first — a record always has an active owner, Empire confirmed 2026-09-09, Rev 23). Reassignment is offered one record at a time and in bulk, for offboarding.
Roles are configured, never predefined (AD #34). A fresh installation ships with one Flyway-seeded, editable IT Admin role holding settings.manage and one active user holding it (the seed migration granted access.manage, and a later migration moved every grant of it to settings.manage — Rev 79). The user’s email is set per environment: the crm01@empire.lk test mailbox outside production, and in production the administrator address Empire confirms, supplied from Secrets Manager and never kept in git. There are no role templates, no superadmin, no non-deletable system role and no wildcard grant. Empire’s administrator creates the six recommended roles and the Managing Director role from the catalog (Altrium supervising at go-live). The role editor attaches keys from the catalog (§Permission keys), rendered grouped by the catalog’s UI-group metadata — per entity a choice of none, view or manage, plus the entity’s all key where it has one (AD #37), and a tick per special key; a role can be renamed (its key never changes), re-permissioned, and deleted only while no user, active or deactivated, holds it. Last-admin invariant: at least one active user always holds settings.manage, so a deactivation, role change, role edit or role delete that would leave none is refused. Self-escalation is unlimited — the administrator may grant any key to any role, their own included — and the audit trail (AD #36) is the control. Permission changes apply on each affected user’s next request, with no sign-out; the frontend re-reads the user’s permissions after a refused request and when the window regains focus.
Ownership and sharing (AD #35; rules in §Multi-Tenancy / Org Hierarchy). A record-share surface on lead and account detail (and deal and quote detail when those land): share the record with a colleague, see who it is shared with and by whom, and remove a share; the picker offers only eligible users. A shared-with-me marker and filter in the list views, without which a shared record is reachable only by direct navigation. A reassign-owner action. A minimal user directory — active users’ display names and role names — readable by every signed-in user, for the share, owner and manager pickers; the full user list stays behind settings.manage. An effective-permissions viewer, behind settings.manage, answers “why can this person see this?” by showing the user’s single role, the keys it holds and, per entity, whether they reach every record (the all key) or the records of the reporting line below them, naming the people it covers. Every change on this surface writes an audit event (AD #36). The Tea Room and Executive role contents are Empire’s configuration (OQ-53 closed as not required, Rev 37). [prototype: the Users & roles screens added 2026-09-07 illustrate the model as a team proposal (design/prototypes/README.md) — their template markers, two-role person and AI-assist chip are superseded by Rev 24, their per-permission reach control by Rev 43, and the share picker’s “No lead access” entries and “cannot pass it on further” text by Rev 37; research: discovery-questions.md Tier 1 Q3, Tier 6 Q43]
F6 — Sample Tracking (multi-round lifecycle)
The sample workflow no generic CRM models. Two views: a lifecycle board (7 columns: Requested → Blended/Prepared → Dispatched → Delivered → Feedback due → Feedback received → Outcome) and a management table that computes a plain-language “where it’s stuck” reason per sample (e.g. “Buyer feedback overdue 18d”, “In transit 10d — check courier”, “Awaiting R&D prep”). Samples are multi-round per deal (Round 1 rejected → Round 2, etc.), each round carrying owner (taster), due date, days-in-state, courier + tracking, and outcome. Overdue-feedback samples surface an AI “Draft feedback chase” (human-approved). Advancing a sample auto-fills courier/tracking on Dispatch and logs feedback state transitions. Typical rounds range from 1–2 when matching an existing client sample to 6–7 when developing a new standard, almost always closing before 10 (OQ-11 confirmed 2026-08-03). [prototype §2.5; research: sri-lanka-tea-industry.md §10 Steps 4–6, discovery-questions.md Q19, Q23]
F7 — Quotes with Readiness Checklist + Approval Gate
Quote records with aging (colored by age), status, margin, a payment-terms field (LC / Open Account / DA / CAD / advance, per customer — OQ-10 confirmed), line items drawn from the account’s buying standards (F26), and an 8-item readiness checklist: product spec, quantity, packaging, Incoterm, currency, destination, certifications, and margin & approval. The system computes the quote’s gross-profit % from the standard’s cost. The AI Quote Assistant (F14) flags each unmet item and relevant risk but never sets price. Submission is blocked until all checklist items pass; a quote at or above the required gross-profit % floor needs no special approval, while a sub-floor quote is blocked pending Managing Director approval (OQ-40 confirmed 2026-08-03) — approval needs quote.approve_sub_floor, which the recommended configuration gives to the Managing Director’s role only (AD #34). Quotes carry a revision history (v1/v2/v3 with notes). AI matching of similar past quotes is not built (F7-e, dropped in Rev 61). Quote expiry matters because auction prices fluctuate weekly. [prototype §2.6; research: sri-lanka-tea-industry.md §4, §10 Steps 9–10]
F8 — Product Briefs (private label)
A structured internal brief turning a buyer’s private-label request into R&D/packaging instructions: tea type, blend profile, origin requirement, packaging format, pack size, outer packaging, volume, target market, and required certifications. Missing values render as “Needs confirmation,” and blocking open questions must be resolved before the brief is “complete — ready for R&D and packaging handoff.” One brief per private-label deal. [prototype §2.8; research: sri-lanka-tea-industry.md §10 Step 3]
F9 — Certification Mismatch Check
On a deal, the CRM cross-references the buyer-required certifications (from the account) against the certifications the deal’s buying standards hold (F26 — the standard carries its held certifications; there is no separate catalog since Rev 27), and flags the gap (“Missing: EU Organic”) or confirms “All buyer-required certifications are present.” One of the highest-value features; custom because neither Zoho validation rules nor Odoo support multi-value cross-checks natively. [prototype §2.8; research: competitive-landscape.md §5.1 gap #3, sri-lanka-tea-industry.md §12]
F10 — Export Documentation Checklist
For a deal at/after the commercial stages, the CRM generates the required export-document set from a rules engine: base documents + destination-country documents + per-certification documents (e.g. Germany + EU Organic → Commercial Invoice, Packing List, B/L, Certificate of Origin, SLTB Export Authorisation, CUSDEC via ASYCUDA, Phytosanitary, EU Organic cert matched to batch/lot, pesticide-residue MRL report). Each item is a toggleable “assembled” checkbox. For pre-commercial (sample) stages, it explains the simplified “no commercial value” customs path. The CRM references the correct set; it does not file to SLTB/ASYCUDA. [prototype §2.8, §9; research: sri-lanka-tea-industry.md §8]
F11 — Lead Triage (AI scoring & drafted replies)
The inbound-inquiry queue and the answer to the 200+ unreviewed Pipedrive leads.
Every lead is researched before it is ranked (confirmed requirement, Rev 30; fallback Rev 83). Ranking a lead on inquiry text alone cannot answer the questions the priority actually turns on — whether the company imports tea at all, at what scale, into which market, and against which certifications — so an AI research pass precedes scoring on every lead: the system searches public sources for the company and synthesises a structured snapshot (industry, size, location, recent signals, certifications, origin/sourcing posture, import-export signals, and the role of the person named on the lead where those sources state it), each field carrying the source URL that grounds it. A second search, for the person — their name with their company — is made while the person-search switch on the CRM’s Settings page is on; an administrator turns it on or off, and it is on by default (Empire Teas’ answer of 10 November 2026; Rev 99; F11-i). With it off, the person’s name is not sent to the search service and their role is taken from the sources about the company. The score, the confidence and the “why this priority” are produced from that snapshot plus the inquiry, and the reason shown to the rep cites what it was based on. Nothing is invented: a field the search cannot ground is left empty rather than guessed, matching F12’s null-not-guess rule, and a lead whose research returns nothing is still scored — from the inquiry alone, at lower confidence. When the research cannot run — the search service is down, paused or switched off, or the lead has had no research for 24 hours since it entered the CRM or was last edited — the lead is ranked from the inquiry alone, at lower confidence, and ranked again once its research completes (Rev 83), so no lead is left unranked; the research still runs on every lead. A lead converted from the capture app arrives researched and ranked by the app, and the CRM does not research or rank it again at conversion (F36, Rev 101); a later ranking in the CRM follows the rules above and uses the campaign focus the lead was ranked with. Research never auto-actions a lead; it informs a ranking a human acts on. This is distinct from F29, dropped in Rev 66 — F29 was the purchase of firmographic records from a data provider, which is not built; this is the AI reading public sources, on the same seam the capture app (F36) uses. The provider behind that seam is an implementation choice recorded in design/ai/lead-research-source-options.md, not a PRD commitment.
Each lead is AI-scored P1–P3 with a confidence % (three levels — Rev 55), gets an AI summary of the inbound email, a “why this priority” reason, a recommended next action, and an editable AI-drafted follow-up in Empire Teas’ voice (pricing deliberately omitted — human-set). The draft is generated when a person asks for it — a button on any lead — and shown for review before anything is sent; nothing is drafted in advance, for new inquiries and the migrated backlog alike (Rev 56). Spam and duplicate detection tag/route junk and re-sends. Hot / cold is a second indicator, separate from the priority (Rev 55): it shows how recently the buyer engaged, so the team can find the cold leads and follow them up (F11-h). A lead is hot while the buyer’s last message — the inquiry that created the lead, or a later email from the buyer linked to it — is no more than 30 days old, and cold after that. Only the buyer’s own messages count: Empire’s emails and follow-ups do not keep a lead hot. The 30 days is a setting, changed without new work. The rule is a date check, not AI. Filters by priority, hot/cold, country, buyer type, lead source, and tags/labels (labels on leads — Pipedrive parity, asked for 2026-09-09, Rev 23), plus an Unassigned filter for leads with no owner, which only all-scope holders see; there is no separate unassigned queue (OQ-56, Rev 37). Every lead captures a first-class lead source (Website, Trade Fair, Referral, Email, Other) set on creation, feeding the F17 dashboard’s leads-by-source breakdown. Per-lead actions: Approve & send, Convert to opportunity, Archive/nurture — every action human-approved. The full 200+ backlog is triaged as a one-time recovery + migration-cleaning pass. [prototype §2.2; research: ai-in-workflows.md §8 UC1, UC7, initial-findings.md §7.1A] [confirmed 2026-07-16 meeting]
F12 — AI Inquiry Extraction from Email
Given inbound inquiry text (from the F20 email feed or pasted in), AI extracts structured fields — buyer/company, country, tea type/grade, volume (with units), packaging, certifications, Incoterm, destination port, timeline — returning null for anything not stated (never guessed) — and pre-fills a CRM lead/deal draft for human confirmation (~30s vs minutes of manual entry). V1 triggers on manual paste/forward-in; an automated inbound-email trigger and multilingual extraction are deferred pending channel/language confirmation. [research: ai-in-workflows.md §2 Technique 1, §8 UC2, discovery-questions.md Tier 4]
F13 — AI Account Briefing
A one-click pre-meeting brief on an account, made when a person whose role holds account.manage asks for it (AD #32): who they are, what happened last, what is still open, a suggested next move, and — when the account is dormant by F1-c’s rule — a re-engagement prompt. It is synthesised from the account’s profile and its communication timeline, so samples, quotes and other records reach it as their timeline entries do. It reads no order history in V1: no order data reaches the CRM (OQ-63, default (b); a typed-in last order would join it if Empire chooses option (a)). Nothing is stored or acted on; the person reads it and decides. Turns 15 minutes of CRM archaeology into a 2-minute read. [prototype §2.4; research: ai-in-workflows.md §8 UC3]
F14 — AI Quote Assistant
Embedded in F7: reads the quote record, flags every missing/incomplete input and relevant risk (e.g. “certification not confirmed for this market”). It does not surface comparable past quotes (F7-e, dropped in Rev 61). It prepares inputs only and never sets or approves price — a human calculates and approves pricing. [prototype §2.6; research: ai-in-workflows.md §8 UC5]
F15 — AI Dashboard (morning briefing, “what’s stuck”, ranked leads)
The dashboard’s AI surface: a narrative morning briefing synthesising the day’s top priorities across leads/opps/samples/quotes; a “what’s stuck — and why” plain-language read of blockers (each click-through to the relevant record with a severity dot); and an AI-ranked high-priority-leads shortlist with confidence. All are read-and-decide aids; the human actions them. [prototype §2.1]
F16 — AI Product-Brief Assistant (dropped, Rev 61)
Not built in V1 (lead decision, 2026-10-11). A rep fills the product brief (F8) by hand; F8-b’s open-questions gate still checks it for completion (§Out of Scope).
F17 — Dashboard & Operational KPIs
The landing page. KPI cards: avg inquiry response (target <12h), follow-ups due today (+overdue), samples overdue for feedback, quotes aging >7 days ($ at risk), dormant high-value accounts. A pipeline-by-stage funnel with Private Label / Bulk toggle and footer stats (open value, weighted forecast from F24 stage probability, won this quarter, in final negotiation). A leads-by-source breakdown (Website / Trade Fair / Referral / Email / Other, from F11’s first-class lead-source field) shows where the book of business is actually coming from. Ad-hoc reporting is served by filterable, exportable list views (F32/F23) rather than a separate report builder; relied-upon Pipedrive reports are confirmed via OQ-26. Gives management the pipeline visibility Pipedrive reports failed to earn trust for. [prototype §2.1; research: discovery-questions.md Q14, Q27] [leads-by-source confirmed 2026-07-16 meeting]
F18 — Stale/Aging Alerts & Dormant-Account Detection
Cross-cutting alerting built on F24’s rotting mechanism: per-stage rotting thresholds (a 14-day-silent deal means nothing in a 5-month private-label cycle but is urgent in a 3-week bulk cycle — thresholds differ per stage/pipeline), quote aging alerts, and dormant reorder-ready account detection (e.g. silent >90 days, high LTV). Feeds the dashboard “what’s stuck” and KPI cards. Thresholds are discovery-driven (Q20–Q21, Q26). [prototype §2.1; research: discovery-questions.md Q20, Q21, Q26]
F19 — CRM→ERP Handoff on Won
When a deal reaches Won, the CRM produces a structured handoff document (manual path) after a readiness checklist passes: quote approved & pricing confirmed, certifications verified (no mismatch), and — for private label — product brief complete. This is the CRM↔ERP boundary: CRM owns everything up to the confirmed order; the ERP owns the order onward. Automated API sync is deferred pending confirmation the new ERP exposes an API. [prototype §2.8; research: tea-export-domain-notes.md CRM-to-ERP boundary, discovery-questions.md Tier 5]
F20 — Email in the CRM (sync, send, templates, tracking)
Because reps work inside Pipedrive’s inbox today, the CRM must own email end-to-end. Two-way email sync connects each user’s Microsoft 365 mailbox (via Microsoft Graph) so incoming and outgoing mail auto-links to the matching contact, deal, and lead and appears on the account timeline. Only email linked to a record is stored in the CRM, in full with its attachments; the rest of the mailbox is read live from Microsoft and never copied (lead decision, 2026-10-17, after Empire asked why whole mailboxes would be synced): the in-CRM inbox shows the user’s folders a page at a time, an email is linked automatically by address or thread or by the user, a record created later and a mailbox connected later both get their past mail linked, users and the administrator can block addresses and domains, and the mailbox connects itself when the user signs in, a failed connection never stopping the sign-in (design/architecture.md § Mailbox integration; F20-i, F20-f, F20-j, F20-k). A contact may hold several email addresses, and mail to or from any of them links (Rev 77; the Pipedrive migration keeps every address — F20-l); a lead keeps one address, and a converted lead’s email is also linked to the account, contact and deal it becomes (F11-e). Each user’s own mailbox is connected, and only their own (email.manage, AD #34): no role can read another person’s mailbox, and the mail linked to a record is visible to whoever reaches that record. The shared inquiries address (info@) is handled by forwarding in V1 (OQ-52 and OQ-54 resolved, Rev 37): someone forwards an inquiry to a rep, the rep’s own synced mailbox brings it in, and the rep creates the lead — by hand or with F12 extraction. There is no shared inbox inside the CRM in V1 and no unowned mailbox connection (the shared inquiries inbox, F20-e, left V1 on 2026-09-24). If Empire wants, info@ can be added as an ordinary CRM user, which needs nothing built, provided info@ is a licensed mailbox that can sign in to Microsoft itself (not a sign-in-disabled Microsoft 365 shared mailbox); its actions are then attributed to info@, not to the person using it. One synced mailbox per user, private by default, is how Pipedrive works today, so reps keep the mental model they already have — mechanics in discovery/research/m365-mailbox-integration.md. Microsoft 365 is the only provider in V1 scope — it is what every Empire user is on (OQ-24) and it is what the issued proposal quoted. Gmail, Exchange-on-prem and raw IMAP are out of scope, additive only via change request; the MailboxProvider seam in architecture.md keeps that addition cheap without paying for it now. Reps compose, reply, and send from within a deal/contact and from an in-CRM inbox, with CC and BCC recipient fields on every compose/reply. Reps send four kinds of email — new, reply, reply-all and forward (a forward keeps the original’s attachments) — with formatted text (bold, italic, lists, links), and attach files to an outgoing email (F20-h, Phase 1). Two deliberate divergences from Pipedrive, confirmed by the lead (Rev 68): no signature is added — Microsoft Graph neither adds nor exposes the Outlook signature (OQ-68 asks Empire whether they want a CRM signature setting) — and one send goes to at most 50 recipients, so it is not a bulk send. Committed V1 email is one send at a time — every send is a single, human-triggered email, including the per-account send this week’s prices action that F26 adds. Bulk sending is F37 (Phase 2 — a stretch candidate from Rev 28, committed to Empire at Rev 57 on 2026-10-09; F37-a was built early and is accepted with Phase 1, Rev 100): the weekly price broadcast to every customer (F37-a) and one message to a saved contact list with a per-send summary (F37-b), both built on F20’s send path rather than changing it; no Phase 1 feature depends on it. Email templates (a starter set plus custom, team-shareable templates) support merge fields that auto-fill from deal/contact/org fields; open and link tracking and scheduled send are included (F20-g, Rev 89; built early and accepted with Phase 1, Rev 100): the rep chooses tracking for each email, on by default; a tracked email shows sent, then opened, then clicked, as estimates, with no delivered state, because Microsoft Graph reports no delivery for a single email (reading bounces is F37-b’s); the CRM keeps only that an open or click happened, when, and which link, never an IP address or device; and a rep can schedule an email up to 30 days ahead and cancel it from a Scheduled folder in the inbox. (This sentence previously also listed “group email” as included, contradicting the Rev 23 exclusion three sentences earlier — corrected at Rev 28.) AI drafting (Claude, tea-voice, pricing omitted, human-approved) is the same engine as F11/F12. Deliverability depends on the sending mailbox’s SPF/DKIM; unlike Pipedrive, our build can optionally send system/automation mail from a shared address. [source: Pipedrive doc research 2026-07-07 — email sync, templates, group email, AI email]
F21 — Activity Calendar & Calendar Sync
A calendar view of activities (day / week / list) with a left-rail filter of activity types and drag-to-reschedule; creating or scheduling an activity shows it in calendar context. Two-way calendar sync with Microsoft 365 (via Graph — the only provider in V1 scope, AD #16) means external meetings appear alongside CRM activities and edits flow both ways (future events only; recurring events managed in the source). Extends F3. [source: Pipedrive doc research — activity calendar, calendar sync]
F22 — Contact Sync
Reads each user’s contacts from their connected Microsoft 365 account (via Graph — the only provider in V1 scope, AD #16) every hour, one way into the CRM; nothing is written to Outlook. The Outlook contacts the CRM does not hold appear on the user’s own From Outlook list, with a suggested account where exactly one fits; the user adds the ones they want, choosing the account, or dismisses the rest, so personal address-book entries never enter the shared CRM unreviewed. When an Outlook contact matches exactly one CRM contact the user can reach, the sync fills only that contact’s empty fields and adds new email addresses as other addresses; it never overwrites a value. Matching uses every email address (F20-l), so the same outside person held by two users is not added twice when the two copies share an email address; a person held under different addresses can still become two contacts. Each user can turn the suggestions off in their mailbox settings. Write-back to Outlook is not in V1; Empire can ask for it at UAT. Spec: .forge/specs/F22-contact-sync-spec.md. [source: Pipedrive doc research — contact sync; the lead’s decisions of 2026-11-20, Rev 107]
F23 — Data Import & Export (CSV/Excel)
An ongoing spreadsheet import tool (beyond the one-time F4 Pipedrive migration): upload XLS/XLSX/CSV of leads, contacts, organizations, deals, buying standards, or activities; auto-map columns to the fields that exist (custom fields are created beforehand under F34; creating them during mapping was dropped in Rev 63); one row links the person + org + deal it contains; resolve duplicates by merge-or-create at finish. Plus CSV/Excel export of any filtered list view. Enables trade-fair lead lists, bulk updates, and data portability. An import needs settings.manage; an export contains only the records the user can view, and every export writes an audit event (Rev 37; AD #34, AD #36). Rev 84: the export is built first on the account, lead and contact lists (F23-d, started early in Phase 1), and the deal, quote, sample and buying-standard lists join it in Phase 2 (F23-a). [source: Pipedrive doc research — spreadsheet import/export]
F24 — Configurable Pipelines (stages, probability, rotting)
Admins can create and edit pipelines: name the pipeline, add/reorder/rename stages, set each stage’s win probability (0–100%) — which drives the weighted forecast on the dashboard (a $10k deal in a 40% stage contributes $4k of expected value) — and set each stage’s rotting threshold (the number of idle days after which a deal is flagged red; the clock resets on any activity/note/email/edit). The system ships seeded with the two tea pipelines (Private Label 10-stage, Bulk 4-stage) as editable defaults. This is the configuration surface behind F2 (boards), F17 (weighted forecast) and F18 (stale/rotting alerts). Because AI features and automations key off stage semantics, stage edits are validated against the domain workflow. [decision 2026-07-07; source: Pipedrive doc research — pipelines, stage probability, rotting]
F25 — Outreach Sequences
A sequence is a multi-step cadence of email steps and follow-up task steps, enrolled on a deal or lead, that nurtures a prospect over time. Reps build sequences from templates or from scratch; AI (Claude) generates each step’s email with a chosen tone and length in Empire Teas’ voice, and — per the governance invariant — a human approves before anything sends. Sequences drive re-engagement of the 200+ triaged leads (F11) and dormant accounts (F18). Enrollment can be manual or triggered by a lead/deal condition. [source: Pipedrive doc research — sequences; research: ai-in-workflows.md §8 UC7]
F26 — Buying Standards & Weekly Pricing (Deal Line Items)
There is no separate products catalog (Rev 27, 2026-09-15). The sellable record — for bulk and private label alike — is the client-specific Buying Standard: a unique, never-reused running number on one account, carrying tea grade, origin/region, brand (Thurson / Hyson / Akina / Ceylon Wild Harvest — Empire’s own-branded goods sell through this pipeline, OQ-20) and the certifications the standard holds, plus its cost and price history. Standards are created, edited and archived by holders of buying_standard.manage (recommended: the Tea Room); archiving keeps the price history and removes the standard from quoting and from the weekly round, and a number is never reused, so create always mints a fresh one. Standards attach to a deal as line items with quantity and discount, rolling up into deal value. The standards book is the single source of truth for the F9 certification-mismatch check and F7 quote line items — the quote picker offers that account’s standards. No separate price-lookup page is built (F26-e, dropped in Rev 61): holders of buying_standard.view find a standard by number or client, with its final published USD price, in the Standards book on the Pricing page (F26-b), and the Tea Room sees the full build-up in its weekly round (F26-f); a user with only account.view sees an account’s standards with the final USD price on the account page (AD #34). Each standard’s published prices, newest first, are shown under History in the Tea Room’s weekly round (F26-f FR-22), and every past price is kept in the effective-dated price rows (AD #14). [replaces the Pipedrive products model — team decision recorded in prototype PR #88]
Bulk pricing (confirmed 2026-08-03): the priced unit is a client-specific Buying Standard — a grade/blend spec a client buys (e.g. BOP1, POSOS), identified by a unique running number never reused across clients; a client typically buys 4–5 standards, each carrying its own weekly price (OQ-42). One price per standard per week — the price does not vary by customer or destination market (decided 2026-09-11 after the 2026-09-09 meeting and Empire’s weekly price workbook; Rev 23, revising the Rev 6 answer to OQ-38 — destination market stays a customer attribute and a quote field, never a price key) — and it is not volume-tiered — order size moves the per-kg price only nominally (OQ-45). A published price holds until the next weekly Colombo auction, with a manual override for exceptions — a single clock shared with the quote (OQ-33). The Tea Room team sets and publishes the weekly prices (OQ-39) — in the model, publishing needs price.publish, which the recommended configuration gives to the Tea Room role (AD #34). A published price whose week starts today or later can be withdrawn (Rev 62; AD #14’s second exception, lead sign-off 2026-10-11; built by F26-f): the row is marked withdrawn with who, when and why, so a corrected price can be published for that week; its figures and validity never change, it is never deleted, and no earlier price is reopened; the standards book retains price history and a per-standard cost used to compute gross profit at quote time (OQ-40). The published price is FOB Colombo in USD, with CIF/other currencies handled per-quote via the cost build-up (OQ-44, OQ-43). A weekly price is recorded as a four-figure build-up, not a single number (Rev 31, 2026-09-17 — team decision, Tharinda; refining OQ-43’s “USD base” answer): the price is set in LKR, an overhead is added in LKR, the total is converted to USD at an exchange rate, and a margin is added to reach the final USD price the customer is given. All four are stored on the price row — price_lkr, price_lkr_with_overhead, price_usd_pre_margin, and the final USD figure — and only the final USD price is required: the three working figures are recorded when the Tea Room has them and left empty when a price is set directly. USD remains the currency the customer is quoted in and the only currency a price is published in, so OQ-43’s “currency is not a price-key axis” stands; what changes is that the rupee working behind that figure is now kept rather than discarded, which is what makes a past week’s price reconstructable. The exchange rate and the overhead are kept per price row, not per week (Rev 53 — team decision, Tharinda, 2026-10-06): the LKR-per-USD rate the conversion used is stored on the price row beside the four figures, recorded when the Tea Room has it, so a week’s figures can be checked against each other; the overhead is the difference between the two LKR figures already on the row. A per-price rate holds whether Empire uses one rate a week or several — the workbook already carries different rates on different tabs in one week. The unit of the LKR figures (taken as LKR per kg until the Tea Room confirms) and who produces the sheet remain OQ-59. Private-label items are standards too (Rev 27, revising OQ-37’s bulk-only answer) — whether they join the weekly round or stay priced per quote is OQ-61. A tea-auction public API is confirmed available (integrated with the current ERP, IFS); pulling auction reference prices into the weekly-pricing workflow is a scoped follow-on — V1 keeps human weekly entry, and auction data would only ever suggest a reference to a human, never auto-set a price. The weekly price list arrives as an Excel workbook by email (one tab per market, one row per standard — CLIENT · STD · TYPE · GRADE — and one column per auction week; ~1,450 standards priced in a current week out of ~35,000 numbers ever issued — workbook seen 2026-09-11). V1 takes that workbook in as draft prices for the Tea Room to review and publish, through an upload that accepts the workbook as it is today — no fixed template is required of the Tea Room — and reports every row or cell it cannot read instead of guessing; it flags a standard number that appears twice in one week instead of silently taking one row (Rev 53). Standards are a searchable list, never a dropdown. A rep sends a customer their standards and this week’s published prices from the account page — a per-account, human-triggered send this week’s prices action through the rep’s own mailbox (F20); sending this week’s prices to every customer at once is F37-a, Phase 2 (Rev 57). The data model is forge-et-be/docs/data-model.md §2 (SP-ARCH-003, DDL-verified) — revised for Rev 23 (no market price axis), Rev 27 (no product) and Rev 31 (the four-figure build-up), owner Tharinda (AD #31); the research doc bulk-tea-pricing.md is superseded input.
F31 — Global Search (dropped, Rev 60)
Not built in V1 (lead decision, 2026-10-11). There is no search across all records. Each list screen carries its own search over the records the user reaches — accounts (F1-b), leads (F11-b), users (F5-c) and every later list (F32) — and a user looking for a record goes to that list (§Out of Scope).
F32 — List/Table Views, Saved Filters & Bulk Actions
Every core entity gets a sortable, column-configurable list/table view in addition to its board/detail views. Users can save filtered views (personal or shared) and run bulk actions on a selection — edit a field, reassign owner, add an activity, enrol in a sequence (F25), archive, or export to CSV/Excel (with F23). This is how reps and managers slice the book of business the way Pipedrive list views allow, and it (with the F17 dashboard) is the reporting surface in place of a separate report builder. Rev 47: the “reassign owner” bulk action on the lead and account lists arrives in Phase 1 (F32-c), because the Pipedrive import owner hands the imported records out with it; every other bulk action, and reassigning deals, stays in Phase 2 (F32-b). Rev 84: the list views and saved filters are built first on the account, lead and contact lists (F32-d, started early in Phase 1), with the contact views F37-b sends to; the deal, quote, sample and buying-standard lists join them in Phase 2 (F32-a). Rev 100: F32-d was done on 2026-11-13 and is accepted with Phase 1. [source: Pipedrive doc research — list views/filters]
F33 — File Attachments
Attach files to any core record — deals, accounts, contacts, quotes, samples, and product briefs. Central for private label, where artwork, packaging mock-ups, buyer POs, spec sheets, and certification PDFs must live with the deal rather than scattered across email. Files are listed on the record with uploader, date, and size; uploads are validated (type/size), and while virus scanning is switched off (from 2026-10-09, Rev 58 — §Non-Functional › File uploads) each upload is recorded as not scanned; access is scoped to the record’s visibility. Rev 84: attachments are built first on accounts, contacts and leads (F33-a, started early in Phase 1) — leads are core records too — and deals, quotes, samples and product briefs join them in Phase 2 (F33-b). Rev 92: F33-a is done, and attachments on accounts, contacts and leads are accepted with Phase 1. [source: Pipedrive doc research — files]
F34 — Admin Custom Fields
Administrators can define custom fields per entity (account, contact, deal, lead, quote, buying standard, sample) — text, number, date, single/multi-select, and similar types — on top of the typed tea-domain schema. This lets the team add new fields later without a code change; Pipedrive custom fields are not migrated (Rev 44). Custom fields appear on forms, list views (F32), filters, and import mapping (F23), and are admin-audited as schema changes. Rev 84: custom fields are built first on accounts, contacts and leads (F34-c, started early in Phase 1), and deals, quotes, buying standards and samples join them in Phase 2 (F34-a). Rev 88: the field types are text, number, date, single select and multi select — a further type is an additive change — and a field is archived and restored, never deleted, so the values records hold are kept (F34-c spec). Rev 90: custom fields on accounts, contacts and leads (F34-c) are Phase 1 scope and accepted with Phase 1 (client/phase-1-acceptance-criteria.md Section K); deals, quotes, buying standards and samples (F34-a) and list columns and filters (F34-b) stay in Phase 2. [decision 2026-07-07; source: Pipedrive doc research — custom fields]
F36 — Trade-Show Lead Capture App (companion PWA)
A standalone installable PWA in its own repository (forge-et-pwa), hosted at its own URL (AD #20/#22), so reps capture leads on the exhibition floor without opening the CRM: photograph a business card or scan a badge QR, one at a time (Rev 95: the POC’s Scan a pile and choosing several photos at once are not built), and send the capture with Submit for Research — a capture whose upload fails on poor venue Wi-Fi is kept on the phone, shown as not sent, and sent again when the app is open with a connection; there is no background sync or full offline mode (Rev 64, §Out of Scope) — an AI vision call reads the card into structured fields, and a research/scoring pass on the same AIProvider seam (human-reviewed, per the standing HITL rule) ranks the lead — the capture app shows that ranking as a tier, Hot (P1), Warm (P2) or Cold (P3), with a fit score from 0 to 100; the tier is a fit ranking, separate from the CRM’s hot / cold engagement status (F11, Rev 55: how recently the buyer wrote) (Rev 98) — and the app tells the rep in an in-app notification — a notifications bell and an on-screen notice while the app is open; the capture app sends no email and uses no WhatsApp vendor (AD #42, Rev 94: the notification email via SES planned until 2026-11-12 is not built). When a person converts a captured lead, its ranking goes into the CRM as the lead’s priority — Hot as P1, Warm as P2, Cold as P3 — with its confidence, reason and next action, and the CRM does not research or rank the lead again at conversion; the fit score stays in the capture app, and the converted lead shows the CRM’s own engagement status (Rev 101). Nothing reaches the CRM unreviewed (Rev 95, decided by the delivery team on 2026-11-12 and accepted by the lead the same day): a captured lead waits in the app, with its card reading and research, until a person reviews it and either converts it, which creates the CRM lead through the F11 intake as a first-class inbound lead with lead-source tracking (F11/F17), owned by the person who converted it, with the rep who captured it kept as captured by (AD #35’s one owner), or rejects it, with an optional reason from a set list and an optional note; a rejected lead stays in the capture app only and can be moved back to review. Using the app needs its own permission, capture.use (Use the capture app), which gives full use of the app, except that converting a captured lead also needs lead.manage, because it creates a CRM lead owned by the person converting (Rev 96); it is a special key like price.publish, ships held by no role (AD #30) and is listed in FS-6 Appendix A — no finer capture-app permission is drawn. Scope is full — Option C, decided 2026-08-18: capture + AI card read + research/scoring + notifications (in-app since Rev 94); the reduced capture-and-feed shape (capture, the review in the app and the intake — the review stays in it, Rev 96) is retained as a descope lever at the capture-app checkpoint, which the Statement of Work of 2026-09-29 holds during Phase 2, now proposed for Fri 2026-11-20, to be confirmed with Empire. The build ports from the working prototype published read-only as the sibling forge-et-pwa-poc repo and runs as a parallel work-stream delivered in Phase 1 since 2026-11-11 (Rev 91; Gate 3 had placed it alongside the Phase 2 work; client/project-timeline.md §2). Organizer-provided bulk attendee lists remain a F23 import + F11 triage path — this feature is the per-lead floor capture, and the plan of which exhibitors’ stands to visit (below). Confirmed and added on 2026-09-09 (Rev 23): badge QR scanning is needed (what the QR encodes is still unknown — a badge photo is requested); an existing-client check during the scan — the app tells the rep at once whether the organisation or person is already a customer and how often Empire deals with them, which needs a read lookup against accounts and contacts from the app and a graceful “check pending” state when offline; the same-day generic follow-up email to people met at the stand is not built (dropped in Rev 63, which closes OQ-60 — §Out of Scope); ranking the existing backlog of stuck leads is F11’s batch scoring. Campaign planning is already present in the POC and is not a new ask. Planning before a show is in Phase 1 (Rev 96, the lead’s decision of 2026-11-12, reported by Nanndish; until then OQ-55’s working position kept the POC’s pre-show exhibitor targeting out of V1): in the app’s Plan tab a rep sets up a campaign for a show, with its first and last day, loads the show’s exhibitor list (a CSV or Excel file read without AI, each column matched by its heading and checked by the rep) or adds exhibitors by hand, edits and archives them, and on the day writes visit notes and marks each stand visited; the AI researches and ranks every exhibitor on the list (score and reason), human-reviewed as any AI output is. The screens and data are built in F36-a and the research and ranking in F36-c, as later waves of each; F36-c’s spec states how the exhibitor research runs, its expected time and its running cost, which client/sow-cost-annexe.md does not yet carry as its own line. The added work is recorded against R-ARCH-001 and narrows the descope lever. A campaign can carry an optional focus (Rev 101, the lead’s decision of 2026-11-18, reported by Dinil): a short note on what the show’s leads should be ranked for, such as Private-label buyers in the EU. With no focus, the standard ranking rules apply; a focus adds to them and never replaces them, and it is passed to the AI as data, not as instructions. It applies to the campaign’s exhibitors and to the leads captured under it, and it can raise or lower the tier, and so the P1–P3 priority a converted lead takes. A ranking made with a focus says so wherever it is explained: the AI’s reason mentions the focus where it made a difference, a fixed line shows the focus text and the campaign’s name, lead lists in the app and the CRM mark such a lead with the same text on hover, tap or keyboard focus, and the CRM’s lead list filters on it. The focus text is kept with the ranking, so a later ranking of the lead in the CRM (F11) uses the same focus. Editing a campaign’s focus ranks its exhibitors and the captured leads still to be reviewed again (the ranking only; the research is not run again); leads already converted keep theirs. The POC’s campaign “lens” (OQ-55), which F36 had left out, is the idea this takes up. Built in F36-c (a wave after its second), with the campaign form’s field in F36-a’s screens and F11-g’s ranking reading the kept focus. [proposal §4; AD #19/#20/#22; architecture.md § Trade-Show Capture App; OQ-55]
User Journeys
Journey A — Lead triage to opportunity (F11, F12, F20, F1/F2):
Inbound inquiry (email synced via F20 / trade fair / website) arrives
→ AI extracts structured fields (F12) + scores priority P1–P3 with confidence, summarises, tags spam/duplicate (F11); a rep asks for a drafted reply on the lead (F11-h)
→ Lead lands in the triage queue, ranked; Sales Rep filters (priority/country/buyer type) and opens the top lead
→ Rep reviews AI summary + "why this priority" + recommended action; edits the drafted follow-up (pricing omitted)
→ Rep chooses: Approve & send | Convert to opportunity | Archive/nurture (or enrol in a sequence, F25)
→ On Convert: a Deal is created on the correct pipeline (Private Label / Bulk) linked to a new/matched Account + Contact
Journey B — Private-label deal, inquiry → Won → ERP handoff (F2, F8, F26, F6, F9, F7, F19):
Deal enters "New inquiry" (Private Label pipeline)
→ Qualified buyer → Brief captured: Product Brief (F8) filled; blocking open questions resolved
→ Sample requested → dispatched → feedback (F6): multi-round sample lifecycle; overdue feedback triggers AI chase (human-approved); round rejected → new round
→ Artwork approval → Certification-mismatch check (F9) confirms the deal's buying standards (F26) hold all buyer-required certs
→ Quote submitted (F7): line items from the account's buying standards; 8-item readiness checklist must pass; AI quote assistant flags gaps; quote meets the required gross-profit floor (sub-floor needs Managing Director approval); quote submitted
→ Negotiation (quote revisions v1→v2→v3); rotting/probability tracked per stage (F24)
→ Won: ERP handoff readiness checklist passes → handoff document generated for manual ERP entry (F19)
Journey C — Quote readiness & approval (F7, F14, F26):
Rep opens a Draft quote; adds line items from the account's buying standards (F26)
→ AI Quote Assistant (F14) flags missing inputs (e.g. margin not set, cert not confirmed)
→ Rep completes the 8 checklist items (product, quantity, packaging, Incoterm, currency, destination, certifications, margin)
→ Submit stays disabled until 8/8 pass AND the quote meets the required gross-profit floor (sub-floor quotes need Managing Director approval)
→ On approval → status "Submitted"; revision logged; quote aging clock starts (expiry matters — auction price drift)
Journey D — Pipedrive migration & backlog recovery (F4, F23, F11):
Export Pipedrive data (leads, people, organizations — Rev 44) → import via the F4 engine (which F23 later exposes)
→ Clean, dedupe, normalize while importing; every lead, organization and person migrates, keeping its original Pipedrive ID (OQ-21)
→ AI triage (F11) then classifies the imported leads P1–P3 / spam / duplicate with reasons; a rep asks for a drafted re-engagement on any of them (F11-h), and F25 sequences work the backlog in Phase 2; spam/dead → archive/nurture
→ Human review queue: reps confirm/override classifications
→ After the data freeze, a final run brings across what Pipedrive gained during the parallel run (Rev 44)
Journey E — Email + follow-up inside the CRM (F20, F3, F21):
Rep opens a deal → composes a reply in-CRM using a template with merge fields (F20), or clicks "AI draft" (Claude, tea-voice) → reviews/edits → sends (tracked)
→ Reply syncs back to the linked deal/contact timeline automatically (two-way sync)
→ Rep schedules a follow-up Activity (F3) that appears on the calendar (F21); or enrols the deal in a sequence (F25)
Integration Points
| System | Direction | Purpose |
|---|---|---|
| ERP — current (IFS) + new (TBD, ~2027) | CRM → ERP (manual handoff document in V1; automated IFS integration a priced follow-on); ERP → CRM (order/shipment/invoice status, read-only — deferred) | Hand off Won deals; surface past orders on accounts. V1 (per AD #10): manual handoff on the ErpHandoffService seam. Automated integration is a separately-priced follow-on, waiting since 2026-11-12 (Rev 92) on Empire naming the ERP that replaces IFS and giving its details (OQ-2). [discovery-questions.md Tier 5] |
| Tea-auction system (public API; integrated with IFS) | Auction → CRM (reference prices — follow-on) | A public API is confirmed available (2026-08-03) to retrieve auction data. V1 weekly pricing stays manual; pulling auction reference prices in to assist the human pricer is a scoped follow-on (never auto-sets a price). |
| Pipedrive | Pipedrive → CRM (one-time) | Migrate leads/contacts/orgs (F4); notes, activities and custom fields are not migrated (Rev 44). Deals are not migrated — a fresh start in the CRM, with Pipedrive staying the record for them (2026-09-13). |
Microsoft 365 via Microsoft Graph — the only mailbox provider in V1 scope (OQ-24 confirmed; the sole provider quoted in the issued proposal). Gmail / Exchange-on-prem / raw IMAP are out of scope, additive only via change request behind the MailboxProvider seam. |
Two-way (contacts: one way, into the CRM — Rev 107) | Email sync (F20), calendar sync (F21), contact sync (F22, read from Outlook into a per-user review list) — the mailbox/calendar/contacts backbone reps use today. |
| Amazon Bedrock (Claude) | CRM backend → Bedrock, in-account (us-east-1) |
All AI features (F11–F15, F20/F25 drafting, F36) — extraction, classification, summarisation, drafting, checks. Claude served via Bedrock inside the project’s AWS account (AD #19); Haiku for high-volume/simple, Sonnet for complex; on outage the circuit breaker degrades to the manual path. The only non-Bedrock call path anywhere is the one-time provider comparison on Altrium-held evaluation keys against anonymised inquiries. [research: ai-in-workflows.md §3, §7] |
Inbound email (individual rep inboxes — confirmed OQ-14; info@empire.lk inquiries reach the CRM only when forwarded into a rep’s synced mailbox in V1 — OQ-52, Rev 37) |
Email → CRM | Source of inquiries for F12 extraction; F20 sync provides the feed. Automated trigger deferred. [discovery-questions.md Tier 4 Q29] |
| Courier services (DHL / FedEx / Aramex) | Manual entry V1 (API deferred) | Sample dispatch courier + tracking number (F6). |
| LinkedIn (third-party — not native to Pipedrive) | Not built (dropped, Rev 66) | Import LinkedIn leads/contacts, sync messages (F30). |
| Web-search provider (for AI research) | CRM backend → search provider, behind a SearchProvider seam |
The research pass that lead ranking is based on (F11; a lead is ranked from the inquiry first when research cannot run, Rev 83) and the capture app’s research/scoring (F36): public-source lookup whose results the AI synthesises into a grounded snapshot. One search per lead for the company; a second, for the person, while the person-search switch on the Settings page is on (on by default — F11-i, Rev 99). Not a firmographics purchase — see the row below. Provider selection and its data-governance basis are recorded in design/ai/lead-research-source-options.md (Exa, chosen by Empire Teas on 10 November 2026 and still on its free credit — SP-ARCH-004 closed). |
| Data-enrichment provider (third-party) | Not built (dropped, Rev 66) | Org/person enrichment (F29) — buying firmographic records per company from a data vendor. Distinct from the web-search row above, which is in V1: that is the AI reading public sources, not a purchased dataset. Do not collapse the two — dropping F29 does not restrict F11/F36 research. |
| Document storage (Google Drive / SharePoint — TBD) | Storage → CRM (deferred) | Source corpus for the deferred RAG knowledge/compliance assistant. [discovery-questions.md Tier 4 Q33] |
| SLTB / ASYCUDA / Customs | Reference only (no integration) | The export-doc checklist (F10) references the required set; submission stays with the export team. Out of scope. |
Non-Functional Requirements
Performance
- Scale: small team — order of magnitude 10–20 concurrent users across offices (exact count is discovery Tier-6 Q43); data volume in the thousands of accounts/deals/leads (Pipedrive migration volume counted at Rev 44 — see §Functional Surface › F4; F23 import caps ~50k rows/file). [research: competitive-landscape.md §5.1, discovery-questions.md Q6, Q43]
- Responsiveness: interactive CRM screens (lists, boards, detail views, calendar) load in < 2 s under normal data volumes; Kanban drag-and-drop, filters, and calendar interactions feel instant (< 200 ms UI response).
- AI latency: synchronous AI calls (extraction, summary, brief, quote flags, email/sequence drafts) return in < ~10 s; long/batch operations (200-lead triage) run as background jobs with a review queue, not blocking the UI. The F11 research pass is background work, not a synchronous call (Rev 30): a search round-trip plus synthesis plus scoring does not fit the <10 s budget, so a lead arrives, is persisted immediately, and is researched and ranked asynchronously — the queue shows it as pending-research and the rep is never held waiting. The 200-lead backlog runs as the same job in batch. AI runs with human review — never in a hard user wait for correctness. [research: ai-in-workflows.md §4]
- Email/sync throughput: email send respects provider rate limits (order of ~40 actions/min/account, per Pipedrive’s documented ceiling); sync and imports run as background jobs — except the Pipedrive migration’s runs, which answer in the request (§ Migration, Rev 70). [source: Pipedrive doc research]
- Migration: the Pipedrive import — a first load, then a final run after the data freeze (Rev 44) — writes as one batch with validation and a re-runnable/rollback-safe path; the dry-run preview that writes nothing may answer in the request (F4-a), and so may the write runs, each in one transaction, while they fit the load balancer’s idle timeout — validation is the dry run and the digest the write run must send back, and the single transaction is the rollback-safe path (F4-d, Rev 70). A write run that no longer fits becomes a background job. [research: discovery-questions.md Q6]
Security and Compliance
- AuthN/AuthZ: per-user Microsoft sign-in (AD #28), accepted only when the verified email matches exactly one active, pre-created user (AD #34); authorization by the grant model — the role’s key, reaching down the reporting line or, with the entity’s
allkey, every record, plus per-record shares, applied through one visibility rule for list queries and single-record checks (AD #34, AD #35, AD #37); quote pricing gated by the required gross-profit-% floor, with sub-floor approval needingquote.approve_sub_floor. The Managing Director-only approval and the Administrator-only configuration are the recommended configuration, not code rules: nothing in code stops the holder ofsettings.managegranting any key to any role, and every grant is audited (AD #36). - Data classification: buyer contact data (PII, incl. EU persons → data-protection care), commercial pricing/margins, and quote/deal data are confidential; access is role-scoped and audited. Email content synced into the CRM inherits this classification.
- Email & mailbox security: OAuth to user mailboxes/calendars/contacts; sending deliverability depends on correct SPF/DKIM on the sending domain; a user reads and sends from their own mailbox only, no role reads another person’s mailbox, and record-linked mail is scoped by the record’s visibility (AD #34). Automation/system mail may send from a shared address (an improvement over Pipedrive’s per-mailbox-only model), with its own authenticated domain.
- AI data handling (cloud AI accepted 2026-07-28; arrangements signed off with the accepted proposal, 2026-08-16; where requests are processed reopened as OQ-15, 2026-09-30 — Rev 48, and settled 2026-11-04 — Rev 82; Haiku 4.5’s background work on the Global route, Rev 82): AI features send buyer inquiry/communication text (incl. synced email) to Claude via Amazon Bedrock, called from inside the project’s AWS account (AD #19), which keeps buyer content within AWS, every call made from that account. Where each request is processed depends on the Bedrock route each call uses: Haiku 4.5’s lead triage and lead research (and later lead ranking, and the summary of a migrated lead from its linked email — F11-j, Rev 106) on its Global route where the environment’s task definition sets it (
.forge/cloud-gated-validation.md§D), by the lead’s direction of 2026-11-02, so that this background work has a request quota of its own; every other Haiku 4.5 call, including those a person waits for, on its US-only route; and Sonnet 5.5, for now, only on the Global route. A Global route may process a request in any commercial AWS Region (ai-provider-strategy.md§4b). Processing outside the project’s Region and outside the US is accepted (OQ-15, resolved by the lead on 2026-11-04, Rev 82). Every call is made from Empire’s own AWS account, and data between Regions stays on the AWS network, encrypted in transit. The model providers have no access to prompts or answers, and neither AWS nor the providers use them for training. All of this holds whichever route a call uses (AWS Bedrock documentation, read 2026-11-04). A US-only route stays a configuration change if Empire ever asks for one. Bedrock authenticates by IAM role, so no AI API key exists in the deployment; the only AI keys anywhere are the Altrium-held evaluation keys for the one-time provider comparison (anonymised inquiries, secrets-managed on Altrium’s side). The data-handling arrangements are those stated in the accepted proposal (Appendix A.6) — no separate approval document or gate (Rev 12); theAIProviderseam is retained as an architectural safeguard. No PII beyond what’s needed is sent. [research: ai-in-workflows.md §9 Q4, discovery-questions.md Tier 4 Q32] - Governance (human-in-the-loop): AI never autonomously sets/approves price, approves compliance, clears export, or auto-sends to buyers/ERP — including sequence steps and drafted emails. Every AI action is a reviewable draft approved by a human. [research: ai-in-workflows.md §4]
- Marketing consent (F37-b, Phase 2, started early in Phase 1 — Rev 102): a bulk send of one message to many contacts requires unsubscribe handling and anti-spam compliance (e.g. CAN-SPAM / GDPR e-privacy) before it goes out. The delivery team decided the model on 2026-11-19 (Rev 103, resolving OQ-62; Empire confirms it at the Phase 1 hand-over): Empire’s contacts are business contacts, so every contact on a saved list receives a bulk email unless they have unsubscribed, with no opt-in tick; every bulk email carries Empire’s postal address and an unsubscribe link that needs no sign-in and opens a page with one Unsubscribe button, and an unsubscribed or bounced address is left out of every later bulk send until someone who can edit the contact clears it at the contact’s request, which is audited. If Empire needs opt-in consent for some contacts (for example recipients in the EU), that is a change made at UAT. F37-a, which sends each existing customer their own prices, is a per-account business email and does not need it.
- Third-party data: purchased enrichment and LinkedIn data (F29, F30) are not built (Rev 66). Either would carry provider licensing and privacy obligations to review first if it were ever proposed again.
- File uploads & schema extensibility: file attachments (F33) are type/size-validated, stored access-scoped to the record’s visibility. Virus scanning (GuardDuty Malware Protection, behind the FS-11 seam) is built but switched off in every environment from 2026-10-09 (Rev 58: Altrium management’s decision, until it is needed or Empire asks), by the deliberate, acknowledged deploy setting F38-j added (Rev 50): each upload is recorded as not scanned (never as clean), the switch is logged, audited and counted, and the client-facing PRD states it (Rev 67: not raised with Empire separately); admin custom fields (F34) extend the schema — changes are admin-audited and never widen data exposure across visibility scopes.
- Regulatory posture: the CRM is a B2B sales tool, not itself an export-compliance system of record; export/SLTB compliance stays operational. Certification/export-doc data must be accurate and current (drives F9/F10 correctness).
- Secrets & config: API keys, ERP/mailbox credentials, and DB credentials are never committed; managed via environment/secret store.
Accessibility
- Supported sizes (lead decision, 2026-09-27; design-system § Viewport and breakpoints, § The capture app): the CRM on desktop and tablet (768px floor), and every CRM page reflows at 320 CSS px — WCAG 2.1 SC 1.4.10, which a 1280px desktop at 400% zoom needs — without being a phone design; the capture app on phone first, and on tablet and desktop too, in both orientations. Both are tested in Chromium and WebKit (Safari on iPhone and iPad) by the accessibility and responsive browser checks, at every size and in both engines, every night on
mainin the nightly full run on the lead’s Mac, not in CI (Rev 45, Rev 81; delivered as F40;.forge/test-strategy.md § Browsers & Viewports). A failure found there is fixed before new work starts. A pull request intomaindoes not run them in full; since Rev 93 a frontend pull request intomainruns the ones its change selects before it is marked ready (.forge/design/harness/fewer-nightly-reds.mdR-1). A pull request intorelease/*, which the nightly run does not test, runs them in full on the developer’s machine before it is marked ready (Rev 81;.forge/design/harness/test-run-cost.mdS-4, N-3). - Responsive web app usable on desktop and tablet; target WCAG 2.1 AA for core screens (keyboard navigation of lists/boards/forms/calendar, sufficient color contrast — the warm-palette design must meet contrast, and status must not rely on color alone; age/priority/severity/rotting dots carry text labels too). No formal assistive-tech commitment beyond AA is claimed for V1; confirm with client if stricter.
- Light theme only in V1. Both frontends — the CRM and the F36 capture PWA — ship the single light (Empire) theme. Dark mode is out of scope for all of V1 (neither Phase 1 nor Phase 2) and would be a future-release item only on client request; the design token layer keeps it cheap to add later. [design-system §9;
.forge/test-strategy.md§Deliberately Not Tested]
Observability and Audit
- Audit trail (Rev 37, AD #36; built as F39): one
audit_eventtable and one service record every write and every security event, in the same transaction as the change, so a change and its audit row commit or roll back together. Each event records who (a user, orSYSTEMfor background jobs), what, which record, when, and the change. Writes include every create, update, archive and state change on a record — moving deal stages, configuring pipelines, approving quote pricing, publishing prices, sending and enrolling emails and sequences, and approving or sending AI-generated actions among them. Security events are sign-in success and refusal, sign-out, deactivation and reactivation, role and permission changes, sharing, share removal and owner reassignment, and exports. Reads are not recorded. The trail is kept indefinitely in V1, with no audit-viewer screen in V1 — it is queried in the database. Every table also carriescreated_at/modified_at, andcreated_by/modified_bywhere a person makes the change. - AI provenance: every AI output is tagged as AI-generated in the UI with its confidence and source; AI drafts vs human-edited state is tracked (“edited by you”).
- Application & email monitoring: error logging; email send/sync + AI-call success/failure, latency, and token-cost tracking (expected AI spend ≈ $25–30/month at assumed volumes, budget $50 with a $150 billing alert — per
proposal § A.3.2, verified 2026-08-18; the June research’s ~$7/yr figure is obsolete); open/click tracking on sent mail; basic uptime/health monitoring. [research: ai-in-workflows.md §7; source: Pipedrive doc research — email tracking]
Constraints
Tech Stack
- Custom build is mandatory (decision, not open): a purpose-built application, not a configured Pipedrive/Zoho/Odoo/HubSpot/Salesforce instance — the differentiating features require equivalent custom development on any SaaS at the same effort but without ownership. Zoho/Odoo/iRely remain feature benchmarks, not implementation targets. [research: competitive-landscape.md §5.1, §5]
- AI provider: Anthropic Claude via Amazon Bedrock, in the project’s AWS account (
us-east-1— AD #19), called from the backend with no third-party automation-platform middleware — Haiku for high-volume/simple tasks, Sonnet for complex synthesis. No direct-API or alternate-vendor path in production; outages degrade to the manual path. Human-in-the-loop is mandatory. - Web-first responsive application (native mobile deferred).
- Email/calendar/contact connectivity: must integrate Microsoft 365 (email + calendar + contacts, via Microsoft Graph) — a hard requirement since reps work in-inbox today. Microsoft 365 is the only provider in V1 scope (OQ-24; the sole provider quoted in the issued proposal); other providers are change-request territory behind the
MailboxProviderseam. - Preferred (not mandated): a relational database (e.g. Postgres/Supabase) for the structured domain model. [research: competitive-landscape.md §3.6]
- Settled at Gate 2 / architecture (the locked set lives in
CLAUDE.md § Architecture Decisions): backend Java 21 + Spring Boot, frontend TypeScript + React SPA on Vite (AD #21 — no SSR; both frontends statically hosted on S3 + CloudFront, AD #22), hosting AWS, Microsoft-only OAuth2 sign-in with server-side sessions (AD #5 as refined by AD #28), Microsoft Graph mailbox integration (AD #16), SQS job/queue infrastructure, AI via Amazon Bedrock (AD #19), and the capture app in its own repository (AD #20). The harness bootstraps separate backend/frontend repos; the full record is.forge/design/architecture.md.
Regulatory
- No heavy regulatory regime governs the CRM itself (it is not the export-compliance system of record). Data protection applies to buyer contacts (EU persons among them) — handle PII with care and role-scoped access; email sync brings buyer communications in-scope for data protection.
- Sri Lanka tea-export regulation (SLTB authorisation, CUSDEC/ASYCUDA, ISO 3720, Lion Logo) is referenced by F10 but enforced operationally, not by the CRM. Direct customs/SLTB integration is out of scope. [research: sri-lanka-tea-industry.md §8]
- Anti-spam/marketing-consent regulation applies to the bulk send to a saved list, F37-b (see Security). The email-campaign product, F28, is not built (Rev 66).
Deployment and Hosting
- Cloud-hosted web application reachable by users across offices, able to reach Bedrock in-account and the Microsoft Graph endpoints. Provider is AWS (Gate 2, AD #4), region US East (
us-east-1) (AD-O-9 — revised 2026-08-18 on cost; confirmed againstus-west-2on 2026-10-01; buyer data is stored inside the project’s AWS account — Empire Teas’ own since 2026-09-29, SOW ET-002 superseded and never signed (design/environments-and-identity.md§3) — regardless of region, the static frontends serve from CloudFront edge, and the ~200ms API round-trip from Sri Lanka is the accepted trade-off). The AI-data-privacy question that once kept a self-hosted branch alive was accepted on 2026-07-28 (OQ-15); its processing-location half was reopened on 2026-09-30 (Rev 48) and settled on 2026-11-04 (Rev 82): any commercial AWS Region. Standard CI/CD, environment separation across two permanent environments — development and production, with development build-only: each client UAT round runs in a temporary environment stood up for the window, or in pre-go-live production with test data cleared afterwards (two-environment basis corrected 2026-08-06 against the costed proposalA.1/A.2.1; a separate staging environment is an unpurchased +$45/mo add-on, andproposal § 11contradicts this by promising three at handover — see OQ-49), and secret management expected. [research: ai-in-workflows.md §9 Q4]
Input Sources
| Source | Date / Version | Used For |
|---|---|---|
Client-approved prototype — .forge/design/prototypes/crm/crm-prototype.dc.html |
2026-07-03 | Authoritative feature set for the tea-domain modules, screens, entities, fields, pipeline/sample/quote lifecycles, AI touchpoints, domain enums. (Full inventory: prototype analysis, 2026-07-06.) |
| Pipedrive official documentation — support.pipedrive.com KB + pipedrive.com feature/newsroom pages | Research 2026-07-07 | The Pipedrive-parity features (F20–F30) and §Reference-System Classification: email sync/templates/tracking, calendar sync, contact sync, spreadsheet import/export, sequences, products catalog, configurable pipelines (stage probability, rotting), chatbot/live chat (LeadBooster), campaigns, data enrichment, LinkedIn (third-party). |
initial-findings.md (R&D discovery) |
2026-06-17 (upd. 2026-06-30) | Business profile, Pipedrive baseline & limitations, opportunity framing, AI use-case shortlist, risks. |
sri-lanka-tea-industry.md (R&D) |
2026-06-30 | Grades, regions, markets, certifications, Incoterms, export process/docs, private-label 16-step workflow, CRM-driving discovery questions. |
tea-export-domain-notes.md (R&D) |
2026-06-17 | Domain workflow, CRM-vs-ERP boundary, AI do/don’t boundaries. |
pipedrive-crm-notes.md (R&D) |
2026-06-17 | Reference-system capability list. |
competitive-landscape.md (R&D) |
2026-06-17 (+ July 2026 deep-research §5.1) | Build-vs-configure decision (custom build), competitor benchmarks, the five gaps closing the custom case. |
ai-in-workflows.md (R&D) |
2026-06-30 | AI techniques, HITL patterns, 7 designed use cases, cost model, AI open questions. |
discovery-questions.md (R&D, consolidated) |
2026-06-30 | 47 tiered open questions → §Open Questions (signals file) and Deferred triggers. |
| empireteas.com; Sri Lanka Tea Board (srilankateaboard.lk); Pipedrive product/API docs; Wikipedia (tea production, grading, Incoterms) | 2026-06 research | Cited domain and reference-system facts throughout. |
Risks
| # | Item | Owner | Status |
|---|---|---|---|
| R-01 | ERP integration scope — RESOLVED for V1 (Rev 5). V1 ships the manual handoff document on the ErpHandoffService seam (per AD #10); no automated integration is in V1 scope, so there is no V1 API dependency. Automated integration is a separately-priced follow-on; if commissioned and the APIs prove unavailable, the handoff stays manual. Empire is replacing IFS with an ERP not yet chosen (2026-11-12, Rev 92), so the follow-on waits until Empire names it and gives its details. |
Lead | accepted |
| R-02 | AI hosting / data-privacy — ACCEPTED (2026-07-28); residual closed 2026-08-19 (Rev 12). No on-prem or self-hosted LLM: AI runs on secure, reputable cloud infrastructure (Anthropic Claude via Amazon Bedrock, in-account — AD #19). The data-handling arrangements are those in the accepted proposal (Appendix A.6, signed off with its commercial acceptance 2026-08-16) — no separate contract-stage approval gate. The AIProvider seam is retained as an architectural safeguard. Where requests are processed was reopened on 2026-09-30 (OQ-15, Rev 48) and settled on 2026-11-04 (Rev 82): processing in any commercial AWS Region is accepted, every call made from Empire’s own account. |
Lead | accepted |
| R-03 | Prototype assumptions unvalidated — grade lists, volume units, pipeline stage names, sample-round counts, stale thresholds are our design, not client-confirmed. Mitigation: validate in discovery before locking the data model. | Lead | open |
| R-04 | Pipedrive data quality & migration scope — record volume, critical custom fields, cleanliness unknown; a large/messy instance raises migration effort. Mitigation: the import cleans and de-duplicates while importing, keeps every record’s Pipedrive ID, and AI triage flags junk after import (OQ-21); the volumes were counted from the exports (§F4, OQ-6), and custom fields, notes and activities are not migrated (Rev 44). | Lead | open |
| R-05 | AI hallucination — LLMs can invent fields/values. Mitigation: “return null, never guess” prompting, structured-output validation, human-in-the-loop approval on every AI action. | Lead | open |
| R-06 | Sales-team adoption — if reps distrust AI or resist data entry, the HITL model and CRM discipline break down. Mitigation: AI as optional assist; training; automation that reduces work. | Lead | open |
| R-07 | Scope creep into a mini-ERP — pressure to add inventory/production/finance would violate the CRM/ERP boundary. Mitigation: explicit Out-of-Scope contract; ERP stays the transaction backbone. | Lead | open |
| R-08 | Own-brand scope — RESOLVED (Rev 4). Empire’s own-branded goods (Thurson/Hyson/Akina/CWH) are sold through this pipeline (confirmed 2026-07-22, OQ-20), so Product and Deal carry a brand attribute. No longer an open risk. |
Lead | closed |
| R-09 | ERP migration contention — the client’s parallel ERP migration may absorb attention/IT capacity; the CRM must stay lightweight and complementary. Mitigation: phase delivery; keep V1 core lean. | Lead | open |
| R-10 | Multilingual inquiries — Arabic/Turkish/Russian inbound would degrade English-tuned AI extraction silently. Mitigation: V1 targets English; multilingual deferred pending language-mix confirmation and per-language testing. | Lead | open |
| R-11 | Multiple external channels for comms (email + WhatsApp + spread rep inboxes) — AI context and inquiry capture are incomplete if communications aren’t centralized. Mitigation: F20 email sync centralizes mail; WhatsApp integration is out of V1 (decided 2026-09-11, §Out of Scope) — non-email conversations are captured manually as notes and activities. | Lead | open |
| R-12 | Email-in-CRM scope & deliverability — reduced 2026-08-06 (Rev 7): the multi-provider half of this risk is gone — V1 scope is Microsoft 365 via Graph only, so SP-ARCH-002 stands down. What remains: two-way sync + templates + tracking is still substantial; deliverability is tied to per-mailbox SPF/DKIM and provider rate limits; and Graph push subscriptions expire within seven days (Microsoft’s documented ceiling is 10,080 minutes for Outlook message subscriptions; pinned in code as MailboxSubscriptions.MAXIMUM_EXPIRY — this row said “~3 days” until Rev 34 corrected it), so a lapsed subscription stops sync silently. Mitigation: F20 stays P0; scheduled subscription renewal plus a lapsed-subscription alarm; shared authenticated sender for automation mail. |
Lead | open (reduced) |
| R-13 | Pipedrive add-on reliance unknown, and F27–F30/F35 are not built (out of V1 since 2026-08-20; dropped, with no later phase planned, in Rev 66). The scope risk of over-building is closed; what remains is an expectation risk against the “nothing lost on migration” promise — if Empire actively relies on one of these today (Campaigns is the likeliest), the CRM will not replace it. Mitigation: ask Empire early (OQ-23/OQ-29), and if reliance is found, raise it with the client at that point as a change request rather than at UAT. | Lead | open |
| R-14 | Configurable pipelines vs domain-AI coupling — fully admin-editable stages can drift from the stage names the AI/automations key off, breaking triage/alerts silently. Mitigation: seed the two tea pipelines as defaults, validate stage edits against workflow semantics, keep a stable stage-type mapping under the display name. | Lead | open |
| R-15 | Marketing-compliance surface (F37-b) — one message sent to many contacts brings consent/opt-in, unsubscribe, and anti-spam obligations that don’t exist for 1:1 sales email. F37-b carries them (Rev 57): committed to Phase 2, and started early in Phase 1 since 2026-11-19 (Rev 102). Mitigation: the delivery team decided OQ-62 in F37-b’s spec on 2026-11-19 (Rev 103) — an unsubscribe link in every bulk email, unsubscribed and bounced addresses left out of later sends, the sender’s own mailbox — and Empire is asked to confirm it at the Phase 1 hand-over (owed.md); a change Empire asks for (opt-in consent, a shared sending address) is made as ordinary work; F28, the campaign product, is not built (Rev 66). |
Lead | open |
| R-16 | Extensibility surface (custom fields + attachments) — admin custom fields (F34) and file attachments (F33) add schema-migration and storage/security surface (upload validation/scanning, storage cost, field sprawl). Mitigation: constrain custom-field types, validate/cap uploads, with scanning off in every environment from 2026-10-09 by an acknowledged setting that records uploads as not scanned (F38-j, Rev 50; Rev 58) and available again without a code change, treat schema changes as audited admin actions. | Lead | open |
| R-17 | Bulk-pricing model — RESOLVED (Rev 4 core, Rev 6 remainder). All pricing dimensions are now confirmed: price validity (single clock, manual override — OQ-33), ownership (Tea Room team — OQ-39), source (online auction system + public API — OQ-46), currency (published in USD — OQ-43, refined by Rev 31: the figure is derived from an LKR build-up which is stored with it), Incoterm basis (FOB Colombo, CIF per-quote — OQ-44), the client-specific Buying Standard price key (OQ-42), destination-market differentials (OQ-38), and no volume tiers (OQ-45) — all settled in the 2026-08-03 meeting. | Lead | closed |
Success Criteria
Functional acceptance:
- No capability lost vs Pipedrive — every P-0x item classified Replicate/Redesign is live and the team can run their day without Pipedrive (Pipedrive decommissioned), including email in the CRM (F20): reps send/receive/reply and manage templates inside the new system. [user directive; §Reference-System Classification]
- Pipelines are admin-configurable with stage probability (weighted forecast) and rotting (F24), seeded with the two tea pipelines; both boards operate with drag-drop stage changes and per-stage stale alerts.
- The tea-domain workflows work end-to-end: multi-round sample lifecycle, quote readiness gate with human pricing approval and buying-standard line items, product briefs, certification-mismatch flagging (from the standards’ held certifications), and destination+cert export-doc checklists.
- AI features run under human-in-the-loop: lead triage/scoring, inquiry extraction, account briefings, quote assistant, dashboard briefings, and email/sequence drafting — all human-approved, AI never prices.
- Pipedrive data (incl. the 200+ lead backlog) is migrated clean, deduped, and triaged; the F23 import/export and calendar/contact sync are working; a Won deal produces a valid ERP handoff document.
- The everyday Pipedrive-parity gaps are closed: filterable list views, each with its own search, with bulk actions + export (F32/F23), file attachments on records (F33), and admin-configurable custom fields (F34) are live.
Business outcomes (targets to validate/baseline with client):
- Faster inquiry response — avg response time trends toward the < 12 h target. [prototype KPI]
- Fewer missed follow-ups — overdue follow-ups fall; the 200+ stale-lead backlog is cleared (100% classified). [research: initial-findings.md §8, ai-in-workflows.md §8 UC1]
- Sample & quote visibility — no sample “stuck without feedback” beyond threshold goes unseen; quotes aging past threshold are surfaced with $-at-risk.
- Dormant-account recovery — silent high-value accounts are detected and re-engaged (via sequences).
- Reduced manual data entry — AI extraction + contact sync cut inquiry-to-CRM entry from minutes to ~30 s per record.
- Management trust in the pipeline — leadership relies on the dashboard + weighted forecast for pipeline visibility (a stated Pipedrive gap). [research: discovery-questions.md Q27]
Adoption: the sales team uses the CRM as the daily system of record — including sending email from within it; AI review queues are actually worked rather than ignored.
Sidecar Files
This PRD is the live contract — the frozen-at-Gate-1 statement of what we are building. Two sidecar files carry the content classes that change post-Gate-1 or are pure bookkeeping:
| File | Contents | Lifecycle |
|---|---|---|
project-prd-signals.md |
Live signals — open and partial open questions, anchored to PRD sections and (optionally) to features that they block. | Authored as questions surface (interview, gates, mid-engagement). Resolved by folding the answer into this PRD body and moving the row to project-prd-history.md. |
project-prd-history.md |
Audit trail — resolved open questions and PRD revisions. | Append-only. |
The OQ resolution procedure and shape-enforcement rules live in .claude/rules/prd.md (path-scoped — loads when any project-prd*.md file is read or edited).