Welcome to the Cosmo backend developer documentation. This documentation provides comprehensive information about the backend architecture, modules, and implementation details.

What is Cosmo?

Cosmo is a conversational AI platform that enables businesses to automate customer interactions through intelligent chat experiences. The platform provides a comprehensive suite of capabilities designed to enhance customer engagement and streamline business operations through conversational interfaces.

Core Capabilities

Customer Interaction & Support: - Question Answering: Intelligent responses to customer inquiries using AI-powered natural language processing - Support Ticket Management: Automated creation, tracking, and management of customer support requests - Product Discovery: Intelligent product search and recommendations based on customer queries

E-commerce Integration: - Order Placement: Seamless order processing from conversation to purchase - Store Integration: Deep integration with e-commerce platforms for real-time product information - Checkout Flow: Direct integration from chat interface to payment processing

Account Management: - Client Onboarding: Automated setup and configuration of business WhatsApp accounts - Account Management: Comprehensive management tools for client WhatsApp business accounts

Technology Stack

Core Infrastructure

• Database: PostgreSQL for primary data storage and relational data management
• Queue System: Redis for caching, session management, and message queuing
• Background Processing: SAQ (Simple Async Queue) for handling background tasks and job processing
• Web Framework: FastAPI for high-performance REST API services
• Frontend: Next.js for the web application interface

External Integrations

• File Storage: Supabase for secure file storage and management
• Messaging Platform: Twilio API for WhatsApp business messaging integration
• Social Media: Meta APIs for Instagram integration and additional WhatsApp functionality
• E-commerce: Shopify API for store integration, product synchronization, and checkout processing

Architecture Overview

Service Architecture

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Frontend      │    │   Web Service   │    │  Background     │
│   (Next.js)     │◄──►│   (FastAPI)     │◄──►│  Service (SAQ)  │
└─────────────────┘    └─────────────────┘    └─────────────────┘
                              │                        │
                              ▼                        ▼
                       ┌─────────────────┐    ┌─────────────────┐
                       │   PostgreSQL    │    │     Redis       │
                       │   (Database)    │    │   (Queue/Cache) │
                       └─────────────────┘    └─────────────────┘

Integration Layer

The platform integrates with multiple external services to provide comprehensive functionality:

• Twilio: Primary WhatsApp API integration for business messaging
• Meta: Instagram API and additional WhatsApp business features
• Shopify: E-commerce platform integration for product data and checkout flows
• Supabase: Cloud storage for media files, documents, and assets

Data Flow

1. Customer Interactions flow through WhatsApp/Instagram → Twilio/Meta APIs → Cosmo Backend
2. AI Processing handles natural language understanding and response generation
3. Business Logic processes requests, manages state, and coordinates with external services
4. Background Tasks handle long-running operations like order processing and account setup

Modules Overview

• API: REST API endpoints and services for all platform functionality
• Clients: External service client implementations for third-party integrations
• Core: Core functionality, utilities, and shared components
• Dataflow: Data processing pipelines and transformation components
• Merchant: Merchant account management and business logic
• ML: Machine learning models and AI services for conversation handling
• Process IO: Input/output processing utilities for message handling
• SAQ: Background job processing and queue management

Getting Started

Navigate through the modules using the sidebar to explore the documentation for each component. Each module provides detailed information about:

• Code Flows: How different parts of the system work together
• Models & Constants: Data structures and configuration values
• Service Functions: Business logic and processing functions
• API Routes: HTTP endpoints and their functionality
• Schemas: Data validation and serialization models

For new developers, we recommend starting with the API module to understand the core endpoints, then exploring the Core module for fundamental utilities and shared functionality.