Local Development Setup

Relevant source files

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

• README.md
• package.json
• convex/http.ts
• src/App.tsx
• convex/ai.ts
• PROJECT_DESCRIPTION.md
• agent_configs/SIMPLE-Co-Sales-Agent.json

This document provides a comprehensive guide to setting up and running the TalkCRM project on a local machine for development purposes. The setup involves running a React frontend, a Convex backend, and configuring several external services that the application depends on, such as ElevenLabs for voice AI and Twilio for telephony.

The local environment is designed to mirror the production architecture, allowing developers to work on the frontend dashboard, backend functions, and AI agent logic in an integrated manner. The primary tools for local development are Node.js, npm, and the Convex CLI.

1. Prerequisites

Before starting, you must have the following accounts and tools set up.

• Node.js: Version 18 or higher.
• Convex Account: To manage the backend, database, and environment variables.
• ElevenLabs Account: Must have access to the Conversational AI feature.
• Twilio Account: A phone number is required for voice connectivity.
• Salesforce Org: A Developer Edition org is sufficient for testing the Salesforce integration.

Sources: README.md:94-99

2. Initial Installation

The first step is to clone the repository and install the required Node.js dependencies.

npm install

This command reads the package.json file and installs all necessary libraries for both the frontend (React, Vite, Tailwind CSS) and backend development (Convex CLI tools).

Sources: README.md:102-104, package.json:12-21

3. Backend Configuration (Convex)

The backend is powered by Convex. To start the local development server, run the following command. This will watch for changes in the convex/ directory and sync them.

npx convex dev

Upon first run, this command will guide you through linking the project to your Convex account.

Sources: README.md:107-109

Environment Variables

TalkCRM requires several environment variables to be set in the Convex dashboard for connecting to external services. These are critical for the application's functionality.

The following diagram illustrates how environment variables are used by the Convex backend to connect to various services.

Set the following variables in your Convex project's dashboard under "Settings" -> "Environment Variables":

Variable	Description	Example Value	Source File
GOOGLE_CLIENT_ID	Google OAuth Client ID for user authentication.	your_google_client_id	README.md:112
GOOGLE_CLIENT_SECRET	Google OAuth Client Secret for user authentication.	your_google_client_secret	README.md:113
AUTH_SECRET	A secret key for session encryption. Generate with openssl rand -base64 32.	your_random_secret_key	README.md:114
CONVEX_SITE_URL	The public URL of your Convex deployment.	https://your-deployment.convex.site	README.md:115
SALESFORCE_ACCESS_TOKEN	Salesforce API access token.	your_token	README.md:118
SALESFORCE_INSTANCE_URL	Your Salesforce organization's instance URL.	https://yourorg.my.salesforce.com	README.md:119
ANTHROPIC_API_KEY	API key for the Anthropic (Claude) AI model.	your_key	README.md:122

Important for Google OAuth: In your Google Cloud Console, you must add an authorized redirect URI pointing to your Convex deployment: https://<your-deployment-name>.convex.site/api/auth/callback/google.

Sources: README.md:111-127

4. Frontend Development

The frontend is a React application built with Vite. To start the frontend development server, use the following command:

npm run dev:frontend

This command starts a hot-reloading server, making the dashboard accessible in your browser, typically at http://localhost:5173.

Sources: package.json:7

Combined Development Script

For convenience, a single command is provided to run both the frontend and backend development servers concurrently.

npm run dev

This script uses npm-run-all to execute dev:frontend and dev:backend in parallel.

Sources: package.json:6

The local development workflow is visualized below.

5. External Service Configuration

ElevenLabs Agent and Tools

The voice agent's behavior is defined in configuration files. To apply changes to your agent, you need to push the configurations to ElevenLabs using their CLI.

1. Push Tool Definitions: The tools the AI can use (e.g., search_salesforce, update_record) are defined in the tool_configs/ directory.

   elevenlabs tools push
   

2. Push Agent Configuration: The agent's personality, prompt, and voice settings are defined in agent_configs/.

   elevenlabs agents push
   

Sources: README.md:129-135, agent_configs/SIMPLE-Co-Sales-Agent.json

Twilio Phone Number

To test voice interactions, you must configure your Twilio phone number's webhook to connect to the ElevenLabs Conversational AI WebSocket. The demo number provided is +1 (646) 600-5041.

The webhook should point to wss://api.elevenlabs.io/v1/convai/conversation and include the agent_id of your pushed agent.

Sources: README.md:137-141, src/App.tsx:249-252

6. Development Scripts

The package.json file contains several scripts to aid in development.

Script	Description
dev	Runs both the frontend (vite) and backend (convex dev) servers in parallel.
dev:frontend	Starts the Vite development server for the React frontend with hot-reloading.
dev:backend	Starts the Convex development server, watching for backend file changes.
predev	A setup script that ensures Convex is running and opens the dashboard before the main dev script.
build	Compiles the TypeScript and builds the frontend application for production using Vite.
lint	Runs TypeScript compiler checks and ESLint to enforce code quality.
preview	Serves the production build locally to preview the final application.

Sources: package.json:5-11

Summary

Setting up the TalkCRM local development environment involves a coordinated effort of running local servers and configuring cloud services. The key steps are installing dependencies, setting up the Convex backend with the correct environment variables, running the frontend server, and ensuring external services like ElevenLabs and Twilio are correctly configured to communicate with the application. The provided npm scripts streamline this process, allowing developers to focus on building features.