Catalyst Frontend Documentation

Overview

The Catalyst frontend is a modern React TypeScript application that provides an intuitive, responsive interface for managing marketing operations, lead scoring, and team collaboration.

Architecture

Technology Stack

• Framework: React 18 with TypeScript
• Routing: Wouter (lightweight router)
• State Management: TanStack Query (React Query) for server state
• UI Components: Custom component library with Radix UI primitives
• Styling: Tailwind CSS with custom design system
• Build Tool: Vite for fast development and building

Project Structure

client/src/
├── components/           # Reusable UI components
│   ├── ui/              # Base UI components (buttons, forms, etc.)
│   └── dashboard/       # Dashboard-specific components
├── pages/               # Page components and routes
├── hooks/               # Custom React hooks
├── helpers/             # Utility functions and helpers
├── shared/              # Shared types and schemas
└── tests/               # Test files

Website Map & Navigation Structure

Complete Site Map

Catalyst Web Application
├── 🔐 Authentication
│   ├── /login - User Login
│   ├── /signup - User Registration
│   ├── /auth/google/callback - Google OAuth Callback
│   ├── /auth/facebook/callback - Facebook OAuth Callback
│   ├── /auth/tiktok/callback - TikTok OAuth Callback
│   └── /invite/accept - Invitation Acceptance
│
├── 🏠 Lead Scoring
│   ├── /lead-scoring - Lead Scoring Performance
│   ├── /lead-scoring-audit - Lead Scoring Audit
│   └── /lead-scoring-settings - Lead Scoring Settings
│
├── 📋 Tasks
│   ├── /task-management - Task Management
│   └── /alerts - Alerts
│
├── 🤖 AI
│   ├── /ai-assistant - Chat
│   └── /facebook-ad-recommendations - Recommendations
│
├── 📊 Sales
│   ├── /sales-recording-audit - Recording Audit
│   ├── /sales-test-cases - Sales Call Test Cases
│   └── /sales-prompt-engineering - Sales Prompt Engineering
│
├── 📢 Marketing
│   ├── /lead-audit - Lead Audit
│   └── /creative-management - Creative Management
│
├── 📦 Product
│   └── /product - Product
│
├── 📊 Data
│   ├── /growth-month - Growth Dashboard
│   ├── /simple-marketing - Simple Marketing Dashboard
│   ├── /channel-month - Channel Dashboard
│   ├── /campaign-month - Campaign Dashboard
│   ├── /adset-month - Ad Set Dashboard
│   └── /ad-month - Ad Dashboard
│
├── 📋 List
│   ├── /recording-audit - Recording Audit
│   ├── /sqls - SQLs
│   ├── /sdr-cancelled - SDR Cancelled
│   └── /sdr-unbooked - SDR Unbooked
│
├── ⚙️ Configuration (Admin Only)
│   ├── /client-onboarding - Onboarding
│   ├── /integrations - Integrations
│   │   ├── /integrations/facebook/:clientId - Facebook Integration
│   │   ├── /integrations/google/:clientId - Google Integration
│   │   ├── /integrations/google-calendar/:clientId - Google Calendar Integration
│   │   ├── /integrations/typeform/:clientId - Typeform Integration
│   │   ├── /integrations/hubspot/:clientId - HubSpot Integration
│   │   ├── /integrations/thrivecart/:clientId - ThriveCart Integration
│   │   ├── /integrations/easypay/:clientId - EasyPay Integration
│   │   ├── /integrations/elective/:clientId - Elective Integration
│   │   ├── /integrations/stripe/:clientId - Stripe Integration
│   │   ├── /integrations/oncehub/:clientId - OnceHub Integration
│   │   ├── /integrations/gohighlevel/:clientId - GoHighLevel Integration
│   │   ├── /integrations/tiktok/:clientId - TikTok Integration
│   │   ├── /integrations/shopify/:clientId - Shopify Integration
│   │   ├── /integrations/whop/:clientId - Whop Integration
│   │   └── /integrations/fathom/:clientId - Fathom Integration
│   └── /user-management - Users
│
├── 🏢 Client Management (Super Admin Only)
│   └── /client-management - Client Management
│
├── 🎧 Sales Call Analysis (Super Admin Only)
│   ├── /manual-test-cases - Manual Test Cases
│   └── /prompt-engineering - Prompt Engineering
│
├── 📄 Static Pages
│   ├── /terms - Terms of Service
│   ├── /privacy - Privacy Policy
│   └── /profile - User Profile
│
└── 🚫 Error Pages
    └── /not-found - 404 Not Found

Navigation Hierarchy

Primary Navigation (Sidebar)

📱 Main Navigation
├── ⚙️ Configuration (Admin/Super Admin)
│   ├── Onboarding
│   ├── Integrations
│   └── Users
├── 📋 Tasks
│   ├── Task Management
│   └── Alerts
├── 🤖 AI
│   ├── Chat
│   └── Recommendations
├── 🎯 Lead Scoring
│   ├── Lead Scoring Performance
│   ├── Lead Scoring Settings
│   └── Lead Scoring Audit
├── 📊 Sales
│   ├── Recording Audit
│   ├── Sales Call Test Cases
│   └── Sales Prompt Engineering
├── 📢 Marketing
│   ├── Lead Audit
│   └── Creative Management
├── 📦 Product
├── 📊 Data
│   ├── Growth Dashboard
│   ├── Simple Marketing Dashboard
│   ├── Channel Dashboard
│   ├── Campaign Dashboard
│   ├── Ad Set Dashboard
│   └── Ad Dashboard
└── 📋 List
    ├── Recording Audit
    ├── SQLs
    ├── SDR Cancelled
    └── SDR Unbooked

Super Admin Additional Navigation

🔧 Super Admin Tools
├── 🎧 Sales Call Analysis
│   ├── Manual Test Cases
│   └── Prompt Engineering
└── 🏢 Client Management

User Flow Diagrams

Authentication Flow

Login Page → Google OAuth → Dashboard
     ↓
Signup Page → Email Verification → Dashboard
     ↓
Invitation Link → Accept Invitation → Dashboard

Main User Journey

Dashboard → Select Client → Choose Feature → Perform Action
     ↓
Task Management → Create/Assign Tasks → Track Progress
     ↓
Alerts → Configure Alerts → Monitor Notifications
     ↓
Lead Scoring → View Performance → Adjust Settings

Admin Workflow

Configuration → Integrations → Connect Platform → Sync Data
     ↓
User Management → Invite Users → Assign Roles
     ↓
Client Onboarding → Setup Client → Configure Settings

Page Access Control

Public Pages (No Authentication Required)

• /login
• /signup
• /terms
• /privacy
• /invite/accept

Authenticated Pages (Requires Login)

• All dashboard pages
• Task management
• Alerts
• Lead scoring
• Creative management
• All data/report pages

Admin-Only Pages (Requires Admin Role)

• /integrations
• /user-management
• /client-onboarding
• /lead-scoring-settings

Super Admin-Only Pages (Requires Super Admin Role)

• /client-management
• /manual-test-cases
• /prompt-engineering

Mobile Navigation

Mobile Menu Structure

☰ Mobile Menu
├── 🏠 Dashboard
├── 📋 Tasks
├── 🤖 AI
├── 🎯 Lead Scoring
├── 📊 Sales
├── 📢 Marketing
├── 📦 Product
├── 📊 Data
├── 📋 List
└── ⚙️ Settings (if admin)

Breadcrumb Navigation

Example Breadcrumbs

Dashboard > Lead Scoring
Dashboard > Tasks > Task Management
Dashboard > Configuration > Integrations > Facebook
Dashboard > Data > Growth Dashboard
Dashboard > Marketing > Creative Management

Core Pages & Features

Dashboard 🏠

Route: / (default)

Purpose: Central hub for all marketing operations and analytics

Key Features:

• Real-time metrics overview
• Quick access to all features
• Client switching
• Recent activity feed

Components Used:

• Header - Navigation and user controls
• Sidebar - Main navigation menu
• Various dashboard widgets

Task Management 📋

Route: /task-management

Purpose: Manage team tasks, assignments, and workflows

Key Features:

• Task creation and assignment
• Status tracking (pending, in-progress, completed)
• Priority management (Backlog, Low, Medium, High)
• Comment system for collaboration
• Filtering and search capabilities

Components Used:

• TaskTable - Main task listing
• CreateTaskModal - Task creation form
• TaskDetailModal - Task details and editing
• TaskComment - Comment system

Alert System ⚡

Route: /alerts

Purpose: Configure and manage automated alerts for marketing metrics

Key Features:

• Custom alert creation wizard
• Alert configuration and thresholds
• Notification management
• Alert testing and triggering
• Frequency scheduling

Components Used:

• CreateAlertWizard - Multi-step alert creation
• AlertDetail - Alert configuration view
• NotificationDetail - Alert notification details
• AlertSettings - Alert management interface

Lead Scoring 🎯

Route: /lead-scoring

Purpose: View and manage lead scoring performance and configuration

Key Features:

• Lead scoring dashboard
• Performance metrics and trends
• Configuration management
• Score distribution analysis
• Historical data tracking

Creative Management 🎨

Route: /creative-management

Purpose: Manage marketing creative assets and review workflows

Key Features:

• Creative asset upload and storage
• Review and approval workflows
• Asset organization and tagging
• Version control
• Integration with task management

Integrations 🔌

Route: /integrations

Purpose: Connect and manage external platform integrations

Key Features:

• Platform connection status
• OAuth authentication flows
• Data synchronization controls
• Integration health monitoring
• Configuration management

UI Component Library

Base Components

Button Component

interface ButtonProps {
  variant?: 'default' | 'destructive' | 'outline' | 'secondary' | 'ghost' | 'link'
  size?: 'default' | 'sm' | 'lg' | 'icon'
  asChild?: boolean
  children: React.ReactNode
}

Usage Examples:

// Primary button
<Button>Click me</Button>

// Secondary button
<Button variant="outline">Cancel</Button>

// Small button with icon
<Button size="sm" className="bg-green-600">
  <CheckCircle className="w-4 h-4" />
  Complete
</Button>

Card Component

interface CardProps {
  children: React.ReactNode
  className?: string
}

// Sub-components
CardHeader, CardContent, CardTitle, CardDescription

Usage Example:

<Card className="bg-catalyst-800 border-catalyst-700">
  <CardHeader>
    <CardTitle>Task Details</CardTitle>
  </CardHeader>
  <CardContent>
    <p>Task content goes here</p>
  </CardContent>
</Card>

Form Components

• Input - Text input fields
• Select - Dropdown selections
• Checkbox - Checkbox inputs
• Textarea - Multi-line text input
• Label - Form labels

Data Display Components

• Table - Data tables with sorting and filtering
• Badge - Status indicators and labels
• Dialog - Modal dialogs and popups
• Tabs - Tabbed content organization

Dashboard Components

Sidebar Navigation

File: components/dashboard/sidebar.tsx

Features:

• Collapsible navigation sections
• Role-based menu items
• Active state highlighting
• Mobile-responsive design

Props:

interface SidebarProps {
  activeSection: string
  onSectionChange: (section: string) => void
  isOpen?: boolean
  onClose?: () => void
  userRole?: string
  selectedClient?: Client | null
}

Header Component

File: components/dashboard/header.tsx

Features:

• User profile and logout
• Client switching dropdown
• Mobile menu toggle
• Notification indicators

State Management

Server State (TanStack Query)

Used for all API data fetching and caching:

// Example: Fetching tasks
const { data: tasks, isLoading, error } = useQuery({
  queryKey: ["/api/v1/tasks", clientId, filters],
  queryFn: () => apiRequest("GET", `/api/v1/tasks?${params}`),
  enabled: !!clientId,
  staleTime: 5 * 60 * 1000, // 5 minutes
})

Local State (React useState)

Used for UI state and form data:

const [isModalOpen, setIsModalOpen] = useState(false)
const [selectedTask, setSelectedTask] = useState<Task | null>(null)
const [filters, setFilters] = useState({
  status: "all",
  priority: "all",
  assignee: null
})

Authentication State

Custom hook for user authentication:

const { user, logout, isLoading } = useAuth()

Routing & Navigation

Router Setup

Using Wouter for lightweight client-side routing:

import { Switch, Route } from "wouter"

function App() {
  return (
    <Switch>
      <Route path="/login" component={Login} />
      <Route path="/" component={Dashboard} />
      <Route path="/task-management" component={TaskManagement} />
      <Route path="/alerts" component={Alerts} />
      {/* More routes... */}
    </Switch>
  )
}

Protected Routes

Routes are protected based on authentication status:

// Redirect to login if not authenticated
useEffect(() => {
  if (!user) {
    setLocation("/login")
  }
}, [user, setLocation])

API Integration

API Client Setup

Centralized API request handling:

// helpers/queryClient.ts
export const apiRequest = async (method: string, url: string, data?: any) => {
  const response = await fetch(`${API_BASE_URL}${url}`, {
    method,
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${getToken()}`
    },
    body: data ? JSON.stringify(data) : undefined
  })
  
  if (!response.ok) {
    throw new Error(`API Error: ${response.status}`)
  }
  
  return response
}

Error Handling

Global error handling with toast notifications:

const { toast } = useToast()

// In component
try {
  await createTaskMutation.mutateAsync(taskData)
  toast({
    title: "Success",
    description: "Task created successfully!",
  })
} catch (error) {
  toast({
    title: "Error",
    description: error.message || "Failed to create task",
    variant: "destructive",
  })
}

Styling & Design System

Tailwind CSS Configuration

Custom design system with Catalyst branding:

// tailwind.config.ts
module.exports = {
  theme: {
    extend: {
      colors: {
        catalyst: {
          50: '#f8fafc',
          100: '#f1f5f9',
          // ... more color variants
          950: '#0f172a'
        }
      }
    }
  }
}

Component Styling Patterns

Consistent styling approach:

// Dark theme with catalyst colors
<div className="bg-catalyst-900 border-catalyst-700 text-catalyst-50">
  <h2 className="text-catalyst-100 font-semibold">Title</h2>
  <p className="text-catalyst-400">Description</p>
</div>

// Interactive elements
<Button className="bg-blue-600 hover:bg-blue-700 text-white transition-colors">
  Click me
</Button>

Responsive Design

Mobile-First Approach

All components designed mobile-first with responsive breakpoints:

// Mobile: single column, Desktop: two columns
<div className="flex flex-col md:flex-row gap-4">
  <div className="w-full md:w-1/2">Content 1</div>
  <div className="w-full md:w-1/2">Content 2</div>
</div>

Mobile Navigation

Collapsible sidebar with overlay on mobile:

// Mobile overlay
{sidebarOpen && (
  <div 
    className="fixed inset-0 bg-black bg-opacity-50 z-20 md:hidden"
    onClick={() => setSidebarOpen(false)}
  />
)}

Performance Optimization

Code Splitting

Lazy loading for route components:

const TaskManagement = lazy(() => import("@/pages/task-management"))
const Alerts = lazy(() => import("@/pages/alerts"))

Memoization

React.memo for expensive components:

const TaskItem = React.memo(({ task, onUpdate }) => {
  // Component implementation
})

Query Optimization

Efficient data fetching with TanStack Query:

// Stale time prevents unnecessary refetches
const { data } = useQuery({
  queryKey: ["tasks"],
  queryFn: fetchTasks,
  staleTime: 5 * 60 * 1000, // 5 minutes
  cacheTime: 10 * 60 * 1000, // 10 minutes
})

Testing

Test Setup

Using Vitest and React Testing Library:

// tests/setup.ts
import { expect, afterEach } from 'vitest'
import { cleanup } from '@testing-library/react'

afterEach(() => {
  cleanup()
})

Component Testing

Example test for TaskManagement component:

// tests/task-management.test.tsx
import { render, screen } from '@testing-library/react'
import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
import TaskManagement from '@/pages/task-management'

test('renders task management page', () => {
  const queryClient = new QueryClient()
  
  render(
    <QueryClientProvider client={queryClient}>
      <TaskManagement />
    </QueryClientProvider>
  )
  
  expect(screen.getByText('Task Management')).toBeInTheDocument()
})

Development Workflow

Local Development

# Install dependencies
npm install

# Start development server
npm run dev

# Run tests
npm run test

# Build for production
npm run build

Code Quality

• TypeScript for type safety
• ESLint for code linting
• Prettier for code formatting
• Husky for pre-commit hooks

Component Development

1. Create component in appropriate directory
2. Add TypeScript interfaces
3. Implement with Tailwind styling
4. Add to storybook (if applicable)
5. Write tests
6. Update documentation

Browser Support

Supported Browsers

• Chrome 90+
• Firefox 88+
• Safari 14+
• Edge 90+

Progressive Enhancement

• Core functionality works without JavaScript
• Enhanced features with modern browser APIs
• Graceful degradation for older browsers

Accessibility

ARIA Labels

Proper labeling for screen readers:

<Button aria-label="Close modal">
  <X className="w-4 h-4" />
</Button>

Keyboard Navigation

Full keyboard support for all interactive elements:

// Focus management
const handleKeyDown = (e: KeyboardEvent) => {
  if (e.key === 'Escape') {
    onClose()
  }
}

Color Contrast

WCAG AA compliant color combinations throughout the interface.

---

This documentation covers the core frontend functionality. For specific component implementations, refer to the source code and inline comments.