Business logic

This module documents what the product does and why. Where a rule has a non-obvious reason — a guard that exists because of a race condition, a cap that exists because of a provider limit — that reason is recorded alongside the rule.

Capability map

flowchart TB
  subgraph Acquire["Acquire"]
    Sellers["Sellers\n(SmartScout / manual)"]
    Contacts["Contacts"]
    Registries["Phone & email registries"]
  end

  subgraph Engage["Engage"]
    CallCamp["Call campaigns"]
    EmailCamp["Email campaigns"]
    Sequences["Nurture sequences"]
  end

  subgraph Understand["Understand"]
    Analysis["LLM call analysis"]
    Inbox["Email inbox & reply categorisation"]
    Reports["Reports"]
  end

  subgraph Handoff["Hand off"]
    Tasks["Follow-up tasks"]
    CRM["HubSpot / CRM queue"]
  end

  Sellers --> Contacts --> Registries
  Registries --> CallCamp
  Registries --> EmailCamp
  Contacts --> Sequences
  CallCamp --> Analysis
  EmailCamp --> Inbox
  Analysis --> Reports
  Inbox --> Reports
  Analysis --> CRM
  Sequences --> Tasks --> CRM

The invariants that matter most

Never contact a suppressed endpoint: A phone number is undialable if its TargetPhoneNumbers row is blocked or deleted, or its riskLevel is medium or worse. An email address is unsendable if its TargetEmails row has newsletterOptOut, marketingOptOut or isBlocked. Both checks happen twice — once when the broadcaster leases work, once inside the workflow — because the lease and the send are minutes apart. See Registries.
Never dial the same number twice at once: Enforced in four independent places: the pg_cron broadcaster’s Redis in-flight ceiling, the database lease on CampaignTarget.leaseExpiresAt, an Inngest rateLimit of 2 runs per targetPhoneNumber per 24 h on callTarget, and a "first call today" guard on the double tap. See Target lifecycle.
Never send the same email twice: Enforced by queuedAt locking in the broadcaster and by the emailSend workflow’s first step, which refuses any target that has already left pending. See Email campaigns.
Respect the recipient’s clock: Call windows are evaluated in the target’s timezone, derived from the number’s area code. See Call windows.
Every LLM verdict is attributable: CallAiAgentAnalysisResult is unique on (callId, aiAgentId, aiAgentVersionId), so a score can always be traced to the exact prompt version that produced it. See Call analysis.
Caps are enforced at every level that has one: Per variation per hour, per email account per day, per parent domain per day, per campaign per day. All four are checked before a send. See Email deliverability.

Reading order

For the dialer: Call campaigns → Target lifecycle → Call analysis → Phone numbers.

For email: Email campaigns → Email deliverability → Email inbox and replies.

For nurture: Contacts, sellers and registries → Nurture sequences → Sales reps and follow-up tasks.