Skip to content

Backend

GiveCare's current gc-sms backend is a compact Greenfield Convex service for SMS-first caregiver support. Current-tense architecture claims should use the active domain/, agent/, convex/, and knowledge/ files. The retired BrownZip runtime exists in git history, not in the active tree1.

Current Greenfield runtime

The active backend contract is the Greenfield gc-sms runtime. The live system is best read as a harness-owned SMS turn kernel with a compact Convex schema12.

What the backend owns

Today the backend owns six broad kinds of state and behavior1:

  1. Caregiver identity and channel consent - caregiver records, channel ownership, send permissions, and consent/safety state
  2. Conversation and turn processing - active conversations, inbound turns, deterministic gates, Pi reservation, commit, review, and failure states
  3. Messages and transport - inbound/outbound message records, outbox rows, Twilio provider SIDs, leases, retries, callbacks, and send-class checks
  4. Memory, loops, and assessment proof - typed memories, caregiver-owned follow-up/load loops, assessment runs, and score snapshots
  5. Events, projections, proof, and learning - append-oriented events plus operator, proof, and learning projections over them
  6. Generated knowledge lookup - static benefits, resources, strategies, and guidance-card bundles adapted for Pi tools

Core Live Tables

Group Tables What they hold
Identity + channel caregivers, channelStates caregiver record, phone hash/address ownership, consent state, send permissions, identity state, and compatibility lifecycle fields
Conversation + turn conversations, turns active conversation per channel state, inbound processing unit, phase, boundary kind, risk, reply, and failure reason
Messages + transport messages, outbox inbound/outbound/internal messages, provider SIDs, queued SMS work, send leases, attempts, provider status, and idempotency keys
Memory + loops memories, loops validated caregiver-stated facts, stale/superseded state, caregiver-owned follow-up/load loops, due time, and stop condition
Assessment + score assessmentRuns, scoreSnapshots GC-SDOH assessment progress, baseline/remeasure scores, attribution language, and loop anchors
Events events gate, context, reason, commit, transport, operator, learning, review, safety, gap, proof, and projection substrate

Live Inbound Path

flowchart TD
    A["Twilio inbound webhook"] --> B["convex/http.ts signature check"]
    B --> C["transport.handleIncomingMessage"]
    C --> D["turns.receive"]
    D --> E["Durable caregiver/channel/conversation/turn"]
    E --> F{"Domain gate"}
    F -->|Boundary| G["Boundary reason result"]
    F -->|Allow| H["mira.runTurn"]
    H --> I["reserve + assemble context"]
    I --> J["Pi Agent Core + tools"]
    J --> K{"Result ok?"}
    K -->|No| L["review / failed terminal turn"]
    K -->|Yes| M["commitAgentReasonResult"]
    G --> N["commitReasonResult"]
    M --> N
    N --> O["Outbox row / suppressed / blocked"]
    O --> P["transport sender + Twilio callback"]

Turn Execution Model

The current runtime separates host-owned guarantees from model-owned language and judgment1.

Layer Current responsibility
Domain gates STOP/HELP/PAUSE/RESTART, consent/safety/identity blocks, deterministic safety routing
Context builder recent durable state, active memories, open loops, channel constraints, source constraints, model metadata
Model/tool path one Pi Agent Core reasoning span, generated-knowledge tools, and required structured final result
Validation final reply checks, source-grounding checks, actor/scope checks, proposed-intent checks
Commit boundary outbound outbox, approved memories, loops, assessment runs, score snapshots, safety/review/gap events

The practical unit of orchestration is not "a model reply"; it is a committed turn outcome. convex/turns.ts:commitReasonResult records the outbound work before Twilio send, applies only validated intents, records events, and moves the turn to committed or review. Approved follow-up requests create loops only after consent and due-time validation, and convex/followups.ts handles later delivery1.

Rules that do not need Convex state live in domain/index.ts: deterministic gates, boundary result conversion, reply validation, and proposed-intent validation. Pi-specific prompt/tool/final-output rules live in agent/ 1.

Knowledge Bundles

The backend consumes public knowledge from generated static bundles rather than from a live wiki database. Wiki Hound projects one versioned gc-sms.json owner bundle. The fixed gc-sms sync resolves its single ArtifactRef and atomically fans it into runtime-local files. knowledge/catalog.ts adapts knowledge/generated/benefits.json, resources.json, strategies.json, and guidance-cards.json; knowledge/toolAdapters.ts and agent/tools.ts expose them to Pi as bounded in-process evidence tools. This keeps public knowledge ownership in gc-wiki and gc-benefits while the SMS runtime remains the serving layer1.

Scheduler and Outbox

There is no separate live BrownZip job table. Convex schedules Pi actions and follow-up delivery directly from the turn/loop commit path. Outbound SMS uses a transactional outbox pattern: commit inserts an outbox row, convex/transport.ts claims and sends queued rows, and Twilio callbacks update provider status1.

  1. GiveCare. "GC-SMS Runtime Contract." Exact verified Hound owner projection. Source -> ↩↩↩↩↩↩↩↩

  2. GiveCare. "GiveCare Backend Specification." Source -> ↩