Design a call to text message survey generator

Problem Statement

Design a system that enables organizations to conduct surveys by initiating outbound phone calls to participants, delivering a brief introduction, and then transitioning the interaction to SMS so respondents can answer questions at their own pace via text message. Surveys support branching logic (subsequent questions depend on previous answers), may span hours or days with pauses and resumptions, and must comply with telecommunications regulations including consent tracking and opt-out handling.

The core engineering challenges are managing long-running, stateful conversations over unreliable channels (telephony and SMS), integrating with third-party providers subject to rate limits and delivery failures, orchestrating branching survey logic at scale, and providing real-time campaign analytics. You will need to reason about state-machine-based workflow orchestration, idempotent message processing, carrier rate limiting, and decoupled event-driven architectures.

Key Requirements

Functional

• Survey authoring -- campaign creators define multi-question surveys with conditional branching, input validation, and configurable reminder schedules
• Call initiation and SMS handoff -- the system places outbound calls, plays voice prompts, and transitions consenting respondents to an SMS-based questionnaire
• Conversational SMS flow -- respondents receive questions one at a time, reply with answers, receive validation feedback, and can pause and resume at any point
• Compliance and consent -- track explicit opt-in during the call, honor STOP/UNSUBSCRIBE keywords instantly, and maintain audit logs
• Campaign monitoring -- provide real-time dashboards showing response rates, question-level drop-off, completion velocity, and exportable results

Non-Functional

• Scalability -- support 500-plus simultaneous campaigns with 100,000-plus active respondents; handle 50,000 inbound SMS messages per minute at peak
• Reliability -- tolerate telephony provider outages, SMS delivery delays, duplicate messages, and out-of-order replies without losing conversation state
• Latency -- respond to inbound SMS within two seconds to maintain a conversational feel; process outbound message queues with sub-minute latency
• Consistency -- each respondent sees questions in the correct order based on their answers; prevent duplicate question sends even during retries

What Interviewers Focus On

Based on real interview experiences at Aurelian, these are the areas interviewers probe most deeply:

1. Stateful Conversation Management

Each respondent interaction is a long-running, multi-step workflow that must survive server restarts, handle replies arriving hours or days later, and correctly interpret answers in the context of the current question. Interviewers want to see how you model, persist, and protect conversation state.

Hints to consider:

• Model each respondent session as a finite state machine with the current question ID, answer history, and branching path; persist checkpoints in PostgreSQL with optimistic locking (version column)
• Cache active sessions in Redis with a seven-day TTL to avoid hitting the database on every inbound message
• Deduplicate inbound SMS using an idempotency set in Redis keyed by (message_id, respondent_id) with TTL
• Implement scheduled reminders as durable timer jobs that check session state and re-send the current question if no reply has been received

2. Integration with Unreliable External Providers

Telephony and SMS providers deliver webhooks that may arrive late, duplicated, or not at all. Carrier throughput limits fluctuate, and over-sending degrades sender reputation or triggers blocks.

Hints to consider:

• Accept provider webhooks into a Kafka topic immediately with minimal processing; return HTTP 200 quickly to prevent provider retries
• Implement per-campaign and per-phone-number token-bucket rate limiters to stay within carrier throughput caps
• Use exponential backoff with jitter for failed outbound sends; route persistent failures to a dead-letter queue for manual review
• Monitor delivery receipts and dynamically adjust sending rates based on throttle signals from the provider API

3. Branching Logic and Survey Orchestration

Surveys have conditional paths where question three may depend on the answer to question two. Interviewers assess how you evaluate rules efficiently, keep survey definitions decoupled from execution code, and enable non-technical users to author complex flows.

Hints to consider:

• Store survey definitions as directed acyclic graphs in JSON: each node represents a question with outgoing edges labeled by answer conditions
• Evaluate branching conditions with a lightweight rule engine operating on the respondent's accumulated answers
• Cache compiled survey graphs in memory per campaign to avoid re-parsing on every inbound message
• Version survey definitions so in-flight conversations continue with the version they started, even if the campaign creator edits the survey

4. Analytics and Real-Time Monitoring

Campaign managers need near-real-time visibility into response rates, bottleneck questions, and completion funnels without slowing down the operational message-processing path.

Hints to consider:

• Stream conversation events (question sent, answer received, session completed) to Kafka for asynchronous consumption by an analytics pipeline
• Materialize aggregates (response counts, drop-off rates by question) into a read-optimized OLAP store or time-series database, updated incrementally
• Use change data capture from PostgreSQL to feed completed survey responses into a data warehouse for historical analysis and CSV export
• Provide approximate real-time unique counts using HyperLogLog if exact metrics are too expensive at scale

5. Compliance and Abuse Prevention

Telecommunications regulations require explicit consent before sending marketing SMS, immediate processing of opt-out requests, and retention of proof-of-consent records.

Hints to consider:

• Record consent timestamp, call recording reference, and metadata in a tamper-evident audit log during the initial call
• Maintain a global opt-out list checked synchronously before every outbound message; replicate updates to all sending workers within seconds
• Implement campaign-level circuit breakers that halt sending when complaint rates or carrier block rates exceed thresholds
• Rate-limit reminder sends per respondent (for example, one reminder per 24 hours) to prevent notification fatigue

Suggested Approach

Step 1: Clarify Requirements

Confirm scale parameters: concurrent campaigns, respondents per campaign, and peak inbound SMS rate. Ask about survey complexity: maximum questions, branching depth, and multimedia support. Clarify timing: can surveys span multiple days, and are there timezone restrictions for sending? Determine provider strategy: single provider or multi-provider redundancy. Verify compliance requirements and consent retention period.

Step 2: High-Level Architecture

Sketch the main components. Control plane: REST API for campaign creation, survey authoring, and result retrieval. Campaign orchestrator: manages outbound call scheduling, drives conversation state machines, and consumes work from internal queues. Telephony adapter: wraps provider APIs (Twilio, Plivo) for placing calls and receiving status webhooks. SMS gateway: sends outbound texts with rate limiting and receives inbound webhooks, publishing to Kafka. Conversation engine: stateful service that loads a respondent session, evaluates branching logic, determines the next question, and updates state atomically. Event stream (Kafka): central bus for inbound messages, outbound sends, state transitions, and analytics events. Session store (Redis plus PostgreSQL): Redis caches active sessions; PostgreSQL persists survey definitions, consent records, and responses. Analytics pipeline: consumes events, aggregates metrics, and writes to an OLAP store for dashboards and exports.

Step 3: Deep Dive on Conversation State

Walk through a single respondent's session. When consent is obtained on the call, a session record is created in PostgreSQL with the respondent ID, campaign ID, survey version, and initial state (question one). The session summary is written to Redis with a seven-day TTL. An inbound SMS webhook arrives and is published to the inbound-sms Kafka topic. A consumer fetches the session from Redis (or PostgreSQL on cache miss), validates the message is not a duplicate using the idempotency set, and locks the session with optimistic versioning. It evaluates the answer against the current question's validation rules. If valid, the answer is appended to history, the branching logic selects the next question, the session version is incremented, and the transaction is committed. An outbound message event is published to the outbound-sms Kafka topic. A separate consumer dequeues it, checks the token bucket for the campaign's phone number pool, and calls the SMS provider API.

Step 4: Address Secondary Concerns

Cover scalability: partition Kafka topics by respondent ID; shard Redis by respondent hash; scale conversation engine consumers horizontally. Discuss reliability: dead-letter queues for messages that fail after retries; circuit breakers on provider API calls. Address rate limiting: token buckets per campaign, per phone number, and globally. Mention compliance: global opt-out bloom filter checked before every send; consent records stored with call recording references; GDPR export and delete APIs. Cover monitoring: queue depth, processing latency, provider error rates, and campaign completion metrics with alerting on anomalies.

Related Learning Resources

• Design a Job Scheduler -- covers durable task scheduling, retry strategies, and rate-limited worker pools directly applicable to campaign orchestration
• Design Slack -- explores real-time message delivery, WebSocket infrastructure, and event-driven communication patterns relevant to the conversational SMS flow