Skip to content

Data Agent SMS Runtime (Convex code)

GiveCare internal. Current live Convex runtime across apps/data-agent/convex/schema.ts, apps/data-agent/convex/schema/sms.ts, sms/twilioInbound.ts, sms/turns.ts, sms/turns/runTurn.ts, sms/turns/runMiraTurn.ts, sms/writes/persistence.ts, and sms/scheduler.ts.

Key information used in wiki

  • The live backend is a unified Convex deployment that combines org, benefits, admin-auth, assessment, pulse, email, SMS, and web tables rather than a standalone SMS-only schema.
  • The core SMS runtime is built around caregivers, conversations, messages, turnState, turnRuns, jobs, smsDispatches, alertDispatches, assessmentRuns, scoreSnapshots, caregiverFacts, benefitsScreenings, resourceCatalog, resourceInteractions, memoryAssertions, and memoryCheckpoints.
  • The inbound SMS entrypoint in twilioInbound.ts performs signature validation, regulatory keyword handling, inbound rate limiting, unknown-number redirect, SHARE keyword handling, inbound persistence, and then turn scheduling.
  • The live host turn path is sms/turns.ts → sms/turns/runTurn.ts, where the system loads the turn envelope, decides deterministic-versus-agent handling, runs either runDeterministicTurn or runMiraTurn, and commits through the atomic persistence seam.
  • writes/persistence.ts:commitTurn is the critical commit boundary: it patches caregiver and conversation state, records turnState, events, and turnRuns, writes care-memory artifacts, persists pending prompts, enqueues follow-up jobs, and schedules outbound SMS segments.
  • sms/scheduler.ts is a job queue for scheduled sends (followup, weeklyBriefing, welcomeRetry) with request-key dedupe and recent-template guards, not a global loop-arbiter tick in the older design-spec sense.