gabbi-law-voice-nexus-dev

Fastify Routes

The Fastify backend (running on Railway) manages webhooks and routes. Filter endpoints using the box below. For detailed backend routing and relay logic documentation, see the railway-backend-index-FIXED developer document.

Helper Logic

Key internal functions running inside railway-backend-index-FIXED.js:

Supabase Tables

Standard Postgres relational tables configured inside Supabase. Use the search filter below to browse the schema:

pgvector Matching Function

Cosine similarity matching for the RAG search pipeline is handled via a Postgres database function:

CopyCREATE OR REPLACE FUNCTION match_knowledge_base_items(
  query_embedding vector(1536),
  match_knowledge_base_id uuid,
  match_threshold float DEFAULT 0.3,
  match_count int DEFAULT 5
) RETURNS TABLE (
  id uuid,
  title text,
  content text,
  type text,
  similarity float
) LANGUAGE plpgsql AS $$
BEGIN
  RETURN QUERY
  SELECT
    kbi.id,
    kbi.title,
    kbi.content,
    kbi.type,
    1 - (kbi.embedding <=> query_embedding) AS similarity
  FROM knowledge_base_items kbi
  WHERE kbi.knowledge_base_id = match_knowledge_base_id
    AND 1 - (kbi.embedding <=> query_embedding) > match_threshold
  ORDER BY kbi.embedding <=> query_embedding
  LIMIT match_count;
END;
$$;

Edge Modules

Categorized layout of core Deno Edge Functions deployed on Supabase:

• RAG Processing: generate-knowledge-embedding creates vectors using text-embedding-3-small; semantic-knowledge-search handles similarity inquiries.
• CRM Hooks: push-lead-to-cms pushes data to Clio or Lawmatics; process-cms-push-queue processes queued tasks.
• Outreach Automation: trigger-chase-protocol schedules SMS templates; execute-scheduled-actions manages messaging timeouts.
• Telephony: twilio-webhook handles incoming calls; make-outbound-call starts outbound calls.

React Architecture

The client side uses React, Vite, and TypeScript. Structure overview:

• Page Router (`App.tsx`): Integrates React Router DOM, managing authentication states, layouts, and redirects.
• State Contexts (`src/contexts`): Provides global hooks for authentication, Supabase client sessions, and active organizations.
• UI Components (`src/components/ui`): Reusable UI primitives styled with Vanilla CSS and Tailwind CSS classes.

Dashboard Pages

Primary configuration views within the web client:

Env Variables

Required environment configuration settings in your local .env file:

Local Installation

Steps to run the client and backend servers locally:

1. Install packages for the workspace dependencies:

   Copynpm install

2. Create environment config: Copy and populate the values in your local .env file.
3. Run the Fastify server:

   Copynode railway-backend-index-FIXED.js

4. Run the Vite frontend:

   Copynpm run dev

5. Expose your local port to Twilio for incoming webhook routing:

   Copyngrok http 3000

Code Snippets

Example: Querying semantic knowledge from the RAG search endpoint

Copyasync function performVectorSearch(supabaseUrl, anonKey, kbId, query) {
  const endpoint = `${supabaseUrl}/functions/v1/semantic-knowledge-search`;
  const response = await fetch(endpoint, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${anonKey}`
    },
    body: JSON.stringify({
      knowledge_base_id: kbId,
      query: query,
      top_k: 3,
      similarity_threshold: 0.3
    })
  });
  
  const result = await response.json();
  if (result.success) {
    return result.results;
  }
  throw new Error(result.error);
}

Dependencies

Core dependencies mapped by their operational scope:

• Voice Stream Relays: ws (OpenAI realtime sockets), twilio (REST SDK).
• Backend Framework: fastify, @fastify/websocket, @fastify/formbody.
• Database Clients: @supabase/supabase-js.
• Frontend Engine: react, typescript, vite, react-router-dom.
• Expression Analytics: @humeai/voice-react (Hume SDK connection modules).

Best Practices

• PostgREST Null Filtering: When mapping team identifiers in DB helpers, always run a null check filter: .filter(id => !!id) prior to querying integrations with .in("user_id", ...) to prevent query parser crashes.
• Vector Cosine Thresholds: Maintain RAG similarity limits around 0.3 in matching queries. This prevents empty results while filtering out irrelevant contexts.
• Non-blocking Sockets: Defer database writes, OpenAI post-call transcriptions, and CRM queue pushes to asynchronous promises. Do not block active VoIP audio packages.
• Interruption Control: When a user starts speaking during AI output, immediately clear the Twilio audio output buffers and send a truncate command to the OpenAI realtime socket.