Boundary 01 / 08
Twilio Voice
- Responsibility
- Receives the call, forwards it, and emits voice and dial-status webhooks.
- System boundary
- External event source
- Accepted tradeoff
- Provider delivery can be duplicated, delayed, or reordered.
Loading
02 / Event-driven SaaS
CallbackCloser / Engineering experience
Trace one missed call across telephony, signed webhooks, durable business rules, SMS qualification, and owner visibility.
Begin the walkthroughRepresentative trace · not a production latency claim
01 / 06
Live workflow timeline
Start the trace, then inspect any stage. The accelerated sequence teaches ordering; it does not claim measured production latency.
Representative event trace
One missed call · one durable lead
02 / 06
System architecture
Select a boundary to see what it owns, why it exists, and the complexity it introduces.
Boundary 01 / 08
03 / 06
Engineering decisions
These decisions are visible in the route handlers, domain modules, schema constraints, and operating runbook.
Why let providers push state changes?
Call, SMS, and delivery-status changes originate in Twilio. Signed webhooks move those events directly into the application instead of repeatedly asking whether anything changed.
Accepted tradeoff
The handlers must tolerate duplication, delay, reordering, authentication failures, and provider retry rules.
Why not keep qualification state in memory?
The lead stores the current SMS state and each message is persisted. Any later request can continue the conversation after a deploy, process restart, or long pause between replies.
Accepted tradeoff
Every transition becomes a database operation, and schema changes must preserve existing conversations.
What happens when Twilio retries an event?
Provider SIDs, unique call identifiers, one lead per call, and notification timestamps turn repeated callbacks into no-ops or updates to the same record.
Accepted tradeoff
Idempotency has to cover both persistence and external side effects; a unique row alone is not enough.
How are transient failures surfaced?
Webhook failures return retryable 5xx responses and correlation IDs. Delivery status is stored separately, while suppressed messaging records an operator-visible reason.
Accepted tradeoff
Retries improve recovery but make deduplication and structured observability mandatory.
Why is there no durable job queue?
The current implementation performs messaging and owner-notification work inside application request workflows. That keeps the system understandable at its present scale.
Accepted tradeoff
A durable queue would be the next boundary when volume, latency, or resumability makes request-bound delivery insufficient.
04 / 06
Operational impact
The system makes an interrupted customer journey visible, structured, and actionable.
A durable call and lead record preserves the opportunity even when billing, compliance, or provider setup prevents automation from continuing.
The SMS state machine collects service need, urgency, location, and callback preference instead of leaving the owner with only a phone number.
SMS, optional email, and the protected workspace expose the qualified lead and each channel's delivery state.
CallbackCloser captures a callback preference and creates an owner handoff. The current code does not book an appointment automatically, and no customer conversion rate is claimed.
05 / 06
Technology evidence
The stack is presented as implementation evidence, not a logo collection.
App Router UI, protected workspace, admin tools, and Twilio/Stripe route handlers.
app/, app/api/twilio/, app/api/stripe/
Voice forwarding, call status, recovery SMS, inbound replies, and delivery callbacks.
Voice + Messaging webhooks
Durable tenant, call, lead, message, consent, notification, subscription, and audit state.
prisma/schema.prisma
User identity and protected, business-scoped dashboard access.
Authenticated app workspace
Checkout, billing portal, signed subscription webhooks, and automation gating.
Subscription state reconciliation
Optional transactional owner-email delivery alongside SMS and in-app alerts.
Owner notification adapter
06 / 06
Lessons learned
The strongest lessons came from provider behavior, operational failure states, and knowing where the architecture should stop.
Event design
01Provider callbacks are not exactly-once messages. Designing around stable provider IDs, database constraints, and claimed side effects was more reliable than treating duplicates as exceptional.
Operational state
02Twilio acceptance starts another event lifecycle. Persisting status callbacks and suppression reasons makes the difference between an optimistic interface and an operable system.
Product boundaries
03Inactive subscriptions and usage limits stop outbound follow-up while the missed call and lead remain visible. Commercial state changes side effects, not the historical event.
Complexity budget
04Request-bound delivery is understandable at the current scale. Higher volume or stronger resumability requirements would move messaging and notifications into durable background work.
Honest outcomes
05The current system captures callback-ready context and notifies the owner. It does not contain a calendar integration, so this experience makes no automated-booking or conversion-rate claim.
Trace complete