Architecture Overview

SynapseAI is built on a modern, composable architecture that combines conversational AI, e-commerce platforms, and intelligent automation. This documentation uses FlavorFlux (a fictional CPG brand) as the demo use case.

Strategic Vision

SynapseAI enables CPG brands (like our demo brand FlavorFlux) to become truly adaptive through:

AI-powered community intelligence
Predictive analytics
Seamless B2B commerce automation
Conversational ordering experiences

High-Level Architecture

System Components

Core Technologies

Backend Stack

FastAPI: High-performance Python web framework
LangGraph: Stateful AI agent orchestration
LiteLLM: Multi-provider LLM interface
Redis: Session and state management
Pydantic: Data validation and serialization

Frontend Stack

React 18: UI component library
Vite: Fast build tool and dev server
TanStack Router: Type-safe routing
TanStack Query: Server state management
TanStack Store: Client state management
Shadcn/ui: Component library
Tailwind CSS: Utility-first styling

Infrastructure

AWS ECS Fargate: Containerized service hosting
AWS ALB: Load balancing and SSL termination
AWS ElastiCache: Redis cluster
AWS ECR: Container registry
Terraform: Infrastructure as Code

LangGraph Agent Architecture

The conversational AI is built using LangGraph with specialized nodes for different intents:

Agent Flow

Key Nodes

1. Intent Detection

intent_detector: Classifies user messages into intents
Routes to appropriate specialized handlers
Supports multi-turn conversations

2. Product Operations

product_processor: Lists and searches products
product_resolution: Matches user queries to products
product_disambiguation: Handles multiple matches

3. Cart Management

cart_get_processor: Views cart contents
cart_update_processor: Parses cart addition requests
cart_add_processor: Adds items to cart via MCP
cart_remove_processor: Removes items from cart

4. Order Operations

order_processor: Places orders
order_history_processor: Shows past orders
reorder_processor: Repeats previous orders

5. Campaign Management

promotion_processor: Lists active campaigns
Integrates with Voucherify via MCP

6. Response Generation

response_generator: Formats AI responses
Handles structured data display
Manages conversation context

MCP (Model Context Protocol) Integration

MCP provides a standardized way to integrate external services:

MCP Clients

Commercetools MCP

Endpoint: http://localhost:3000

Capabilities:

Product catalog management
Cart operations (create, update, view)
Order placement and tracking
Customer management

Voucherify MCP

Endpoint: http://localhost:3002

Capabilities:

Campaign listing
Promotion management
Voucher validation
Loyalty program integration

MCP Client Pattern

from app.mcp.client import MCPClient

# Initialize client
ct_client = MCPClient(base_url="http://localhost:3000")

# Make MCP calls
products = await ct_client.call_tool(
    tool_name="list-products",
    arguments={"filter": "categories:yogurt"}
)

Data Flow

Conversational Order Flow

User Input → Frontend chat interface
API Request → POST /agent/chat
Intent Detection → LangGraph classifies intent
Product Resolution → Match products via MCP
Cart Update → Add items via Commercetools MCP
Promotion Check → Validate via Voucherify MCP
Response Generation → Format and return
UI Update → Display in chat interface

Authentication Flow

User Login → POST /auth/login
Token Generation → JWT with claims
Session Creation → Store in Redis
Token Storage → Frontend localStorage
API Requests → Include Bearer token
Token Validation → Verify on each request
Auto Refresh → Refresh before expiry

Session Management

Redis Session Store

Structure:

{
  "session_id": "user-123",
  "customer_id": "ct-customer-abc",
  "messages": [
    {"role": "user", "content": "Show me products"},
    {"role": "assistant", "content": "Here are our products..."}
  ],
  "cart_id": "cart-xyz",
  "context": {
    "last_intent": "product_operations",
    "disambiguation_state": null
  },
  "ttl": 3600
}

Session Lifecycle

Creation: On first message
Updates: After each interaction
Expiry: 1 hour of inactivity
Cleanup: Automatic Redis TTL

Security Architecture

Authentication

JWT Tokens: Stateless authentication
Refresh Tokens: Long-lived renewal
Token Claims: User ID, customer ID, roles

Authorization

Role-Based: Admin, buyer, store rep
Resource-Based: Own orders only
API Gateway: Validates all requests

CORS Configuration

CORS_ORIGINS = [
    "http://localhost:3000",
    "http://localhost:5173",
    "https://your-production-domain.com"
]

Secrets Management

Development: .env files
Production: AWS Secrets Manager
Rotation: Automatic for sensitive keys

AI and LLM Strategy

Dual LLM Approach

LiteLLM (Basic Tasks)

Intent classification
Product search
Text parsing
Response generation

Models Supported:

OpenAI (GPT-4, GPT-3.5)
Cerebras (Llama 3.3 70B)
Groq (Fast inference)
Together AI

Advanced AI (Complex Tasks)

Campaign Template AI:

Community sentiment analysis
Campaign generation
Smart targeting
AWS Bedrock integration

Demand Forecasting AI:

Historical sales analysis
Inventory optimization
Trend prediction
AWS Forecast integration

Predictive Reordering AI:

Sales pattern analysis
Stockout prevention
Inventory turnover
AWS Forecast integration

LLM Router

Intelligent routing between LiteLLM and Advanced AI:

Cost optimization
Performance balancing
Fallback mechanisms
Request queuing

Composable Commerce Core

Commercetools Integration

Purpose: E-commerce platform Capabilities:

Product catalog
Cart management
Order processing
Customer management

Voucherify Integration

Purpose: Promotion engine Capabilities:

Dynamic promotions
Loyalty programs
Volume discounts
Campaign analytics

Scalability Considerations

Horizontal Scaling

ECS Tasks: Auto-scaling based on CPU/memory
Redis Cluster: Sharded for high throughput
Load Balancer: Distributes traffic evenly

Caching Strategy

Redis: Session data, product catalog cache
LiteLLM: Response caching for common queries
CDN: Static assets (frontend)

Performance Optimization

Connection Pooling: HTTP clients, Redis
Async Operations: FastAPI async/await
Lazy Loading: Frontend code splitting

Monitoring and Observability

Logging

Application Logs: CloudWatch Logs
Access Logs: ALB logs
Error Tracking: Structured logging

Metrics

Application Metrics: Custom CloudWatch metrics
Infrastructure Metrics: ECS, Redis, ALB
Business Metrics: Orders, sessions, conversions

Health Checks

Backend: GET /health
MCP Servers: Connection checks
Redis: Ping checks
Dependencies: External service monitoring

Next Steps

Backend Setup - Set up the backend
Frontend Setup - Set up the frontend
User Scenarios - Learn about user workflows
Deployment - Deploy to production
C4 Architecture - Detailed C4 diagrams

Architecture Overview

Strategic Vision

SynapseAI enables CPG brands (like our demo brand FlavorFlux) to become truly adaptive through:

AI-powered community intelligence
Predictive analytics
Seamless B2B commerce automation
Conversational ordering experiences

High-Level Architecture

System Components

Core Technologies

Backend Stack

FastAPI: High-performance Python web framework
LangGraph: Stateful AI agent orchestration
LiteLLM: Multi-provider LLM interface
Redis: Session and state management
Pydantic: Data validation and serialization

Frontend Stack

React 18: UI component library
Vite: Fast build tool and dev server
TanStack Router: Type-safe routing
TanStack Query: Server state management
TanStack Store: Client state management
Shadcn/ui: Component library
Tailwind CSS: Utility-first styling

Infrastructure

AWS ECS Fargate: Containerized service hosting
AWS ALB: Load balancing and SSL termination
AWS ElastiCache: Redis cluster
AWS ECR: Container registry
Terraform: Infrastructure as Code

LangGraph Agent Architecture

The conversational AI is built using LangGraph with specialized nodes for different intents:

Agent Flow

Key Nodes

1. Intent Detection

intent_detector: Classifies user messages into intents
Routes to appropriate specialized handlers
Supports multi-turn conversations

2. Product Operations

product_processor: Lists and searches products
product_resolution: Matches user queries to products
product_disambiguation: Handles multiple matches

3. Cart Management

cart_get_processor: Views cart contents
cart_update_processor: Parses cart addition requests
cart_add_processor: Adds items to cart via MCP
cart_remove_processor: Removes items from cart

4. Order Operations

order_processor: Places orders
order_history_processor: Shows past orders
reorder_processor: Repeats previous orders

5. Campaign Management

promotion_processor: Lists active campaigns
Integrates with Voucherify via MCP

6. Response Generation

response_generator: Formats AI responses
Handles structured data display
Manages conversation context

MCP (Model Context Protocol) Integration

MCP provides a standardized way to integrate external services:

MCP Clients

Commercetools MCP

Endpoint: http://localhost:3000

Capabilities:

Product catalog management
Cart operations (create, update, view)
Order placement and tracking
Customer management

Voucherify MCP

Endpoint: http://localhost:3002

Capabilities:

Campaign listing
Promotion management
Voucher validation
Loyalty program integration

MCP Client Pattern

from app.mcp.client import MCPClient

# Initialize client
ct_client = MCPClient(base_url="http://localhost:3000")

# Make MCP calls
products = await ct_client.call_tool(
    tool_name="list-products",
    arguments={"filter": "categories:yogurt"}
)

Data Flow

Conversational Order Flow

User Input → Frontend chat interface
API Request → POST /agent/chat
Intent Detection → LangGraph classifies intent
Product Resolution → Match products via MCP
Cart Update → Add items via Commercetools MCP
Promotion Check → Validate via Voucherify MCP
Response Generation → Format and return
UI Update → Display in chat interface

Authentication Flow

User Login → POST /auth/login
Token Generation → JWT with claims
Session Creation → Store in Redis
Token Storage → Frontend localStorage
API Requests → Include Bearer token
Token Validation → Verify on each request
Auto Refresh → Refresh before expiry

Session Management

Redis Session Store

Structure:

{
  "session_id": "user-123",
  "customer_id": "ct-customer-abc",
  "messages": [
    {"role": "user", "content": "Show me products"},
    {"role": "assistant", "content": "Here are our products..."}
  ],
  "cart_id": "cart-xyz",
  "context": {
    "last_intent": "product_operations",
    "disambiguation_state": null
  },
  "ttl": 3600
}

Session Lifecycle

Creation: On first message
Updates: After each interaction
Expiry: 1 hour of inactivity
Cleanup: Automatic Redis TTL

Security Architecture

Authentication

JWT Tokens: Stateless authentication
Refresh Tokens: Long-lived renewal
Token Claims: User ID, customer ID, roles

Authorization

Role-Based: Admin, buyer, store rep
Resource-Based: Own orders only
API Gateway: Validates all requests

CORS Configuration

CORS_ORIGINS = [
    "http://localhost:3000",
    "http://localhost:5173",
    "https://your-production-domain.com"
]

Secrets Management

Development: .env files
Production: AWS Secrets Manager
Rotation: Automatic for sensitive keys

AI and LLM Strategy

Dual LLM Approach

LiteLLM (Basic Tasks)

Intent classification
Product search
Text parsing
Response generation

Models Supported:

OpenAI (GPT-4, GPT-3.5)
Cerebras (Llama 3.3 70B)
Groq (Fast inference)
Together AI

Advanced AI (Complex Tasks)

Campaign Template AI:

Community sentiment analysis
Campaign generation
Smart targeting
AWS Bedrock integration

Demand Forecasting AI:

Historical sales analysis
Inventory optimization
Trend prediction
AWS Forecast integration

Predictive Reordering AI:

Sales pattern analysis
Stockout prevention
Inventory turnover
AWS Forecast integration

LLM Router

Intelligent routing between LiteLLM and Advanced AI:

Cost optimization
Performance balancing
Fallback mechanisms
Request queuing

Composable Commerce Core

Commercetools Integration

Purpose: E-commerce platform Capabilities:

Product catalog
Cart management
Order processing
Customer management

Voucherify Integration

Purpose: Promotion engine Capabilities:

Dynamic promotions
Loyalty programs
Volume discounts
Campaign analytics

Scalability Considerations

Horizontal Scaling

ECS Tasks: Auto-scaling based on CPU/memory
Redis Cluster: Sharded for high throughput
Load Balancer: Distributes traffic evenly

Caching Strategy

Redis: Session data, product catalog cache
LiteLLM: Response caching for common queries
CDN: Static assets (frontend)

Performance Optimization

Connection Pooling: HTTP clients, Redis
Async Operations: FastAPI async/await
Lazy Loading: Frontend code splitting

Monitoring and Observability

Logging

Application Logs: CloudWatch Logs
Access Logs: ALB logs
Error Tracking: Structured logging

Metrics

Application Metrics: Custom CloudWatch metrics
Infrastructure Metrics: ECS, Redis, ALB
Business Metrics: Orders, sessions, conversions

Health Checks

Backend: GET /health
MCP Servers: Connection checks
Redis: Ping checks
Dependencies: External service monitoring

Next Steps

Backend Setup - Set up the backend
Frontend Setup - Set up the frontend
User Scenarios - Learn about user workflows
Deployment - Deploy to production
C4 Architecture - Detailed C4 diagrams

Architecture

On this page

Architecture

On this page