TWDAGENTSHUB MVP DESIGN 2026-04-21 ~192h / 24 DEV-DAYS

Sales Agent MVP — Platform-first, ERP as System of Record

AgentsHub is a multi-tenant platform for configuring domain agents (Sales, HR, Accountant, ...). Sales Agent is the first concrete instance — it validates platform primitives while supporting the BD team with auto lead generation, qualification, pre-call context, and proposal drafting.

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
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: Slack 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
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 Slack 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 (Slack) · 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.