Frontend Development (React)

Relevant source files

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

• src/App.tsx
• src/LandingPage.tsx
• src/components/SlackSettings.tsx
• package.json
• index.html
• convex/http.ts
• src/components/TermsPage.tsx
• src/components/PrivacyPage.tsx

The TalkCRM frontend is a single-page application (SPA) built with React and TypeScript, using Vite as the build tool. Its primary purpose is to provide a user-facing interface for authentication, displaying installation instructions for Salesforce, and managing integrations like Slack. The application is designed to be lightweight, with a simple custom routing mechanism and a clear separation between public-facing content and authenticated user views.

The frontend communicates with a Convex backend for dynamic features, particularly for managing Slack settings. Authentication is handled externally via WorkOS AuthKit. The UI is styled using Tailwind CSS, with animations powered by Framer Motion and icons from Lucide React.

Sources: src/App.tsx, package.json, PROJECT_DESCRIPTION.md

Project Setup and Dependencies

The project is configured as a standard Vite + React + TypeScript application. Development and build processes are managed through npm scripts defined in package.json.

Sources: package.json

Key Scripts

Script	Description
dev	Runs the frontend (Vite) and backend (Convex) servers in parallel.
dev:frontend	Starts the Vite development server with hot-reloading.
dev:backend	Starts the Convex development server.
build	Type-checks with tsc and builds the application for production using Vite.
lint	Runs the linter to enforce code quality.

Sources: package.json:5-11

Core Dependencies

The following table lists the essential libraries used in the frontend application.

Library	Version	Description
react	^19.2.1	The core library for building the user interface.
vite	^7.2.6	The build tool and development server.
convex	^1.31.2	The client library for interacting with the Convex backend.
@workos-inc/authkit-react	^0.14.0	Handles user authentication via WorkOS.
tailwindcss	^4.1.17	A utility-first CSS framework for styling.
framer-motion	^12.23.26	Powers animations, primarily on the landing page.
lucide-react	^0.562.0	Provides a library of SVG icons.

Sources: package.json:14-22

Application Entry Point and Structure

The application's entry point is index.html, which contains the root div (<div id="root"></div>) where the React application is mounted. This file is also heavily optimized for SEO, containing extensive metadata and structured data (JSON-LD) for search engines.

The React application itself is initialized in src/main.tsx, which is not present in the provided files but is referenced in index.html. The root component, App, is wrapped with necessary context providers, such as the AuthKitProvider for authentication.

Sources: index.html:148, index.html:10-146

Routing and Navigation

The application employs a simple, custom-built router implemented in the useSimpleRouter hook within src/App.tsx. This hook utilizes the browser's native History API (window.location.pathname and window.history.pushState) to manage navigation without a full-page reload.

Sources: src/App.tsx:9-22

useSimpleRouter Hook

// src/App.tsx:9-22
function useSimpleRouter() {
  const [path, setPath] = useState(window.location.pathname);

  useEffect(() => {
    const handlePopState = () => setPath(window.location.pathname);
    window.addEventListener("popstate", handlePopState);
    return () => window.removeEventListener("popstate", handlePopState);
  }, []);

  const navigate = (newPath: string) => {
    window.history.pushState({}, "", newPath);
    setPath(newPath);
  };

  return { path, navigate };
}

Component Rendering Flow

The App component uses the path from useSimpleRouter and the user object from useAuth to conditionally render different page components.

The diagram below illustrates the main routing and component rendering logic.

Authentication Flow

Authentication is managed by the WorkOS AuthKit, integrated via the @workos-inc/authkit-react package. The useAuth hook provides the user's authentication state (isLoading, user) and a signOut function.

The flow is as follows:

1. An unauthenticated user lands on the LandingPage.
2. Clicking "Log in" or "Get started" sets a local state showAuth to true.
3. This triggers the rendering of the LoginPage component, which wraps the WorkOS authentication UI.
4. Upon successful authentication, WorkOS redirects the user to the /callback path.
5. A useEffect hook in App.tsx detects the /callback path and the presence of the user object, then performs a hard redirect to the root path (/).
6. With a user object now present, the InstallationPage is rendered, displaying content for authenticated users.

The following sequence diagram shows the authentication process.

Core Components

The frontend is structured around several key components.

Component	File	Description
App	src/App.tsx	The root component that manages routing and authentication state.
LandingPage	src/LandingPage.tsx	The public-facing page for unauthenticated users. Features marketing content and animations.
LoginPage	src/components/LoginPage.tsx	A wrapper component for the WorkOS AuthKit UI.
InstallationPage	src/App.tsx	The main view for authenticated users, providing Salesforce package installation steps and integrating other settings components.
SlackSettings	src/components/SlackSettings.tsx	A component for connecting and configuring Slack notifications. Interacts with the Convex backend.
TermsPage	src/components/TermsPage.tsx	A static page displaying the Terms of Service.
PrivacyPage	src/components/PrivacyPage.tsx	A static page displaying the Privacy Policy.

Sources: src/App.tsx, src/LandingPage.tsx, src/components/SlackSettings.tsx, src/components/TermsPage.tsx, src/components/PrivacyPage.tsx

SlackSettings Component

This component is a good example of frontend-backend interaction. It allows an authenticated user to connect their Slack workspace to receive CRM notifications.

Data Flow

The component fetches its initial state from the backend and sends updates via POST requests.

Backend API Endpoints

The SlackSettings component interacts with several API endpoints hosted on the Convex backend. The base URL is retrieved from the VITE_CONVEX_SITE_URL environment variable.

Method	Endpoint	Purpose
GET	/api/slack/status	Checks if the user's account is connected to a Slack workspace.
GET	/api/slack/channels	Fetches a list of available Slack channels and current notification mappings.
POST	/api/slack/channels	Sets or removes a channel mapping for a specific notification purpose.
GET	/api/slack/install	Initiates the Slack OAuth installation flow.
POST	/api/slack/disconnect	Disconnects the user's Slack integration.

Sources: src/components/SlackSettings.tsx:100-111, src/components/SlackSettings.tsx:114-125, src/components/SlackSettings.tsx:169-186, src/components/SlackSettings.tsx:135-144, src/components/SlackSettings.tsx:147-166