TRANSO AI Sales Bot
A modular Spring Boot backend engineered to ingest inbound Meta Messenger events, execute bounded KiotViet inventory reads, enforce vendor-neutral failure semantics, and persist durable employee-review work items with database-enforced invariants.
- • Verified inbound Meta webhook ingestion with HMAC-SHA256 signature validation and idempotency checking.
- • Bounded KiotViet product, price, and inventory integration preventing unconstrained downstream stalls.
- • Defensive read resilience with configurable timeouts and limited retry semantics on external vendor calls.
- • Vendor-neutral integration failure translation mapping third-party errors into structured internal states.
- • Deterministic human-handoff triggers when inventory state is ambiguous or customer intent requires manual care.
- • No message queue or distributed broker infrastructure (no RabbitMQ, Kafka, or Redis).
- • No circuit breaker pattern implemented (bounded reads rely on timeouts and limited retries).
- • No completed outbound Meta Messenger message delivery pipeline.
- • No completed employee review UI or review management REST API.
- • No completed CRM synchronization.
- • No production deployment, live customer traffic, or commercial revenue claims.
System Boundaries & Event Lifecycle
Materializes inbound events into conversation message state. Evaluates intent classification rules, applies human-handoff triggers, and initiates bounded external queries.
Executes bounded inventory, product search, and retail price lookups. Protected by strict connection/read timeouts and limited retries (no circuit breaker). Translates provider faults to vendor-neutral error types.
Generated when inventory is verified and intent matches product catalog. Composes structured response draft grounded strictly in confirmed stock data for human review.
Triggered upon ambiguous queries, timeout degradation, or explicit handoff. Persisted directly to PostgreSQL with database-enforced invariants and idempotency semantics (no queue / no Redis).
1. Inbound Meta Webhook Ingestion & Signature Verification
When Meta Messenger delivers webhook events, network transport must be treated as untrusted and susceptible to replays. The ingestion layer intercepts requests before domain dispatching:
- HMAC-SHA256 Verification: The request payload is verified against the application secret key matching the
X-Hub-Signature-256header. - Immutable Raw Event Logging: Validated webhook payloads are appended to an immutable inbound event store in PostgreSQL before transformation.
- Idempotent Event Materialization: Event processing guarantees that duplicate webhook delivery IDs are identified and safely ignored without duplicate business actions.
2. Bounded KiotViet Inventory Reads & Resilience
The project interfaces with the KiotViet retail management API for product search, stock levels, and default retail prices. Because external vendor networks are prone to latency spikes and outages, strict bounded read semantics are enforced:
- Bounded Read Timeouts: Configurable connection and read timeouts prevent external slow responses from tying up HTTP worker threads.
- Limited Retry Semantics: Limited retry policies apply only to transient idempotent read failures, preventing self-inflicted denial of service.
- Vendor-Neutral Fault Isolation: Rather than leaking KiotViet-specific HTTP status codes or exceptions into the core domain, vendor errors are translated into typed internal fault categories.
- Zero Inventory Caching Claim: All inventory evaluations are executed against direct bounded vendor reads; no speculative caching layers are assumed.
3. Durable Employee-Review Work Items with Database Invariants
When product availability is ambiguous, pricing requires manual confirmation, or the customer expresses complex intent, autonomous AI generation is deliberately stopped. Instead, the system produces a structured, reviewable handoff:
- Persisted Work Items: Rather than relying on transient queues or memory buffers, review items are committed to PostgreSQL tables with unique relational constraints.
- Database-Enforced Invariants & Idempotency: Unique compound indices prevent duplicate work items from being created for the same customer inquiry or webhook event.
- Deterministic Reviewable Drafts: The engine prepares an explainable, fact-checked response draft referencing confirmed product attributes, empowering human operators to verify or adjust before sending.
4. Automated Verification via Testcontainers
In-memory databases (like H2) often fail to replicate real PostgreSQL dialect nuances, transaction isolation levels, and Flyway migration behaviors. TRANSO enforces verification through disposable containers:
Current Engineering Milestone Status
TRANSO AI Sales Bot is currently in active development under Milestone 7. Verified components include inbound webhook ingestion, bounded KiotViet client reads, domain materialization, Flyway database invariants, and Testcontainers automated suites. Ongoing work focuses on human review API ergonomics. No live production deployment or end-to-end outbound messaging pipeline is claimed.