Skip to main content

Catalyst Backend Documentation

Overview​

The Catalyst backend is built with Python FastAPI and provides a robust, scalable API for the web application. It handles data processing, integrations, user management, and business logic.

Architecture​

Technology Stack​

  • Framework: FastAPI (Python 3.8+)
  • Database: PostgreSQL with SQLAlchemy ORM
  • Authentication: JWT tokens with role-based access control
  • API Documentation: Auto-generated OpenAPI/Swagger docs
  • Background Tasks: Async processing for heavy operations

Project Structure​

backend/
├── api/                    # API endpoints and routing
│   └── api_v1/            # Version 1 API routes
├── crud/                  # Database operations (Create, Read, Update, Delete)
├── models/                # Database models and schemas
├── schemas/               # Pydantic models for data validation
├── services/              # Business logic and external integrations
├── utils/                 # Helper functions and utilities
├── db/                    # Database configuration and migrations
└── setting/               # Configuration and constants

Core API Endpoints​

Authentication & Users 🔐​

User Management​

  • POST /api/v1/auth/login - User login
  • POST /api/v1/auth/register - User registration
  • GET /api/v1/users/me - Get current user profile
  • PUT /api/v1/users/me - Update user profile

Client Management​

  • GET /api/v1/clients - List user's clients
  • POST /api/v1/clients - Create new client
  • PUT /api/v1/clients/{client_id} - Update client
  • GET /api/v1/clients/{client_id}/role - Get user role for client

Task Management 📋​

Task Operations​

  • GET /api/v1/tasks - List tasks (with filtering)
  • POST /api/v1/tasks - Create new task
  • PATCH /api/v1/tasks/{task_id} - Update task
  • DELETE /api/v1/tasks/{task_id} - Delete task
  • POST /api/v1/tasks/{task_id}/complete - Mark task as complete
  • POST /api/v1/tasks/{task_id}/cancel - Cancel task

Task Comments​

  • GET /api/v1/tasks/{task_id}/comments - Get task comments
  • POST /api/v1/tasks/{task_id}/comments - Add comment
  • PATCH /api/v1/tasks/comments/{comment_id} - Update comment
  • DELETE /api/v1/tasks/comments/{comment_id} - Delete comment

Alert System ⚡​

Alert Management​

  • GET /api/v1/alerts - List alerts
  • POST /api/v1/alerts - Create alert
  • PUT /api/v1/alerts/{alert_id} - Update alert
  • DELETE /api/v1/alerts/{alert_id} - Delete alert
  • POST /api/v1/alerts/{alert_id}/trigger - Manually trigger alert

Alert Instances (Notifications)​

  • GET /api/v1/alerts/instances - List alert notifications
  • PUT /api/v1/alerts/instances/{instance_id}/resolve - Resolve notification
  • PUT /api/v1/alerts/instances/{instance_id}/dismiss - Dismiss notification

Lead Scoring 🎯​

Lead Scoring Operations​

  • GET /api/v1/leadscoring/results - Get lead scoring results
  • POST /api/v1/leadscoring/score - Score new leads
  • GET /api/v1/leadscoring/config - Get scoring configuration
  • PUT /api/v1/leadscoring/config - Update scoring rules

Integrations 🔌​

Platform Integrations​

  • GET /api/v1/integrations - List available integrations
  • POST /api/v1/integrations/{platform} - Connect platform
  • GET /api/v1/integrations/{platform}/status - Check connection status
  • DELETE /api/v1/integrations/{platform} - Disconnect platform

Data Synchronization​

  • POST /api/v1/integrations/{platform}/sync - Trigger data sync
  • GET /api/v1/integrations/{platform}/data - Get synced data

Reports & Analytics 📊​

Report Generation​

  • GET /api/v1/reports/growth - Growth reports
  • GET /api/v1/reports/performance - Performance analytics
  • GET /api/v1/reports/leads - Lead analysis reports
  • POST /api/v1/reports/custom - Generate custom reports

Creative Management 🎨​

Creative Assets​

  • GET /api/v1/creative-submissions - List creative submissions
  • POST /api/v1/creative-submissions - Submit new creative
  • PUT /api/v1/creative-submissions/{id} - Update creative
  • POST /api/v1/creative-submissions/{id}/approve - Approve creative
  • POST /api/v1/creative-submissions/{id}/reject - Reject creative

Database Models​

Core Models​

User Model​

class User(Base):
    id: UUID (Primary Key)
    email: String (Unique)
    name: String
    role: String (user, admin, super_admin)
    is_active: Boolean
    created_at: DateTime
    updated_at: DateTime

Client Model​

class Client(Base):
    id: UUID (Primary Key)
    name: String
    logo: String (Optional)
    is_active: Boolean
    lead_scoring_config: JSONB
    created_at: DateTime
    created_by: UUID (Foreign Key)

Task Model​

class Task(Base):
    id: UUID (Primary Key)
    name: String
    task_type: String (review_creative, review_report, other)
    status: String (pending, in_progress, completed, cancelled)
    priority: String (Backlog, Low, Medium, High)
    client_id: UUID (Foreign Key)
    created_by: UUID (Foreign Key)
    assignees: JSONB (Array of user IDs)
    due_date: DateTime (Optional)
    description: String (Optional)
    related_object_id: UUID (Optional)
    related_object_type: String (Optional)

Alert Model​

class Alert(Base):
    id: UUID (Primary Key)
    client_id: UUID (Foreign Key)
    name: String
    description: String (Optional)
    alert_type: String (cplpv, eroas, etc.)
    condition_config: JSONB
    action_config: JSONB
    data_source: String
    frequency: JSONB
    is_active: Boolean
    is_default: Boolean
    created_at: DateTime

Supporting Models​

UserClient (Many-to-Many)​

  • Links users to clients with specific roles
  • Supports role-based permissions per client

TaskComment​

  • Comments on tasks for collaboration
  • Includes user attribution and timestamps

AlertInstance​

  • Logs when alerts are triggered
  • Tracks resolution status and actions taken

Business Logic Services​

Lead Scoring Service​

  • Purpose: Automatically score leads based on configurable rules
  • Key Features:
    • Multiple scoring algorithms (logistic regression, rule-based)
    • Configurable weights and thresholds
    • Real-time scoring for new leads
    • Historical performance tracking

Alert Monitoring Service​

  • Purpose: Monitor marketing metrics and trigger alerts
  • Key Features:
    • Configurable alert conditions
    • Automated task creation
    • Email/Slack notifications
    • Escalation workflows

Integration Services​

  • Purpose: Connect with external marketing platforms
  • Supported Platforms:
    • Facebook Ads API
    • Google Ads API
    • TikTok Ads API
    • HubSpot CRM
    • Stripe Payments
    • Shopify
    • And 10+ more platforms

Task Management Service​

  • Purpose: Handle task lifecycle and team collaboration
  • Key Features:
    • Automatic task creation from alerts
    • Assignment and notification system
    • Progress tracking and reporting
    • Integration with creative review workflows

Security & Authentication​

Authentication Flow​

  1. User logs in with email/password or Google OAuth
  2. Server validates credentials and generates JWT token
  3. Token includes user ID, role, and expiration time
  4. All subsequent requests include token in Authorization header

Role-Based Access Control​

  • Super Admin: Full system access, can manage all clients
  • Admin: Full access within their client scope
  • Member: Limited access to assigned tasks and data
  • Viewer: Read-only access to dashboards

Data Security​

  • All API endpoints require authentication
  • Sensitive data encrypted in database
  • API rate limiting to prevent abuse
  • CORS configured for frontend domains only

API Response Format​

Success Response​

{
  "status_code": 200,
  "message": "Success",
  "data": {
    // Response data here
  }
}

Error Response​

{
  "status_code": 400,
  "message": "Error description",
  "detail": "Additional error details"
}

Configuration​

Environment Variables​

  • DATABASE_URL: PostgreSQL connection string
  • SECRET_KEY: JWT signing key
  • GOOGLE_CLIENT_ID: Google OAuth client ID
  • FACEBOOK_APP_ID: Facebook API credentials
  • OPENAI_API_KEY: OpenAI API key for AI features
  • SENDGRID_API_KEY: Email service credentials

Database Configuration​

  • PostgreSQL 12+ with async support
  • Connection pooling for performance
  • Automated migrations for schema changes
  • Backup and recovery procedures

Performance & Scalability​

Database Optimization​

  • Proper indexing on frequently queried columns
  • Query optimization and caching
  • Connection pooling
  • Read replicas for heavy analytics queries

API Performance​

  • Async/await for non-blocking operations
  • Response caching for static data
  • Pagination for large datasets
  • Background task processing

Monitoring & Logging​

  • Request/response logging
  • Performance metrics tracking
  • Error monitoring and alerting
  • Database query performance monitoring

Development & Deployment​

Local Development​

# Install dependencies
pip install -r requirements.txt

# Set up environment variables
cp .env.example .env

# Run database migrations
alembic upgrade head

# Start development server
uvicorn main:app --reload

Production Deployment​

  • Docker containerization
  • Cloud Run deployment
  • Environment-specific configurations
  • Automated CI/CD pipeline
  • Health checks and monitoring

Testing​

Test Coverage​

  • Unit tests for business logic
  • Integration tests for API endpoints
  • Database transaction tests
  • Authentication and authorization tests

Test Commands​

# Run all tests
pytest

# Run with coverage
pytest --cov=.

# Run specific test file
pytest tests/test_tasks.py

API Documentation​

Interactive Documentation​

  • Swagger UI available at /docs (development only)
  • ReDoc available at /redoc (development only)
  • OpenAPI schema at /openapi.json

Code Examples​

Create a Task​

import requests

response = requests.post(
    "https://api.catalyst.surf/api/v1/tasks",
    headers={"Authorization": "Bearer YOUR_TOKEN"},
    json={
        "name": "Review Facebook Ad Creative",
        "task_type": "review_creative",
        "priority": "High",
        "assignees": ["user-id-1", "user-id-2"],
        "due_date": "2024-01-15",
        "description": "Review the new Facebook ad creative for Q1 campaign"
    }
)

Get Lead Scoring Results​

response = requests.get(
    "https://api.catalyst.surf/api/v1/leadscoring/results",
    headers={"Authorization": "Bearer YOUR_TOKEN"},
    params={
        "client_id": "client-uuid",
        "limit": 100,
        "min_score": 0.7
    }
)

This documentation covers the core backend functionality. For specific implementation details, refer to the source code and inline comments.