Real-time Web Dashboard

Relevant source files

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

• src/App.tsx
• src/LandingPage.tsx
• README.md
• PROJECT_DESCRIPTION.md
• convex/http.ts
• convex/analytics.ts
• convex/ai.ts
• index.html

The TalkCRM web application serves as the primary user interface for authentication, installation, and configuration. While the main interaction with the service is voice-based, the web dashboard provides the entry point for users to connect their accounts and manage integrations. The backend is built on Convex, which enables real-time data subscriptions for the dashboard, allowing for live updates as voice interactions occur.

The application is a single-page React application that handles routing and state management internally. It presents different views based on the user's authentication status: a public-facing landing page for new visitors, and a private installation/dashboard page for authenticated users.

Sources: src/App.tsx:1-400, README.md:1-50, PROJECT_DESCRIPTION.md:1-50

Application Architecture

The web dashboard is a React frontend that interacts with a Convex backend. The backend orchestrates calls to external services like ElevenLabs (Voice AI), Claude (AI Brain), and the Salesforce REST API. The Convex backend is designed to push real-time updates to the React dashboard via subscriptions.

Sources: README.md:9-45, PROJECT_DESCRIPTION.md:20-45

High-Level Component Flow

The following diagram illustrates the overall architecture, highlighting the dashboard's role and its real-time connection to the backend.

This diagram shows how both the voice interface (via Twilio/ElevenLabs) and the web dashboard interact with the central Convex backend. The green arrow indicates the real-time data flow to the dashboard.

Sources: README.md:9-45

Frontend Application Flow

The main App.tsx component orchestrates the user experience by managing routing and authentication state. It uses a simple custom hook, useSimpleRouter, to handle client-side navigation.

The flow is as follows:

1. The app checks the authentication status using the useAuth hook from WorkOS.
2. If loading, a loading spinner is displayed.
3. If the user is not authenticated, it shows the LandingPage or LoginPage.
4. If the user is authenticated, it displays the InstallationPage, which acts as the main dashboard.
5. The router also handles specific paths for legal pages like /terms and /privacy.

Sources: src/App.tsx:10-90

This diagram illustrates the conditional rendering logic within App.tsx.

Authentication

User authentication is managed by the @workos-inc/authkit-react library. The App component uses the useAuth hook to get the user's authentication state and profile information.

• Login/Signup: The LandingPage provides onLogin and onSignup buttons which toggle the display of the LoginPage component.
• Callback Handling: After a successful login via WorkOS, the user is redirected to the /callback path. An effect in App.tsx detects this, and once the user object is available, it redirects them to the root path (/).
• Sign Out: The authenticated InstallationPage provides a "Sign out" button that calls the signOut function from the useAuth hook.

Sources: src/App.tsx:28-37, src/App.tsx:85-88, src/App.tsx:116-122

Dashboard Components

Once authenticated, the user is presented with the InstallationPage, which serves as the main dashboard.

Sources: src/App.tsx:89-90

Installation Steps

The primary purpose of the authenticated view is to guide the user through installing the TalkCRM Salesforce package. It provides direct links for both production and sandbox environments.

Step	Description
1	Install the Salesforce Package using provided links.
2	Select "Install for All Users" within Salesforce.
3	Approve Third-Party Access for API permissions.
4	Start using the service by calling the provided phone number.

The installation links point to Salesforce's installPackage.apexp page with the package ID 04tHn000000QBNdIAO.

Sources: src/App.tsx:135-217

Integrations

The dashboard includes a section for managing integrations. The only integration currently visible in the UI is for Slack, handled by the SlackSettings component.

Sources: src/App.tsx:284-294

Technical Details

A collapsible "Technical Details" section provides an overview of the system's architecture and technology stack.

This diagram from the UI illustrates the data flow for a voice command.

Sources: src/App.tsx:334-351

The tech stack is listed as:

• Voice AI: ElevenLabs
• Phone: Twilio
• Backend: Convex
• CRM: Salesforce
• AI: Claude
• Auth: WorkOS

Sources: src/App.tsx:354-383

Real-time Capabilities & Analytics

While the current frontend UI in src/App.tsx is focused on installation, the project's documentation and backend code are built to support a real-time analytics dashboard.

The README.md and PROJECT_DESCRIPTION.md files state that the dashboard receives real-time updates via Convex subscriptions. This allows the frontend to show live agent activity as calls happen.

Sources: README.md:46-47, PROJECT_DESCRIPTION.md:121-124

Backend Analytics Queries

The convex/analytics.ts file defines several queries to pull usage data, which could power a real-time dashboard.

Query	Description
getUserUsage	Retrieves overall usage stats for a user over a specified number of days, including call counts, duration, and tool usage.
getDailyUsage	Provides a daily breakdown of calls and duration for charting.
getToolUsage	Breaks down usage by the specific AI tool called (e.g., search_salesforce).
getTopRecords	Lists the most frequently accessed or modified Salesforce records.
getAdminDashboard	Provides a summary for an admin view, including total users, active users, and call volumes.

Sources: convex/analytics.ts:1-200

Analytics API Endpoints

These queries are exposed via HTTP actions in convex/http.ts, making them available for the frontend to consume.

Method	Path	Handler Query	Description
GET	/api/analytics/stats	api.conversations.getConversationStats	Gets high-level conversation statistics.
GET	/api/analytics/detailed	api.conversations.getConversationAnalytics	Gets detailed analytics for a time period.
GET	/api/conversations	api.conversations.listConversations	Lists conversations with their analytics.
GET	/api/conversation	api.conversations.getConversation	Gets full details for a single conversation.

Sources: convex/http.ts:796-868

Real-time Data Flow Example

This sequence diagram shows the end-to-end flow from a user's voice command to a potential real-time update on the dashboard, based on the project's described architecture.

Conclusion

The TalkCRM web application serves as the user's entry point for setup and configuration. The primary authenticated view, InstallationPage, guides users through connecting Salesforce. Although this view does not currently display real-time data, the underlying architecture, powered by Convex's real-time database and subscriptions, is explicitly designed to support a live dashboard. The backend exposes a rich set of analytics queries and API endpoints, laying the groundwork for future features that could visualize call activity, tool usage, and Salesforce interactions as they happen.

Sources: src/App.tsx, convex/analytics.ts, README.md