Product Specification & Technical Architecture · v2.1

RY:ACT: Autonomous Sales Intelligence & Follow-up Operating System

Zero-entry conversation intelligence, 5-stage AI lifecycle state machine, deterministic SLA automation, and role-differentiated dispatches across omnichannel customer inboxes.

Document Status Approved Baseline v2.1

Lifecycle Stages 5 Canonical Stages

Channel Support Omnichannel (Zalo, WA, Mail)

Core Paradigm Zero-Adoption / Passive Sync

01 Executive Overview & Problem Statement

Modern B2B sales teams rely on fragmented customer messaging channels (Zalo OA, WhatsApp, Telegram) and enterprise mailboxes (Gmail, Outlook). Traditional CRMs fail because sales reps prioritize customer replies over manual data entry, creating three fatal failure points:

1. Inbound Black Hole

Shared messaging inboxes suffer from bystander apathy. Inbound enquiries go unreplied during the critical 30-minute window.

2. 48-Hour Quote Drop

A quotation is delivered, then silence. Reps fail to bump prospects after 2 days, assuming silence means rejection.

3. Invisible Deal Pipeline

Management lacks visibility into which quotes are in Negotiations vs. Lost without manually reading raw chat logs.

Zero Adoption Required: Sales staff communicate normally in their native apps with zero new software or logins.
AI 5-Stage Detection: The system automatically extracts commercial intent and advances enquiries across 5 canonical stages.
Role-Differentiated Dispatches: Managers receive high-level pipeline health + Q&A; staff receive prioritized daily follow-up queues.

02 System Architecture & Data Pipeline

Every conversation is ingested, reconciled, and processed through two independent parallel lanes: a deterministic timing/rules engine and an LLM semantic understanding lane.

03 AI Enquiry Lifecycle & 5 Canonical Stages

The system classifies each customer enquiry into one of 5 canonical stages based on conversation intent, document attachments, and commercial cues:

1. New Enquiry

Inbound greeting, initial product/service inquiry, RFQ submission, or general spec questions.

"Hello, do you have 500 units in stock for model M10?"

2. Quotation Stage

Formal quotation requested or sent, price sheet shared, PDF/image quote delivered.

"Please find attached Quotation #VN-88. Total: $4,200."

3. Negotiations

Price bargaining, discount requests, credit term adjustments, MOQ revisions, contract clauses.

"Can we get a 5% discount if we pay 50% deposit upfront?"

4. Won

Purchase Order (PO) issued, contract signed, deposit confirmed, delivery schedule locked.

"PO #4912 approved. Sent deposit slip to your accounting."

5. Closed

Lost deal, competitor chosen, budget revoked, project cancelled, or auto-dormant due to inactivity.

"We decided to proceed with an alternate supplier for this project."

Stage Transition State Machine

From Stage	To Stage	Primary Trigger Conditions	Automated Fallback / Timeout
`New Enquiry`	`Quotation Stage`	Staff provides price breakdown, sends quotation PDF/image attachment	If no staff reply in 2h → Flag Inbound SLA Breach
`Quotation Stage`	`Negotiations`	Customer counters on price, discount, payment terms, or MOQ	If quiet for 48h → Trigger 48h Follow-up Nudge
`Quotation / Nego`	`Won`	PO issued, signed agreement, or deposit payment verified	Logs deal value & cycle velocity automatically
`Any Stage`	`Closed`	Customer explicitly declines, budget cancelled, or manual archiving	Silent for 21–30 days without response → Auto-Dormant
`Closed`	`New Enquiry`	Customer initiates a brand-new RFQ after previous deal closed	Starts new enquiry lifecycle ticket

04 Prompt Engineering & State-Transition Engine

Single static LLM prompts fail on chat logs due to stage regression (e.g. classifying a negotiation question as a "New Enquiry") and token bloat. RY:ACT deploys a 3-Tier Incremental State Machine:

Tier 1: Deterministic Pre-Pass

Regex for PO patterns, attachment extractors (PDF quotes, image invoices), and cron time-decay (21d silence = Closed/Dormant).

Tier 2: State-Transition LLM

Receives current_stage + sliding window of 5–8 delta messages. Evaluates state transition validity with confidence score.

Tier 3: Guardrail Validator

Enforces legal state transitions (rejects illegal jumps like Won → New) and gates low-confidence classifications (<0.85).

State-Transition Classifier Specification

Input Payload Contract To Model

current_stage: quotation
allowed_transitions: ["negotiations", "won", "closed"]
sliding_delta_window: Last 5–8 messages (sender, text, timestamp, ID)
system_prompt: Determines valid transition and extracts evidence ID

Structured Output Contract From Model

transitioned: true / false
new_stage: negotiations
confidence: 0.96 (Gated ≥ 0.85)
reason: "Customer bargaining on payment terms"
evidence_message_id: msg_104 (Timestamped source citation)

05 Smart Admin Rule Engine & SLA Automations

Deterministic rules operate 24/7 independently of LLM availability, preventing lost revenue caused by team lapses.

Rule 1: Inbound Customer Priority (ASAP) Inbound SLA

Trigger: Customer sends the last message in a conversation thread.

0 – 15 mins: Normal state during working hours.
15 – 60 mins: Tagged as [Action Required: Reply ASAP] on Staff Action Queue.
> 2 hours: Escalated as critical SLA breach in Manager Executive Digest.

Rule 2: The 48-Hour Quote Nudge Outbound SLA

Trigger: Staff sent the last message (quote, proposal, terms) with zero customer reply.

0 – 48 hours: Marked as [Awaiting Customer] under consideration.
> 48 hours: Automatically surfaced to rep's morning action list as [Follow-up Due: 48h Bump].
Includes AI-generated 1-line recap of the proposal sent.

Environmental Guardrails: Timers calculate elapsed time strictly against company business hours (Mon–Fri 08:30–17:30, Sat 08:30–12:00) and automatically pause during Lunar New Year (Tet) and national holidays.

06 Role-Differentiated Reporting: Manager vs. Staff

A single underlying conversation database powers two completely distinct daily experiences:

FOR SALES LEADERS & DIRECTORS Executive Digest

Delivered every morning at 08:00 via Telegram / Web Console.

☀️ Daily Sales Pulse · 20 Aug

📊 Pipeline Status:
• 18 Active Enquiries (5 New, 8 Quoted, 4 Negotiations)
• 1 Won Yesterday (Hoang Gia JSC · $12,500)
• 2 Critical SLA Breaches

🔴 Urgent Overdue Responses:
• Minh Phat Trading: Customer asked for revised spec 4h ago during work hours. Unreplied.
View Thread Nudge Rep

🟡 Stalled in Negotiations (>3 days):
• Duc Thanh Co: Customer requested 30-day credit terms on 500 units.
Drill Down

💬 Reply to this bot to ask specifics about any account or deal.

Interactive Conversational Deep-Dive:
Manager can ask: "Why did Minh Phat stall in negotiations?" or "Show all quotes sent last week with no response." The system replies immediately with verified source links.

FOR SALES REPS & ACCOUNT EXECUTIVES Action Item Queue

Personal morning action list — zero noise, only actionable to-dos.

🎯 Your Follow-up Queue · 3 Action Items

⚡ 1. Minh Phat Trading [Quotation Stage]
• Reason: Customer replied 45m ago asking about Net-30 terms.
• Action: Reply ASAP
Open Thread Copy AI Draft

⏳ 2. Acme Vina — Ms Lan [Quotation Stage]
• Reason: You sent Quote #1042 48h ago. Customer has been quiet.
• Action: Send 48h follow-up bump.
Open Thread Generate Nudge

📦 3. Hoang Phat Co [Negotiations]
• Reason: Manager approved 5% volume discount.
• Action: Send revised quotation to client.
Open Thread

Zero Administrative Overhead:
Rep clicks directly into the customer thread, replies normally, and the system automatically clears the action item upon detecting the reply.

07 Conversational Query Engine across Omnichannel Threads

Users and executives can query the unified database in plain natural language (Vietnamese, English, Chinese) without complex SQL or dashboard configuration:

Query Type	Natural Language Prompt Example	AI Engine Resolution Mechanism
Pipeline Health	"How many deals are in Negotiations, and quiet > 3 days?"	Filters by `stage = 'Negotiations'` and `last_activity < NOW() - 3d` with conversation deep links.
Promise Verification	"What delivery schedule did we promise Acme Vina in March?"	Scans historical messages and PDF/image attachments across channels, citing the exact timestamped message.
Staff Response Audit	"What was our median first-response time to new enquiries this week?"	Calculates delta between inbound message and staff's first reply during verified business hours.

08 Admin Web Console, Channel Setup & 360° Customer Intelligence

The Admin Web Console provides a single-pane control center for channel onboarding, deep pipeline analytics, and data governance overrides.

1. Channel Auth Hub Onboarding

1-click OAuth & webhook setup for Zalo OA, Google Workspace (Gmail), and WhatsApp Business API with working hours and Tet holiday schedules.

2. 360° Customer Profile Unified View

Aggregated chronological timeline unifying all messages, quotes, spec PDFs, and photos across Zalo, Email, and WhatsApp into a single client record.

3. Admin Overrides Governance

Manually override enquiry stages (force to Won/Closed), merge cross-channel duplicate contacts, re-assign account owners, and set VIP SLA rules.

Admin Governance & Manual Override Capabilities

Control Surface	Admin Action & Mechanism	Data Integrity & Audit Trail
Manual Stage Override	Admin can force-advance or revert an enquiry stage (e.g. `Quotation` → `Won` or `Closed`) if an offline deal occurs.	Logs admin ID, timestamp, and override reason. AI respects manual lock until next active customer reply.
Cross-Channel Contact Merging	Merge a Zalo contact ID, phone number, and corporate email into a single canonical Account entity.	Unifies historical messages into one timeline without losing original source channel IDs or thread links.
Rep Re-assignment & Routing	Re-assign account ownership between sales reps or adjust shared inbox routing rules.	Updates assigned rep immediately; dispatches subsequent action items to the new owner's morning queue.
Custom SLA & VIP Rules	Override default 48-hour follow-up or 2-hour inbound SLAs for specific key accounts or enterprise deals.	Allows custom timer rules (e.g., 24h follow-up cadence or 30m urgent inbound SLA for Tier-1 clients).

09 Security, Privacy & Compliance Architecture

Read-Only Safety

The system operates strictly in read/ingest mode. It never sends automated outgoing messages to customers, ensuring zero accidental customer communication.

Zero Model Storage

Customer enterprise API keys are used directly with Anthropic / OpenAI / Google. Training on customer data is strictly disabled by contract.

Regulatory Compliance

Designed to meet regional Personal Data Protection regulations (Vietnam PDPD Decree 13/2023) and enterprise data residency standards.

10 Implementation Roadmap & Performance Profile

Phase	Milestone	Key Deliverables	Validation Criteria
Phase 1	3-Tier State-Transition Engine	Incremental transition classifier with guardrails for the 5 canonical stages.	>95% classification accuracy across test fixtures; <500ms latency.
Phase 2	Admin Rule & SLA Engine	Inbound urgency trigger (ASAP reply) and 48-hour follow-up cadence engine with holiday calendar support.	Accurate SLA calculation ignoring weekend and quiet hour windows.
Phase 3	Dual Dispatch Reporting	Manager Executive Daily Summary + Rep Personal Action Queue via Telegram Bot and Web.	Clear separation of role permissions and 1-tap deep links to messaging apps.
Phase 4	Omnichannel Ingestion Adapters	Generic webhook adapter interface supporting messaging channels (Zalo, WA) and enterprise mailboxes (Gmail).	Sub-second ingestion latency with automatic deduplication.

Fast Tier Latency

< 600 ms average classification latency using lightweight models (Gemini 1.5 Flash, Claude 3.5 Haiku, GPT-4o-mini).

Token Efficiency

~350 tokens per classification pass via sliding delta window, keeping LLM costs below $0.0002 / check.

Time-Decay Ghosting

Zero LLM cost on dormant deals: database cron transitions silent quotes (>21 days) to Closed automatically.

RY:ACT Engineering & Product Specification v2.1 Confidential · Internal & Enterprise Evaluation Only