Backend Setup

The SynapseAI backend is a FastAPI application powered by LangGraph for conversational AI orchestration.

Setup Steps

Follow these pages in order:

1. Installation

Install Python dependencies and tools

• Time: 10 minutes
• Difficulty: Beginner

2. Configuration

Set up environment variables and API keys

• Time: 15 minutes
• Difficulty: Beginner

3. Running Locally

Start the backend and verify it's working

• Time: 5 minutes
• Difficulty: Beginner

4. Development Guide

Hot reload, debugging, and best practices

• Time: 20 minutes
• Difficulty: Intermediate

What You'll Build

By the end of this section, you'll have:

✅ FastAPI backend running on http://localhost:8001
✅ LangGraph AI agent responding to chat messages
✅ MCP clients connecting to Commercetools and Voucherify
✅ Redis session storage
✅ Debug-ready development environment

Architecture Overview

Key Technologies

• FastAPI: Web framework with automatic API documentation
• LangGraph: Stateful AI agent orchestration
• LiteLLM: Multi-provider LLM interface
• Redis: Session and conversation history storage
• MCP Protocol: Standardized external service integration
• Pydantic: Data validation and serialization

Project Structure

backend/
├── app/
│   ├── agent/              # LangGraph AI agent
│   │   ├── intelligent_graph.py
│   │   └── state.py
│   ├── routers/            # API endpoints
│   │   └── auth.py
│   ├── services/           # Business logic
│   │   ├── customers.py
│   │   ├── prompts.py
│   │   └── session.py
│   ├── mcp/                # MCP client
│   │   └── client.py
│   ├── config.py           # Configuration
│   ├── models.py           # Data models
│   └── main.py             # Application entry
├── scripts/                # Utility scripts
├── docker-compose.dev.yml  # Docker setup
├── Dockerfile
├── pyproject.toml          # Dependencies
└── .env                    # Environment vars

Quick Start (Docker)

If you prefer Docker over manual setup:

cd backend
cp env.example .env
# Edit .env with your API keys
docker-compose -f docker-compose.dev.yml up --build -d

Then skip to Configuration to set up your API keys.

Prerequisites

Before proceeding, ensure you have:

• ✅ Python 3.11+ installed
• ✅ Docker Desktop running (for Redis)
• ✅ API keys ready (LLM provider, Commercetools, Voucherify)

Missing something? Go back to Prerequisites

Next Steps