Skip to content

Platform Module

Overview

This repository is a Vite + React + TypeScript application backed by Supabase. The frontend is routed in src/App.tsx, uses TanStack Query for data fetching, Tailwind plus shadcn/Radix for UI, and a large set of Supabase Edge Functions for app workflows.

Frontend Architecture

  • App shell: src/App.tsx
  • Routing covers Leads, Message Center, Broadcasts, Broadcast Analytics, Jobs, Field Sales, Sales Sheet, Reports, Admin, and settings pages
  • Providers include auth, enums, company phones, user profile, assistant state, realtime follow-up updates, and AI review queue state
  • Styling uses Tailwind tokens from tailwind.config.ts with app-specific color groups such as sidebar, navbar, success, warning, danger, and follow-up status colors

Backend Architecture

  • Supabase Postgres remains the main system of record
  • Edge Functions under supabase/functions/ handle search, messaging, campaign operations, jobs, AI workflows, notifications, OCR, and reporting
  • Shared server logic lives in supabase/functions/_shared/
  • Realtime is used for follow-ups and thread-note related UI refresh paths

API Surface In Practice

The old API reference and OpenAPI file were incomplete. The current codebase exposes many function families instead: - Lead and search APIs: lead-read-search, lead-count, lead-filter-options, lead-search, contact-counts - Message Center APIs: thread-search, thread-read, message-read, message-send, message-inbound, thread-call-dial - Broadcast APIs: campaign-create, campaign-update, campaign-search, campaign-metrics, campaign-lead-search, campaign-lead-send - AI/admin APIs: admin-ai-settings, ai-yes-intent-update-from-agent, ai-no-intent-update-from-agent, ai-review-apply-data - Utility/integration APIs: ocr-vision, geocoding-proxy, get-google-maps-key, notification-dispatcher

Development Workflow

  • Install dependencies with npm install
  • Run the app with npm run dev
  • Build with npm run build
  • Lint with npm run lint
  • Vitest and Storybook dependencies are present, and the repo contains table tests/stories, but there is no dedicated npm test script in package.json

Deployment And Operations

  • Frontend build/deploy helper: deploy-code.sh
  • Edge function deploy helper: deploy-functions.sh
  • Migration helper: deploy-migrations.sh
  • Supabase function JWT overrides are configured in supabase/config.toml

Current Constraints And Risks

  • Several legacy scripts and deployment helpers include environment-specific assumptions; treat them as project-local tooling, not generic setup instructions.
  • deploy-migrations.sh is a direct psql runner that archives migrations after execution, so it is operationally different from a pure Supabase CLI workflow.
  • Some Edge Functions intentionally run with verify_jwt = false; these routes rely on webhook validation, bearer tokens, or other app-side controls.

Troubleshooting Focus Areas

  • If the UI is stale or inconsistent, inspect TanStack Query cache behavior before adding more refetches.
  • If messaging/call flows fail, check the relevant Edge Function first, then the external provider integration.
  • If a table feels slow, verify whether the screen should switch to server-side mode or virtualization instead of adding page-local optimizations.
  • If a feature depends on enums or company phones, confirm provider initialization and enum loading rather than debugging downstream UI only.

Repository Reality vs Older Briefs

  • The app is no longer accurately described by the earlier high-level “project brief” docs; the current repo is already organized around concrete modules and workflow-specific Edge Functions.
  • The platform is not purely Twilio or purely PBX; it currently contains both Twilio-based communication paths and PBX integration points.
  • The best source of truth for supported flows is the route tree in src/App.tsx, the shared providers, and the function inventory in supabase/functions/.

Specifications