Welcome

Introduction

Introduction

Setup & Installation

Setup OverviewPrerequisitesQuick Start
MCP Servers

Architecture & Design

Architecture

Features & Scenarios

Deployment

Deployment

API Reference

API Reference

Tools & Utilities

Scripts & UtilitiesTroubleshooting
Setup & Installation

Prerequisites

Tools and accounts you need before starting

Prerequisites

Before setting up SynapseAI, ensure you have the following tools installed and accounts configured.

Required Tools

1. Docker & Docker Compose

Docker is required to run Redis and MCP servers.

Installation:

macOS:

# Install Docker Desktop
brew install --cask docker

Linux:

# Install Docker Engine
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

# Install Docker Compose
sudo curl -L "https://github.com/docker/compose/releases/latest/download/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose

Verify:

docker --version
docker-compose --version

2. Python 3.11+

Required for the backend.

Installation:

macOS:

brew install python@3.11

Linux (Ubuntu/Debian):

sudo apt update
sudo apt install python3.11 python3.11-venv python3-pip

Verify:

python3 --version  # Should be 3.11 or higher

3. Node.js 20.x+

Required for the frontend.

Installation:

macOS:

brew install node@20

Linux:

# Using NodeSource
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

Using nvm (Recommended):

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install 20
nvm use 20

Verify:

node --version   # Should be v20.x
npm --version

4. pnpm

Package manager for the frontend.

Installation:

npm install -g pnpm

Verify:

pnpm --version

5. uv (Optional but Recommended)

Fast Python package manager.

Installation:

curl -LsSf https://astral.sh/uv/install.sh | sh

Verify:

uv --version

Required API Keys & Accounts

1. LLM Provider (Choose One)

You need at least one LLM provider API key:

OpenAI (Recommended for production):

  • Sign up: platform.openai.com
  • Create API key
  • Models: GPT-4, GPT-3.5-turbo

Cerebras (Recommended for development):

  • Sign up: cloud.cerebras.ai
  • Fast inference, cost-effective
  • Models: Llama 3.3 70B

Groq (Alternative):

  • Sign up: groq.com
  • Very fast inference
  • Free tier available

Together AI (Alternative):

  • Sign up: together.ai
  • Multiple open-source models

2. Commercetools

E-commerce platform for product catalog and orders.

Setup:

  1. Sign up: commercetools.com
  2. Create a project
  3. Get API credentials:
    • Project Key
    • Client ID
    • Client Secret
    • API URL
    • Auth URL
  4. Set scopes: manage_products, manage_orders, manage_customers

3. Voucherify

Promotion and loyalty platform.

Setup:

  1. Sign up: voucherify.io
  2. Create an application
  3. Get credentials:
    • Application ID
    • Application Token
  4. Note the API URL

4. AWS Account (For Deployment Only)

Required only if deploying to production.

Setup:

  1. Create AWS account: aws.amazon.com
  2. Set up IAM user with appropriate permissions
  3. Configure AWS CLI:
aws configure

Development Tools (Recommended)

IDE/Editor

VS Code (Recommended):

# macOS
brew install --cask visual-studio-code

# Extensions
code --install-extension ms-python.python
code --install-extension dbaeumer.vscode-eslint
code --install-extension esbenp.prettier-vscode

PyCharm (Alternative):

  • Professional or Community edition
  • Python and Docker plugins

Database Client

Redis CLI:

# macOS
brew install redis

# Linux
sudo apt install redis-tools

RedisInsight (GUI):

# macOS
brew install --cask redisinsight

API Testing

httpie or curl:

# macOS
brew install httpie

# Test
http GET http://localhost:8001/health

Postman (Alternative):

  • Download from postman.com

Environment Configuration

Create environment files for storing credentials:

Backend .env

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

Frontend .env

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

Verify Setup

Run this checklist to ensure everything is ready:

# Check Docker
docker --version && docker-compose --version

# Check Python
python3 --version

# Check Node.js and pnpm
node --version && pnpm --version

# Check uv (optional)
uv --version

# Test Docker
docker run hello-world

Quick Test

Clone the repository and verify structure:

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

# Verify structure
ls -la backend/
ls -la frontend/
ls -la docs/

Troubleshooting

Python Version Issues

If python3 --version shows an older version:

# macOS - set default
brew link --overwrite python@3.11

# Linux - use update-alternatives
sudo update-alternatives --install /usr/bin/python3 python3 /usr/bin/python3.11 1

Docker Permission Issues (Linux)

# Add user to docker group
sudo usermod -aG docker $USER

# Logout and login again

Port Already in Use

Check and free up ports:

# Check what's using port 8001
lsof -i :8001

# Kill process if needed
kill -9 <PID>

Next Steps

All set? Move on to:

Quick Start →

Run with Docker Compose

Backend Setup →

Detailed backend installation

Estimated Time: 30-45 minutes
Difficulty: Beginner

Setup Overview

Get SynapseAI running on your machine

Quick Start

Get SynapseAI running in 30 minutes with Docker Compose

On this page

PrerequisitesRequired Tools1. Docker & Docker Compose2. Python 3.11+3. Node.js 20.x+4. pnpm5. uv (Optional but Recommended)Required API Keys & Accounts1. LLM Provider (Choose One)2. Commercetools3. Voucherify4. AWS Account (For Deployment Only)Development Tools (Recommended)IDE/EditorDatabase ClientAPI TestingEnvironment ConfigurationBackend .envFrontend .envVerify SetupQuick TestTroubleshootingPython Version IssuesDocker Permission Issues (Linux)Port Already in UseNext Steps