Quick Start

Get SynapseAI running in 30 minutes with Docker Compose

Quick Start Guide

Get Synapse AI running locally in about 30 minutes using Docker Compose.

Before You Begin

Ensure you have:

✅ Prerequisites installed
✅ API keys for LLM provider and Commercetools
✅ Docker Desktop running

Step 1: Clone the Repository

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

Step 2: Configure Environment

Create your .env file in the backend directory:

cd backend
cp env.example .env

Edit .env with your API keys:

# Minimum required configuration
LITELLM_MODEL=cerebras/llama-3.3-70b
CEREBRAS_API_KEY=your-cerebras-key

# Commercetools
CT_CLIENT_ID=your-client-id
CT_CLIENT_SECRET=your-secret
CT_PROJECT_KEY=your-project-key
CT_AUTH_URL=https://auth.us-central1.gcp.commercetools.com
CT_API_URL=https://api.us-central1.gcp.commercetools.com
CT_SCOPES=manage_products manage_orders

# Voucherify
VOUCHERIFY_APP_ID=your-app-id
VOUCHERIFY_APP_TOKEN=your-token

Step 3: Start Services

From the backend directory:

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

This starts:

✅ Backend API (port 8001)
✅ Commercetools MCP Server (port 3000)
✅ Voucherify MCP Server (port 3002)
✅ Redis (port 6379)

Expected output:

Creating network "backend_default" with the default driver
Creating backend_redis_1              ... done
Creating backend_ct-mcp-server_1      ... done
Creating backend_voucherify-mcp_1     ... done
Creating backend_machbot_1            ... done

Step 4: Verify Backend

Check that the backend is running:

curl http://localhost:8001/health

Expected response:

{
  "status": "healthy",
  "timestamp": "2024-11-03T12:00:00Z"
}

Step 5: Start Frontend

In a new terminal, navigate to the frontend directory:

cd frontend
pnpm install
pnpm dev

The frontend will start on http://localhost:5173

Step 6: Test the Application

Try the Chat Interface

Open http://localhost:5173 in your browser
Sign up for a new account or sign in
Try these example conversations:

Example 1: List Products

You: Show me berry flavored products

Example 2: Add to Cart

You: Add 50 Berry Blast to my cart

Example 3: View Cart

You: What's in my cart?

Example 4: Place Order

You: Place my order

Quick Test Commands

Check All Services

# View running containers
docker-compose -f backend/docker-compose.dev.yml ps

# Check logs
docker-compose -f backend/docker-compose.dev.yml logs -f

# Check specific service
docker-compose -f backend/docker-compose.dev.yml logs machbot

Test API Directly

# Test chat endpoint
curl -X POST http://localhost:8001/agent/chat \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Show me products",
    "session_id": "test-123",
    "customer_id": "customer-abc"
  }'

Stopping Services

# Stop all services
cd backend
docker-compose -f docker-compose.dev.yml down

# Stop and remove volumes (clean slate)
docker-compose -f docker-compose.dev.yml down -v

Common Issues

Port Already in Use

If you see "port is already allocated":

# Find what's using the port
lsof -i :8001

# Stop the conflicting service
kill -9 <PID>

Backend Won't Start

Check logs for errors:

docker-compose -f docker-compose.dev.yml logs machbot

Common issues:

Missing API keys in .env
Invalid Commercetools credentials
Network connectivity issues

Frontend Can't Connect

Verify backend is running: curl http://localhost:8001/health
Check CORS settings in backend .env:

CORS_ORIGINS=http://localhost:3000,http://localhost:5173

Clear browser cache and reload

Redis Connection Errors

Restart Redis container:

docker-compose -f docker-compose.dev.yml restart redis

Project Structure Overview

B2B-Wholesale-AI/
├── backend/
│   ├── app/
│   │   ├── agent/           # LangGraph AI agent
│   │   ├── routers/         # API endpoints
│   │   ├── services/        # Business logic
│   │   └── mcp/             # MCP client
│   ├── docker-compose.dev.yml
│   └── .env
├── frontend/
│   ├── src/
│   │   ├── components/      # React components
│   │   ├── routes/          # TanStack Router
│   │   └── integrations/    # API clients
│   └── .env
└── docs/
    └── content/docs/        # This documentation

What's Running?

Backend API (`localhost:8001`)

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

Frontend (`localhost:5173`)

Chat interface
User authentication
Product browsing
Cart management

MCP Servers

Commercetools (port 3000) - Product and order management
Voucherify (port 3002) - Promotions and campaigns

Redis (`localhost:6379`)

Session storage
Conversation history
Cache

Next Steps

Now that you have SynapseAI running:

Try User Scenarios →

Example conversations and workflows

Development Setup →

Set up for active development

Architecture →

Understand how it works

API Reference →

Explore the API

Advanced Configuration

Want more control? Check out:

Full Backend Setup - Run without Docker
Frontend Development - Hot reload and debugging
MCP Server Configuration - Custom MCP setup

Estimated Time: 30 minutes
Difficulty: Beginner
Result: Fully functional local SynapseAI instance