Lead System
Technical documentation for the Onsidian lead management system
The lead system is the core of Onsidian. It manages the full lifecycle of a sales prospect — from import or manual creation, through contact attempts and appointments, to a final outcome (sale, no sale, or terminal resolution).
How it works
A lead enters the system and moves through a stage-based state machine. Every action an agent takes — calling, texting, scheduling an appointment, running a presentation — is logged as an activity. Database triggers watch those activities and automatically advance the lead's stage and status. Metrics and daily reports are updated atomically by the same triggers.
System layers
| Layer | What it does |
|---|---|
| Database | PostgreSQL tables, RLS policies, triggers, and RPC functions. All business logic for stage transitions, metric tracking, and atomic operations lives here. |
| Hooks | React hooks (useLead, useLeads) wrap Supabase queries. Components never call the database directly. |
| UI | The leads page, detail panel, and action modals. Stage-aware — buttons and options change based on where the lead is in the workflow. |
| API | Two REST endpoints: bulk import (for lead vendors) and presentation activity logging (from the pop-out presentation window). |
Data flow
Lead created (manual, import, or referral)
→ leads row inserted (stage: new, status: open)
→ lead_metrics row created by trigger
Agent takes action (contact, appointment, presentation, resolve)
→ RPC function called (atomic)
→ lead_activity row(s) inserted
→ Triggers fire:
1. Stage/status updated on leads row
2. lead_metrics counters incremented
3. lead_reports daily row upserted
4. last_activity_at timestamp updated
Presentation completed
→ submit_lead_presentation RPC called
→ Demographics, sale details, referrals all written atomically
→ calendar_events status set to completed
→ sale or no_sale activity logged → triggers advance stage to terminalWhat's company-specific
The current system was built for life insurance sales agencies. Several things are specific to that domain and would need to change for other companies. See Company-Specific Configuration for a full breakdown.