Call Me Maybe — Tech Spec

01 / Implementation Status

What's Built vs What's Left

Auth (Clerk) Done

Clerk JWT auth + dev fallback via X-Dev-User-Sub header. Lazy-create user on first authenticated request.

Onboarding Done

Session + answers upsert, voice note upload (stored locally), persona selection stored as onboarding answer.

Goals Done

Goal templates (weight_loss, get_fit) seeded. Create/list/update goals via API.

Commitments Done

Contract creation + signing, invite links (single-use, 7-day expiry), public accountability view via access_token.

Compliance Done

Compliance events + window-based score (30d). Used for public views + bet settlement.

Betting Done

Guests bet for/against commitment. Owner settles bets at contract end. Money rails via Stripe TODO.

Telegram Linking Only

Link code creation + webhook consumption works. Outbound nudges and scheduling TODO.

Wearables Manual

Store tokens for Oura/Whoop. Upsert/list daily summaries. OAuth flow and auto-sync TODO.

Voice Calls Scaffold

Twilio outbound endpoint + voice webhook + ElevenLabs TwiML helper. Needs env vars + public URL.

Payments Stub

Placeholder payment intent for commitment deposits. Full Stripe integration TODO.

Dashboard API Done

GET /dashboard returns today's summary + 7/30 day trends from wearable data.

WhatsApp TODO

Phase 2. Twilio WhatsApp number + webhook. 24h service window + template approval needed.

02 / Core User Flows

MVP Path

Onboarding
Questions + voice

→

Commitment
Sign + invite

→

Telegram
Link + nudges

→

Wearables
Oura / Whoop

→

Dashboard
Trends + plan

Onboarding Data Captured

Identity

Name, email/phone, locale, timezone, preferred language

Body Metrics

Height, weight, target weight, body fat% (optional)

Health Context

Injuries, conditions, medications, contraindications

Lifestyle

Schedule, sleep, work type, activity level, gym access, equipment

Preferences

Coaching style (supportive/strict/humor), profanity Y/N, persona choice

Commitment

Stake type (money/family/friends), sign contract, invite accountability

03 / API Endpoints

28 Endpoints Implemented ▶

Method	Path	Description
GET	/me	Current user info
POST	/onboarding/sessions	Create onboarding session
POST	/onboarding/sessions/{id}/answers	Upsert answers
POST	/onboarding/sessions/{id}/voice	Upload voice note
POST	/onboarding/sessions/{id}/complete	Complete onboarding
GET	/goals/templates	List goal templates
POST	/goals	Create goal
GET	/goals	List user goals
PATCH	/goals/{id}	Update goal
POST	/commitments/contracts	Create contract
POST	/commitments/contracts/{id}/sign	Sign contract
POST	/commitments/contracts/{id}/invite-links	Create invite link
POST	/commitments/invite-links/{token}/accept	Accept invite
GET	/public/accountability/{token}	Guest accountability view
GET	/public/betting/{token}	Guest betting view
POST	/public/betting/{token}/bets	Place a bet
GET	/bets/contracts/{id}	List bets on contract
POST	/bets/contracts/{id}/settle	Settle bets
POST	/compliance/events	Create compliance event
GET	/compliance/window/30d	30-day compliance score
POST	/wearables/{provider}/connect	Store wearable tokens
GET	/wearables/connections	List connections
POST	/wearables/{provider}/daily-summaries	Upsert daily data
GET	/wearables/{provider}/daily-summaries	Get daily data
GET	/dashboard	Dashboard summary
POST	/telegram/link-code	Generate link code
POST	/integrations/telegram/webhook	Telegram webhook
POST	/calls/outbound	Trigger outbound call

04 / Data Model

Postgres Schema (14 Tables)

👤 users

id pk

timezone text

locale text

coaching_style enum

profanity_ok bool

🔑 auth_identities

id pk

user_id fk

provider text

provider_subject unique

📋 onboarding_sessions

id pk

user_id fk

status enum

completed_at ts

📄 onboarding_answers

id pk

session_id fk

question_key text

answer jsonb

🎤 voice_assets

id pk

session_id fk

storage_url text

transcript_text text

🎯 user_goals

id pk

user_id fk

template_id fk?

config jsonb

status enum

📜 commitment_contracts

id pk

user_id fk

stake_type enum

stake_config jsonb

effective_from/to ts

✅ compliance_events

id pk

user_id fk

type text

data jsonb

💱 contract_bets

contract_id fk

viewer_id fk

side for/against

amount_cents int

status enum

⏱ wearable_connections

id pk

user_id fk

provider enum

tokens (enc) text

last_synced_at ts

📈 daily_summaries

id pk

user_id fk

provider enum

day date

data jsonb

💬 user_channels

id pk

user_id fk

type tg/wa/phone

address text

verified bool

🔔 nudge_attempts

id pk

user_id fk

reason text

status enum

sent_at ts

🚨 emergency_sessions

id pk

user_id fk

trigger_channel enum

context jsonb

outcome jsonb

05 / Integrations

External Services

💬

Telegram Phase 1

Bot via BotFather. Webhook at /integrations/telegram/webhook. User links via one-time code. Nudges (scheduled + reactive) TODO.

📲

WhatsApp Phase 2

Twilio WhatsApp number. 24h service window constraint. Needs pre-approved templates for outbound. Same linking flow as Telegram.

📞

Voice Calls Scaffold

Twilio telephony + ElevenLabs voice agents. Outbound call endpoint + voice webhook implemented. Needs env vars + public URL to activate.

⏱

Wearables Manual

Oura + Whoop. Manual token connect works. OAuth flow, auto-sync, and webhook listeners TODO. Daily summaries stored as JSONB.

💰

Payments (Stripe) Stub

Placeholder payment intent for commitment deposits. Full checkout flow, refund logic, and payout rails TODO.

06 / Voice Stack Options

Key Architecture Decision

Option A: Twilio + Custom Agent

Twilio handles calls, audio streamed via WebSockets (Media Streams). Your server runs STT + agent + TTS. Max control, swap vendors freely. More engineering.

Option B: Realtime Speech-to-Speech

Twilio for PSTN edge, realtime model handles conversation. Fewer moving parts, more natural. Vendor dependency, careful interruption handling.

Option C: Voice Notes Only (MVP)

User uploads voice note, backend stores + transcribes. Simplest path. No telephony complexity. Great for onboarding depth but not a "call".

Current implementation: Twilio outbound + ElevenLabs register-call for TwiML. This is Option B with ElevenLabs as the voice agent. Needs env vars to go live.

07 / Environment Variables

All Required Config ▶

🔑 Auth (Clerk)

CLERK_JWKS_URLJWKs endpoint for JWT verification

CLERK_ISSUERToken issuer

CLERK_AUDIENCEOptional audience enforcement

🗃 Database

DATABASE_URLPostgres connection string

💬 Telegram

TELEGRAM_BOT_TOKENFrom BotFather

TELEGRAM_WEBHOOK_SECRETOptional, recommended

⏱ Wearables

OURA_CLIENT_ID

OURA_CLIENT_SECRET

WHOOP_CLIENT_ID

WHOOP_CLIENT_SECRET

📞 Voice (Twilio + ElevenLabs)

TWILIO_ACCOUNT_SID

TWILIO_AUTH_TOKEN

TWILIO_FROM_NUMBERE.164 format

TWILIO_VOICE_WEBHOOK_URLPublic URL

ELEVENLABS_API_KEY

ELEVENLABS_DEFAULT_AGENT_ID

💰 Payments (Stripe)

STRIPE_SECRET_KEY

STRIPE_WEBHOOK_SECRET

STRIPE_SUCCESS_URL

STRIPE_CANCEL_URL

08 / Open Decisions

Questions to Resolve

MVP path priority?

Onboarding → Telegram nudges, OR onboarding → wearables dashboard, OR emergency button first?

Product

Wearables optional?

Can users use the app without Oura/Whoop (manual mode)?

Product

Voice stack selection

Twilio + custom agent vs realtime speech-to-speech vs voice notes only for MVP?

Tech

Job runner

Celery+beat vs ARQ vs APScheduler vs cron hitting endpoints?

Tech

Agent orchestration

Tool calling inside app vs MCP servers for integrations?

Tech

Languages day-1?

English + French? Turkish? Vietnamese? Affects voice personas and content.

Product

Commitment model

Pick one stake (money/family/friends) or combine? Failure payout rules?

Product

Medical vs wellness

Stay wellness to avoid regulated medical advice claims? Affects compliance path.

Legal

Voice personas & rights

Original voices only (no celebrity impersonation). Explicit opt-in for harsh/profane style.

Legal

Data retention

Voice recordings: 7 days, 30 days, or forever? "Delete my data" self-serve day-1?

Legal

WhatsApp provider

Twilio vs Meta Cloud API direct? Template approval flow needed.

Tech

Compliance scoring

Exact thresholds: workouts/week + nutrition check-ins + sleep targets for pass/fail?

Product

09 / Next Steps

Priority TODO

Voice: Configure Twilio + ElevenLabs

Create API keys, configure agent IDs, expose webhook publicly (ngrok/prod), trigger test outbound call.

Telegram: Implement nudge scheduling

Outbound nudges (daily check-in, missed workout, low recovery). Job runner decision needed first.

Wearables: OAuth flow

Replace manual token connect with proper OAuth for Oura and Whoop. Auto-sync periodic pulls.

Payments: Stripe integration

Commitment deposit capture, refund flow on success, payout rails for accountability buddies.

DB Migrations: Alembic

Replace create_all() with proper Alembic migrations for production readiness.

Voice transcription

Transcribe + summarize uploaded voice notes. Provider decision: OpenAI Whisper vs Deepgram.

Dev Quickstart

      docker compose up --build

      # API: http://localhost:8000/docs

      # Web: http://localhost:3000

      # Generate frontend types:

      cd frontend && npm run gen:types