Sales Agent MVP — Architecture & User Workflow

01 / System Architecture

Hub = Agent Brain · ERP = Source of Record + UI

Twendee ERP already owns lead/deal/company data and UI. Hub does not duplicate — it provides agent capabilities (skills, workflows, memory) exposed via API and embeddable chat widget.

FIG 01 · SYSTEM CONTEXT

— Integration topology

graph LR subgraph ERP["Twendee ERP · System of Record"] direction TB E1[Lead / Deal / Company UI] E2["Extended fields:
icpScore · classification
enrichmentData (JSONB)"] E3[Approval workflow] E4[("ERP Database")] E1 --> E4 E2 --> E4 E3 --> E4 end subgraph HUB["AgentsHub · Agent Brain"] direction TB H1[Agent Registry
dynamic config] H2[Skill Registry
9 skills at MVP] H3[Workflow Runner
sync + async] H4[Memory
vector + convo] H5[Admin UI
/agents /workflows /chat] end REP((BD Rep)) LLM[/"LLM Provider
OpenAI · Anthropic"/] SRC[External lead sources
LinkedIn · web] REP -->|"day-to-day work"| E1 REP -->|"chat widget embed"| H5 REP -.->|"deep-link SSO · JWT"| H5 SRC -->|"webhook"| H2 E1 <-.->|"API · insights, proposal"| H2 H2 -.->|"push: score, classification"| E2 H3 --> H2 H2 --> LLM H4 --> H2 classDef erp fill:#162438,stroke:#4a90d9,stroke-width:1px,color:#c8d8e8 classDef hub fill:#1a2b42,stroke:#d4a73a,stroke-width:1px,color:#c8d8e8 classDef ext fill:#111d2e,stroke:#607080,stroke-width:1px,color:#c8d8e8,stroke-dasharray: 3 3 class E1,E2,E3,E4 erp class H1,H2,H3,H4,H5 hub class LLM,SRC,REP ext

Rep chạm vào đâu — 4 bề mặt

Rep BD chỉ thấy ERP quen thuộc + 1 widget chat nhỏ. Còn lại là hạ tầng agent chạy ngầm.

① ERP Twendee

Rep làm việc như cũ. Chỉ thêm ICP Score + Hot/Warm/Cold trên lead/deal + panel Enrichment — đều hiển thị như field native.

② Widget Chat (nhúng trong ERP)

Nút Generate Proposal mở side-panel. Dùng để tạo draft, hỏi nhanh về deal. Scope chỉ trong 1 deal, không rò rỉ dữ liệu.

③ Agent chạy ngầm — rep không động tay

Webhook → enrich → score → ghi ngược ERP. Xong trước khi rep mở lead. Chỉ ping Telegram khi Hot (< 60 giây).

④ SSO Deep-link

ERP gửi JWT ngắn hạn cho widget qua postMessage, whitelist origin. Rep không login lần hai. Đóng deal page → JWT biến mất.

Design boundary Hub stores no lead/deal rows. Skills read/write via IERPAdapter. Sales-specific code lives in agents/sales — never imports Twendee-specific types (lint-enforced). Adding HR Agent = new skills only, zero platform changes.

02 / Platform vs Vertical

What's shared, what's Sales-specific

Kỷ luật ranh giới: mọi primitive dùng được cho agent vertical khác phải ở platform layer. HR/Accountant next chỉ cần viết skills mới.

Platform · shared across all agents

Platform Primitives

Agent registry + config exists
Skill registry new
Workflow runner (sync + async) new
Approval adapter new
Memory service (conversations + embeddings) exists
Integration adapter interface exists
Event bus + subscribers exists
Observability (tokens, SLA, runs) new

Sales Vertical · first concrete instance

Sales Skills & Assets

sales.lead-enricher exists
sales.icp-scorer new
sales.pre-call-briefer new
sales.post-call-extractor new
sales.proposal-generator new
Sales prompts (system + few-shots) new
Workflow seed templates (YAML) new
Finance-agent cross-check contract new

03 / User Workflow

How a BD rep uses Sales Agent — day in the life

Agent runs autonomously in background (lead gen → qualify → brief). Rep takes over once lead is Hot, with full context pre-loaded. At negotiation, rep triggers proposal — agent drafts, rep reviews, ERP approves.

FIG 02 · SEQUENCE

— 8-step lead-to-proposal flow

sequenceDiagram autonumber participant SRC as External source participant AGENT as Sales Agent participant ERP as Twendee ERP participant REP as BD Rep participant LLM as LLM SRC->>AGENT: webhook: new lead card AGENT->>LLM: enrich (infer fields + confidence) AGENT->>ERP: write lead + enrichment AGENT->>AGENT: ICP score (deterministic, LLM for borderline) AGENT->>ERP: update icpScore + classification Note over AGENT: classification == "hot" AGENT->>REP: Telegram notify ("Hot lead: Acme, score 87") REP->>ERP: open Lead → sees brief + insights REP->>REP: schedule call with customer AGENT->>REP: pre-call brief (30min before meeting) Note over REP,REP: Discovery call happens REP->>AGENT: upload transcript AGENT->>LLM: extract pain + stakeholders + timeline AGENT->>ERP: update deal with structured signals REP->>ERP: click "Generate Proposal" ERP->>AGENT: POST /skills/proposal-generator/run AGENT->>AGENT: cross-check with Finance agent AGENT->>REP: draft proposal ready (<3 min) REP->>REP: review + edit + send to customer

Một ngày làm việc — timeline 9 mốc

Chuỗi 15 tin nhắn ở sơ đồ trên tương đương ~48 giờ thực tế. Đọc nhanh theo timeline bên dưới để thấy rep và agent phối hợp như thế nào.

08:00 Agent Lead mới tới (rep chưa dậy)

Webhook từ LinkedIn / web form → sales.lead-enricher gọi LLM điền các field thiếu + confidence score. Field độ tin thấp được flag, không tự commit. Ghi ngược vào ERP.
08:02 Agent ICP scoring + phân loại

Chạy scorer xác định (rẻ, nhanh, không token) trước. Chỉ khi kết quả 20–80 mới gọi LLM. Ghi icpScore + hot/warm/cold vào ERP.
08:03 Agent → Rep Ping Telegram khi Hot

"🔥 Hot lead: Acme Corp, ICP 87. Tech stack khớp gói enterprise." Tối đa 60 giây. Warm chờ trong queue; cold chỉ log.
09:30 Rep Mở lead trong ERP

Tap link Telegram → ERP lead page. Thấy score, classification, enrichment panel. Không UI mới để học. Rep đặt lịch discovery call 10:30.
10:00 Agent → Rep Pre-call brief (30 phút trước call)

Brief 1 trang: snapshot công ty, tin tức gần đây, pain points, câu hỏi đề xuất, stakeholders. Gửi qua Telegram + note trong ERP.
10:30 Rep Thực hiện call — agent im lặng

Agent không chen ngang, không transcribe live. Cố ý — rep là con người, agent lo chuẩn bị + giấy tờ.
11:15 Rep → Agent Trích xuất sau call

Rep paste transcript vào widget. post-call-extractor rút: pains, stakeholders, timeline, objections — kèm source span để audit. Deal record được cập nhật.
D2 14:00 Rep → Agent Tạo proposal

Click Generate Proposal → SSE stream hiển thị live: fetching-deal → computing-margin → generating-summary → rendering-pdf → writing-draft → complete. Margin kiểm tra sàn 30%, LLM viết exec summary, draft lưu dưới dạng comment có tag. < 3 phút.
D2 14:03 Rep Review → edit → gửi

Rep chỉnh summary, sửa line item, bấm Save. Nếu discount vượt quyền → thẻ approval pop-up trên Telegram của manager (1-tap Approve/Reject). Ngược lại, rep tải PDF và gửi khách. Con người luôn là người bấm "gửi".

STEP 01 — 02

Autonomous ingest

Webhook brings new lead into Hub. Enricher fills missing fields via LLM with confidence scores.

Agent · no rep

STEP 03 — 04

Score & notify

ICP scorer classifies Hot/Warm/Cold. Only Hot pings rep via Telegram within 60 seconds.

Agent · no rep

STEP 05 — 06

Pre-call context

Rep opens ERP lead page with score + insights. Agent delivers brief 30 min before scheduled call.

Rep reads · Agent drafts

STEP 07 — 08

Negotiation support

Post-call transcript → structured deal fields. Rep clicks Generate Proposal → agent + Finance verifier output draft.

Rep drives · Agent supports

The core value Agent handles repetitive upstream work (research, scoring, note-taking) so rep spends time on what only a human can do: talking to the customer, understanding the real need, closing.

04 / Phase Plan

Value-first ordering — Proposal ships before Qualify

Rep sees tangible output (a proposal document) in week 2-3 instead of waiting for full pipeline. Platform primitives build in M0, then each vertical phase adds 1 skill group.

Phase	Scope	Effort	Value delivered
M0	Platform primitives. Skill registry · Workflow runner (sync first) · Integration adapter generalize · JWT SSO · ERP schema PR with Twendee team	~60h	Infra foundation — no user value yet
M1	Proposal Generator. sales.proposal-generator skill · Finance cross-check · chat widget embed on ERP Deal page · POST /skills/.../run API	~48h	Rep generates proposal from ERP in < 3 min
M2	Qualification Pipeline. sales.icp-scorer · async workflow runner · platform.notify (Telegram) · push score to ERP via webhook	~36h	Auto-scoring · Hot lead notifications < 60s
M3	Discovery. sales.pre-call-briefer · sales.post-call-extractor · memory wiring · transcript upload UI	~32h	Pre-call brief 30min before call
M4	Polish + dogfood. Observability dashboards · bug fixes · 1-week BD team dogfood	~16h	Production-ready · metrics-validated

05 / Key Decisions

9 design choices — what was rejected, what was selected

Each decision locks a trade-off. Listed with rationale so future readers can challenge them if constraints change.

01 · Data ownership

ERP is SoR · Hub caches

ERP owns lead/deal rows + UI. Hub stores only agent-layer data (skill runs, memory, workflow state). Avoids duplicate schema and sync conflict.

02 · Agent config

Hybrid: UI config + code skills

Admin UI configures agent name, prompts, rules, tool toggles. Skills are code-registered. Avoids over-engineered DSL while keeping config flexible.

03 · UI duplication

No /leads /deals UI in Hub

ERP already has best-in-class lead/deal UI. Hub only builds what ERP lacks — agent config, chat, approvals. Saves ~40h of duplicate work.

04 · Workflow runner

2-tier shared core

Sync in-process for user-triggered (proposal gen). Async BullMQ for batch/cron (qualify 500 leads / 5 min). Approval steps pause-resume via persisted job state.

05 · Auth

JWT passthrough ERP → Hub

ERP signs JWT (tenantId, userId, roles, exp). Hub verifies shared secret. Deep-link + widget embed both use same token. IdP upgrade path kept behind AuthProvider interface.

06 · Phase ordering

Proposal before Qualify

User-facing value first. Rep sees proposal output week 2-3. Forces platform primitives to ship early — later phases reuse the same runner, adapter, and SSO plumbing.