Skip to main content

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

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)

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​

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.