Schema Tables
automations
Workflow definitions. Fields: contractorId, name, description, trigger (triggerType union), triggerConfig, steps[] (automationStepDef), status (active/paused/draft/archived), tier (pro/pro_unlimited), totalRuns, lastRunAt, createdAt, updatedAt. Indexes: by_contractor_status, by_contractor_trigger, by_trigger_status. Search: search_name.
automationTemplates
Pre-built starter workflows. Fields: name, category, description, trigger, steps[], isSystem, tier, popularity. Index: by_category. 21 system templates across 6 categories.
automationRuns
Execution history. Fields: automationId, contractorId, contactId, triggeredBy (event/manual/schedule/mcp), status (running/completed/failed/cancelled), currentStep, stepResults[], startedAt, completedAt, error, costCents. Indexes: by_automation_status, by_contractor, by_contractor_started.
automationSteps
Denormalized step execution log. Fields: runId, stepIndex, type (stepType union), status (pending/executing/completed/failed/skipped), executedAt, completedAt, result, error. Index: by_run.
automationUsage
Monthly metering per contractor. Fields: contractorId, month (YYYY-MM), totalRuns, totalSteps, emailsSent, smsSent, voiceCallsMade, webhooksCalled, conditionsEvaluated, contactsUpdated, totalCostCents, lastChargedAt, stripePaymentIntentId. Indexes: by_contractor_month, by_month.
automationSettings
Singleton for admin kill switch. Fields: automationsPaused, pausedBy, pausedAt, systemContractorId.
Engine Functions
executeAutomation
Entry point (internalMutation). Checks global kill switch, hourly rate limit (100/hr), dedup guard. Creates run record, step logs, schedules processStep.
processStep
Recursive step executor (internalMutation). Handles all 18 step types via switch. Inline steps: condition, update_contact, add_tag, create_job, update_job_status, assign_to_team. Async steps: send_email, send_sms, webhook, voice_call, CRM sync, calendar. Wait steps use ctx.scheduler.runAfter.
recordStepAndContinue
Callback from async actions (internalMutation). Records step result, handles retries (MAX_RETRIES=3, 500ms base), advances to next step or marks run failed.
sendAutomationEmail
SendGrid HTTP action (internalAction). Resolves template variables via interpolateTemplate(), sends via SENDGRID_MAIL_URL.
sendAutomationSms
Twilio HTTP action (internalAction). Sends SMS via TWILIO_API_BASE with contractor's phone number.
recordRunUsageFromSteps
Usage metering (internal). Counts step types, calculates cost, upserts automationUsage for current billing month.
useTemplate
Clone template into contractor's automations (mutation). Checks tier compatibility, enforces PRO limit (5 automations), copies steps.
Step Type Registry (18)
Communication (4)
send_email (SendGrid), send_sms (Twilio), voice_call (Twilio + ElevenLabs/Deepgram), webhook (external HTTP POST/GET)
CRM (6)
update_contact (name/email/address/status), add_tag (customFields.tags[]), sync_to_crm (HubSpot push), sync_from_crm (HubSpot pull), create_crm_task, update_crm_deal
Calendar (3)
create_calendar_event, update_calendar_event, send_calendar_invite (Google Calendar API)
Internal Ops (3)
create_job (inserts to jobs table), update_job_status (enforces state machine), assign_to_team (team member routing)
Flow Control (2)
wait (duration + unit, supports waitUntil shorthand), condition (field/operator/value with skipCount branching)
Trigger Types (11)
new_lead, job_completed, bid_accepted, quote_sent, appointment_scheduled, contact_stage_changed, manual, schedule, call_connected, call_missed, voice_agent_completed
Template Categories (6)
lead_nurture (5), reviews (2), sales (2), scheduling (2), re_engagement (5), seasonal (5). Sorted by popularity. Tier gating: pro vs pro_unlimited.
Safety Guards
Global kill switch (automationSettings), hourly rate limit (100 runs/contractor), dedup guard (no duplicate running runs per contact), MAX_STEPS_PER_RUN=20, MAX_RETRIES=3, RETRY_BASE_DELAY_MS=500, OCC serialization for race conditions.
