Getting Started

Welcome to the SynapseAI B2B Wholesale Platform documentation! SynapseAI is an AI-powered B2B commerce platform that enables conversational ordering, inventory management, and intelligent campaign creation. This documentation uses FlavorFlux (a fictional adaptive CPG brand) as the demo use case.

What is SynapseAI?

SynapseAI is an intelligent B2B wholesale commerce platform built with LangGraph that provides:

• Conversational AI for natural language ordering
• Predictive inventory management
• Automated campaign generation
• Multi-channel support (web, voice, WhatsApp)

FlavorFlux Demo Brand

FlavorFlux is our fictional demo brand - the first truly adaptive CPG (Consumer Packaged Goods) brand that evolves its product line based on real-time consumer feedback and community co-creation.

The SynapseAI platform leverages:

• LangGraph for conversational AI orchestration
• FastAPI for high-performance backend services
• React/Vite for modern frontend interfaces
• Model Context Protocol (MCP) for external service integrations
• Commercetools for e-commerce operations
• Voucherify for promotions and loyalty programs

Architecture Overview

The platform consists of three main components:

🔧 Backend

FastAPI application with LangGraph AI agent that handles:

• Conversational AI for B2B ordering
• Product search and cart management
• Order processing and history
• Campaign and promotion management
• Real-time session management with Redis

🎨 Frontend

React application with TanStack Router that provides:

• Chat-based ordering interface
• User authentication
• Product browsing and cart management
• Real-time voice chat capabilities
• WhatsApp integration

☁️ Infrastructure

AWS-based deployment using Terraform:

• ECS Fargate for containerized services
• Application Load Balancer for traffic distribution
• ElastiCache for session storage
• ECR for container registry

Quick Start

Prerequisites

Before you begin, ensure you have the following installed:

• Node.js 20.x or higher
• Python 3.11 or higher
• Docker and Docker Compose
• pnpm for frontend package management
• uv for Python package management (optional but recommended)

Environment Setup

1. Clone the repository:

git clone <repository-url>
cd B2B-Wholesale-AI

2. Set up environment variables:

For the backend:

cd backend
cp env.example .env
# Edit .env with your API keys and credentials

For the frontend:

cd frontend
cp .env.example .env
# Edit .env with your configuration

Running the Application Locally

Option 1: Using Docker (Recommended)

Start all services with Docker Compose:

cd backend
docker-compose -f docker-compose.dev.yml up --build -d

This will start:

• Backend API at http://localhost:8001
• Commercetools MCP server
• Voucherify MCP server
• Redis for session storage

Option 2: Running Services Individually

Backend:

cd backend
uv pip install -e .
uvicorn app.main:app --reload --port 8001

Frontend:

cd frontend
pnpm install
pnpm dev

The frontend will be available at http://localhost:5173

Next Steps

• Backend Setup - Detailed backend configuration and development
• Frontend Setup - Frontend development guide
• Architecture - Deep dive into system architecture
• User Scenarios - Understanding user personas and workflows
• Deployment - Infrastructure and deployment guide

Key Features

🤖 Conversational AI

• Natural language product search
• Cart management through chat
• Order placement and tracking
• Product disambiguation and recommendations

📊 Campaign Management

• AI-powered campaign template generation
• Community sentiment analysis
• Smart targeting for retail partners
• Automated promotion creation

📦 Inventory Intelligence

• Predictive reordering based on demand forecasting
• Stockout prevention
• Optimal inventory levels
• Sales pattern analysis

🎯 Human-in-the-Loop (HITL)

• Approval workflows for high-value orders
• Risk mitigation for unusual demand spikes
• Audit trails for compliance
• Notification systems for approvals

API Endpoints

The backend exposes the following main endpoints:

• POST /agent/chat - Main conversational interface
• GET /health - Health check
• POST /auth/login - User authentication
• POST /auth/signup - User registration
• POST /auth/refresh - Token refresh

Support and Resources

• Documentation: This documentation site
• GitHub Repository: [Link to repository]
• Issue Tracker: Report bugs and request features

Project Structure

B2B-Wholesale-AI/
├── backend/          # FastAPI backend with LangGraph
├── frontend/         # React frontend with TanStack Router
├── docs/             # Documentation site (this site)
├── documentation/    # Architecture and design documents
└── terraform/        # Infrastructure as Code for AWS