Agent Runtime — Kiến trúc tổng quan & Sales-v0 flow

flowchart TB
  %% ① Clients
  subgraph CLIENT["① Clients"]
    direction LR
    USR["End users
(Telegram · Web · Email)"]
    OPS["Operators
(Admin UI)"]
  end

  %% ② Channels
  subgraph CH["② Channels"]
    direction LR
    REST["REST API"]
    TGC["Telegram"]
    SGC["SendGrid"]
  end

  %% ③ Agent Runtime — the brain
  subgraph RT["③ Agent Runtime"]
    direction LR
    TRG["Triggers
cron · event · message · webhook"]
    EXE["Executor
workflow + step pipeline"]
    REG["Registries
agents · steps · tools"]
    TRG --> EXE
    REG -. lookup .-> EXE
  end

  %% ④ Capability layers
  subgraph CAP["④ Capabilities"]
    direction LR
    TOOLS["Tools
(MCP · Native · Memory)"]
    ADP["ERP Adapters
(@twd/erp-adapters)"]
    LLM["LLM
(tier router)"]
  end

  %% ⑤ External
  subgraph EXT["⑤ External services"]
    direction LR
    ERP[("Twendee ERP")]
    APO[("Apollo.io")]
    EMAIL[("SendGrid · Gmail")]
    AI[("OpenAI · Gemini · Ollama")]
  end

  %% ⑥ Platform
  subgraph PLT["⑥ Platform"]
    direction LR
    PG[("PostgreSQL
multi-tenant + RLS")]
    RD[("Redis
queues + cache")]
    SEC["Auth · Encryption ·
Metering · Observability"]
  end

  CLIENT ==> CH ==> RT ==> CAP
  ADP --> ERP
  ADP --> APO
  ADP --> EMAIL
  LLM --> AI
  RT -.-> PLT

  classDef ch fill:transparent,stroke:#0f766e,color:inherit;
  classDef rt fill:transparent,stroke:#b45309,color:inherit;
  classDef tl fill:transparent,stroke:#4d7c0f,color:inherit;
  classDef ad fill:transparent,stroke:#7c3aed,color:inherit;
  class REST,TG,SG,UI ch;
  class TR,EX,SE,REG rt;
  class TI,TR2 tl;
  class APOL,CRM,EM,OTH ad;

flowchart LR
  AG["defineAgent
id identity triggers
tools channels budget"] --> AR["AgentRegistryService
boot scan"]
  AR --> TBUS["Trigger Bus"]

  TBUS --> CRON["CronScheduler
BullMQ repeat + LISTEN
agent_workflows_changed"]
  TBUS --> EVT["EventBus
emit fanout matched agents"]
  TBUS --> MSG["MessageRouter
team lead · mention · keywords · fallback"]
  TBUS --> WHK["Webhook controller"]

  CRON --> Q["trigger-exec queue
BullMQ"]
  EVT --> Q
  MSG --> Q
  WHK --> Q

  Q --> P["TriggerExecProcessor"]
  P --> WF["WorkflowExecutor
runPipeline steps ctx"]
  WF --> SX["StepExecutor"]

  SX --> PR["ParamResolver
trigger.x · steps.id.y"]
  SX --> BG["BudgetGuard
tokens · cost · duration"]
  SX --> OBS["ObservabilityInjector
pipeline_events"]
  SX --> SR["StepRegistry
handler dispatch"]

  SR --> DATA["data steps
salesRunCampaignsBatch
apolloEnrichLeads
erpQueryLead
erpUpsertContacts"]
  SR --> LLMS["llm steps
defaultChatLoop
clarifyRequirements
draftProposal ..."]
  SR --> OUT["output steps
telegramNotify · emitEvent"]

  classDef rt fill:transparent,stroke:#b45309,color:inherit;
  classDef tr fill:transparent,stroke:#0f766e,color:inherit;
  classDef st fill:transparent,stroke:#4d7c0f,color:inherit;
  class AG,AR,WF,SX,P rt;
  class TBUS,CRON,EVT,MSG,WHK,Q tr;
  class DATA,LLMS,OUT,SR,PR,BG,OBS st;

flowchart TB
  STEP["Step handler
e.g. salesRunCampaignsBatch"] -->|"invoke qualifiedName params ctx"| TI["ToolInvokerService"]

  TI --> ZV["Zod validate
tool.inputSchema"]
  TI --> AUDIT["Audit log
tool.invoked"]
  TI --> RAW["tool.rawHandler
parsed, ctx"]

  RAW --> RES["AdapterResolver ctx
SalesIntegrationFactoryService.bundleFor"]
  RES -->|"per-tenant"| BUNDLE["SalesAdapterBundle
apollo · crm · email"]

  BUNDLE --> APO["Apollo client
ISalesEnrichmentPort"]
  BUNDLE --> CRMA["TwendeeCRMAdapter
ICRMAdapter
via TwendeeHttpClient"]
  BUNDLE --> EMP["Email port
SendGrid · Gmail OAuth"]

  CRMA -->|"HTTPS"| CRMERP[("Twendee ERP
REST API")]
  APO -->|"HTTPS"| APOAPI[("Apollo.io API")]
  EMP -->|"HTTPS"| SGAPI[("SendGrid /
Gmail SMTP")]

  subgraph TR2["ToolRegistry contents"]
    direction LR
    M["MCP tools
sales.campaign_*
sales.crm_*"]
    N["Native dynamic tools
SQL · HTTP scripts"]
    MEM["Memory tools"]
  end
  TI -. lookup .- TR2

  classDef st fill:transparent,stroke:#4d7c0f,color:inherit;
  classDef ad fill:transparent,stroke:#7c3aed,color:inherit;
  classDef erp fill:transparent,stroke:#b45309,color:inherit;
  class STEP,TI,RAW,ZV,AUDIT,M,N,MEM st;
  class RES,BUNDLE,APO,CRMA,EMP ad;
  class CRMERP,APOAPI,SGAPI erp;

sequenceDiagram
  autonumber
  participant CRON as BullMQ repeat
  participant FAN as CronFanoutProcessor
  participant Q as trigger exec queue
  participant WF as WorkflowExecutor
  participant BATCH as salesRunCampaignsBatch
  participant TI as ToolInvoker
  participant CRM as Twendee CRM
  participant APO as Apollo
  participant LLM as LLM smart tier
  participant TG as Telegram

  CRON->>FAN: fire sales v0 cron apollo
  FAN->>Q: enqueue per tenant jobs
  Q->>WF: runPipeline batch notify fanout

  WF->>BATCH: handler ctx params
  BATCH->>TI: campaign_list_active
  TI->>CRM: GET active campaigns
  CRM-->>BATCH: up to 5 campaigns

  loop per campaign
    BATCH->>TI: campaign_search_apollo_leads
    TI->>APO: POST mixed_people search with ICP filter
    APO-->>BATCH: leads
    BATCH->>TI: campaign_create_lead concurrency 5
    TI->>CRM: upsert contact and link campaignId
    BATCH->>LLM: draft personalized email
    BATCH->>TI: campaign_save_email_template
    TI->>CRM: save PENDING_REVIEW draft
  end

  BATCH-->>WF: perCampaign reportHtml upsertedIds
  WF->>TI: telegramNotify chatId from agent_workflows
  TI->>TG: sendMessage reportHtml
  Note over TG: onError continue
  WF->>WF: emitEvent salesLeadsImported with upsertedIds

flowchart LR
  PROD["Producer
REST controller / ERP webhook /
another agent"] -->|"emit rfqReceived"| EB["EventBus"]
  EB -->|"jobId via sha payload
match subscribers"| Q["trigger exec queue"]
  Q --> WF["WorkflowExecutor"]
  WF --> S1["clarify
step clarifyRequirements
rfq from trigger.rfq"]
  S1 --> S2["draft
step draftProposal
rfq + clarifications"]
  S2 --> S3["notify
step telegramNotify
onError continue"]
  S3 --> TG[("Telegram chat")]

  classDef st fill:transparent,stroke:#4d7c0f,color:inherit;
  classDef tr fill:transparent,stroke:#0f766e,color:inherit;
  class S1,S2,S3 st;
  class EB,Q,WF tr;

sequenceDiagram
  autonumber
  participant U as User
  participant TG as Telegram Bot API
  participant WH as TelegramController
  participant IDM as Idempotency
  participant MR as MessageRouter
  participant Q as trigger exec queue
  participant WF as WorkflowExecutor
  participant CHAT as defaultChatLoop
  participant TI as ToolInvoker
  participant CRM as Twendee CRM
  participant LLM as LLM

  U->>TG: message
  TG->>WH: POST telegram webhook
  WH->>IDM: dedupe by update id
  WH->>MR: dispatch tenant channel text conversationId
  MR->>MR: resolve agent by lead mention keywords fallback
  MR->>Q: enqueue sales v0 message trigger
  Q->>WF: runPipeline chat
  WF->>CHAT: handler ctx
  CHAT->>LLM: chat with tool erpQueryLead
  alt tool call
    LLM-->>CHAT: tool_call erpQueryLead args
    CHAT->>TI: invoke erp_query_lead args mcpCtx
    TI->>CRM: GET leads
    CRM-->>CHAT: result
    CHAT->>LLM: continue with tool result
  end
  LLM-->>CHAT: final reply
  CHAT->>TG: channels reply conversationId text
  TG->>U: bot message