Architecture Overview

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• src/App.tsx
• convex/ai.ts
• PROJECT_DESCRIPTION.md
• agent_configs/SIMPLE-Co-Sales-Agent.json
• index.html
• convex/slackBlocks.ts

TalkCRM is a voice-first AI assistant designed to allow sales representatives to interact with their Salesforce CRM hands-free. The architecture is built around a core principle of using a voice interface to drive CRM operations, orchestrated by a serverless backend that leverages a powerful AI model for natural language understanding and Salesforce API interaction. The system is designed to be real-time, responsive, and deeply integrated with the user's specific Salesforce organization.

The primary components include a voice interface powered by Twilio and ElevenLabs, a serverless backend using Convex, a frontend dashboard built with React, and an AI "brain" using Anthropic's Claude. This document provides a detailed breakdown of these components and their interactions.

Sources: README.md, PROJECT_DESCRIPTION.md

Core Components & Tech Stack

The system is composed of several key technologies working in concert. The main components are responsible for voice connectivity, backend logic, AI processing, CRM integration, and user interface.

Sources: README.md:28-36, src/App.tsx:392-410, PROJECT_DESCRIPTION.md:38-45

The following diagram illustrates the primary technologies used in the TalkCRM stack.

Component	Technology	Purpose
Voice AI	ElevenLabs Conversational AI	Provides the natural language voice agent that interacts with the user.
Backend	Convex	Serves as the serverless backend, handling real-time database, HTTP actions for webhooks, and server-side functions.
CRM	Salesforce	The source of truth for all customer data; interacted with via its REST API.
Phone	Twilio	Provides the phone number and voice connectivity, connecting the user's call to the ElevenLabs agent.
AI Brain	Claude (Anthropic)	Interprets the user's natural language requests and determines the appropriate Salesforce operations to perform.
Frontend	React + Vite	Powers the web dashboard for installation, configuration, and viewing real-time activity.
Auth	WorkOS	Handles user authentication for the web dashboard.
Styling	Tailwind CSS	Used for styling the UI components in the React frontend.

Sources: README.md:28-36, src/App.tsx:3-8,409, PROJECT_DESCRIPTION.md:38-45

High-Level Architecture Flow

The architecture is designed to process a sales representative's voice command, translate it into a Salesforce action, execute it, and provide a spoken response. The flow involves multiple services, with Convex acting as the central orchestrator.

The diagram below shows the end-to-end flow from a user's voice command to the final CRM update and response.

Call Flow Explained

1. A sales representative calls the dedicated TalkCRM phone number provided by Twilio.
2. Twilio establishes a WebSocket connection to an ElevenLabs Conversational AI agent.
3. The user speaks a command, such as "Update the Acme deal to Closed Won".
4. The ElevenLabs agent, using its configured tools, makes a webhook call to a Convex HTTP endpoint (/tools/assistant).
5. The Convex HTTP action receives the natural language message and triggers the askSalesforce action.
6. The askSalesforce action in convex/ai.ts constructs a prompt including the user's message and Salesforce schema context, then sends it to the Claude AI model.
7. Claude interprets the request and returns a structured JSON object defining the intent (e.g., action: "update", objectType: "Opportunity").
8. The Convex backend executes the corresponding Salesforce action (e.g., updateRecord) using its Salesforce API wrapper.
9. The wrapper makes a secure REST API call to the Salesforce platform.
10. Salesforce processes the request and returns the result.
11. The result is propagated back through the Convex action.
12. The response is sent back to the ElevenLabs agent, which speaks the result to the user.
13. Simultaneously, the Convex backend can push real-time updates to the React dashboard.

Sources: README.md:39-45, PROJECT_DESCRIPTION.md:51-60, convex/ai.ts:100-111

Backend Architecture (Convex)

Convex is the backbone of TalkCRM, handling all server-side logic, data persistence, and external API orchestration.

Sources: PROJECT_DESCRIPTION.md:47-50

AI Orchestration with askSalesforce

The core of the AI logic resides in the askSalesforce action within convex/ai.ts. This function is responsible for taking a user's natural language message and converting it into an executable Salesforce operation.

This sequence diagram details the internal logic of the askSalesforce action.

Key Steps:

1. Fetch Org Metadata: The action first queries the Convex database using internal.orgMetadata.getAvailableObjects to retrieve the user's specific Salesforce custom objects and fields. This ensures the AI is aware of the org's unique schema.
2. Construct Prompt: It combines the standard Salesforce schema, the custom object context, and the conversation history into a system prompt for Claude.
3. Interpret Intent: The interpretWithClaude function sends the prompt to the Anthropic API. Claude returns a ParsedIntent JSON object containing the action to perform (query, update, etc.), target object, fields, and a user-facing response.
4. Execute Action: A switch statement routes the parsed intent to the appropriate Convex action that wraps the Salesforce API, such as api.salesforce.searchRecords or api.salesforce.updateRecord.
5. Return Response: The result from the Salesforce action is formatted into a human-readable string and returned, often with a suggested follow-up action.

Sources: convex/ai.ts:114-290, PROJECT_DESCRIPTION.md:68-91

Salesforce Schema Context

To enable the AI to generate accurate SOQL queries and understand custom fields, it is provided with a rich context about the Salesforce organization's schema. This context is dynamically loaded for each user.

This diagram shows how both standard and custom object schemas are combined to form the full context for the AI.
Sources: convex/ai.ts:10-98, 114-178, README.md:69-82

The system syncs metadata including:

• Custom object names, labels, and descriptions.
• Key fields for each object, including name, type, and picklist values.
• Relationship names for traversing lookups in SOQL.
• Record counts to give the AI a sense of data volume.

Sources: README.md:84-92, convex/ai.ts:120-178

Frontend Architecture

The frontend is a single-page application (SPA) built with React and Vite, styled with Tailwind CSS. It serves as the user-facing web interface for onboarding, installation, and settings.

Sources: src/App.tsx, src/LandingPage.tsx

Application Routing and Authentication

The main application component, App.tsx, handles routing and authentication state.

• A custom useSimpleRouter hook manages client-side navigation.
• The @workos-inc/authkit-react library is used for user authentication.
• The application displays different pages based on the user's authentication status and the current URL path:
  • Unauthenticated: LandingPage or LoginPage.
  • Authenticated: InstallationPage which includes Salesforce package installation links and SlackSettings.
  • Legal Pages: TermsPage and PrivacyPage.

This flow is illustrated below:

Key Frontend Components

• App.tsx: The root component that orchestrates the entire application's state and routing.
• LandingPage.tsx: The public-facing marketing page with calls-to-action for login and signup.
• InstallationPage: An authenticated page that guides users through the Salesforce package installation and provides the TalkCRM phone number. It also contains technical details and example commands.
• SlackSettings.tsx: A component within the InstallationPage for managing Slack integration.
• TermsPage.tsx / PrivacyPage.tsx: Static pages for legal information.

Sources: src/App.tsx:1-9, src/LandingPage.tsx

Agent and Tool Configuration

The ElevenLabs voice agent is configured via a JSON file that defines its personality, voice, and available tools.

Agent Configuration

The agent_configs/SIMPLE-Co-Sales-Agent.json file defines the core behavior of the voice assistant.

• prompt: A detailed prompt that instructs the AI on its personality (Adam Anzuoni, founder), tone, goals, and guardrails. It includes specific qualification questions and closing approaches.
• tts: Text-to-Speech settings, including the ElevenLabs voice ID (mHV5m7DLaQM0bIAP6BTK) and parameters like speed and stability.
• asr: Automatic Speech Recognition settings.
• tools: A list of available tools the agent can call. These are API webhooks that connect to the Convex backend.

Sources: agent_configs/SIMPLE-Co-Sales-Agent.json:2-230

Available Tools

The agent has access to a set of tools that map to Convex HTTP actions, which in turn call Salesforce functions.

Tool Name	Description
calcom_create_booking	Create a new booking for an event.
calcom_get_available_slots	Get available time slots for a specific event type.
search_salesforce	Find records like accounts, contacts, and opportunities.
update_record	Modify fields on an existing Salesforce record.
create_record	Create new records such as tasks.
log_call	Log a call activity to a Salesforce record.
get_my_pipeline	View a summary of the user's open opportunities.
get_my_tasks	View the user's open tasks.

Sources: agent_configs/SIMPLE-Co-Sales-Agent.json:165-229, src/App.tsx:413-430, README.md:50-57