Architecture Overview

System Architecture

The e-commerce API is built on a modern, scalable architecture designed to handle high-traffic retail operations. The system uses a microservices-oriented approach with multiple data stores and caching layers.

Technology Stack

Core Framework

Falcon WSGI Framework

Lightweight, high-performance Python web framework
RESTful API design with explicit routing
Minimal overhead for maximum throughput
Custom middleware pipeline for request processing

app = falcon.App(middleware=middleware)
app.req_options.keep_blank_qs_values = True
app.req_options.auto_parse_form_urlencoded = True

Database Layer

The platform uses a multi-database architecture for optimal performance and scalability:

MySQL

Primary relational database for transactional data

Write Instance: Product catalog, orders, users
Read Replica: Query optimization and load distribution
Connection pooling with SQLAlchemy ORM

MongoDB (DocumentDB)

NoSQL database for flexible schema data

Product metadata and catalogs
Shopping cart persistence
Session and analytics data

Redis

In-memory data store for caching

Multiple Redis instances for different purposes
Session management and user tokens
Real-time inventory buffers

Elasticsearch

Search and analytics engine

Product search and filtering
User behavior analytics
Recommendation engine data

Database Configuration

# MySQL Write Connection
engine = create_engine(
    'mysql+pymysql://{user}:{password}@{host}:{port}/{database}',
    pool_size=5,
    max_overflow=30,
    pool_pre_ping=True,
    pool_recycle=60,
    pool_timeout=60
)

# MySQL Read Replica
engine_r = create_engine(
    'mysql+pymysql://{user}:{password}@{host}:{port}/{database}',
    pool_size=5,
    max_overflow=30,
    pool_pre_ping=True
)

The API uses separate read and write connections to MySQL, allowing for horizontal scaling and improved query performance.

Middleware Pipeline

Requests flow through a series of middleware components that handle cross-cutting concerns:

middleware = [
    DatabaseManager(db_session, db_session_r, mongoDb),
    BlacklistHandler(),
    AuthHandler(),
    JSONTranslator(),
    CartMiddleware(),
    WishlistMiddleware(),
    MultipartMiddleware(),
    ActiveCartMiddleware(),
    MysqlWishlistMiddleware()
]

Middleware Components

DatabaseManager

Manages database connections throughout the request lifecycle.Responsibilities:

Injects MySQL and MongoDB sessions into request context
Handles automatic commit/rollback on response
Manages connection pooling and cleanup
Separates read/write database operations

def process_request(self, req, resp):
    req.context["mongo_session"] = self.mongo_session
    req.context['session'] = self._session_factory
    req.context['session_r'] = self._session_factory_r

AuthHandler

Handles JWT token validation and user authentication.Features:

JWT token decoding (standard and 512-bit)
User data caching in Redis (5-10 min TTL)
Two-factor authentication support
Public endpoint optimization (skips DB lookup)
Token blacklist validation

# Optimized auth flow
- Check if endpoint is public → skip auth if no token
- Decode JWT token (supports 2FA tokens with "2f." prefix)
- Try Redis cache for user data first
- Fall back to MySQL query on cache miss
- Validate user status and 2FA consistency

CartMiddleware

Manages shopping cart state and persistence.Features:

Loads cart only for whitelisted endpoints (performance optimization)
Merges browser cart with server-side cart
Supports hyperlocal and split order modes
MySQL-based cart persistence
Lazy calculation of cart totals

Cart-Required Endpoints:

/api/v2/cart, /api/v2/validatecheckout
/api/v2/processorder, /api/v2/order
Coupon and gift voucher endpoints

BlacklistHandler

Prevents access from blacklisted IPs and user agents.

Dedicated Redis instance for blacklist data
Real-time blocking without database queries

JSONTranslator

Automatically parses request body JSON and injects into req.context['data'].

Caching Strategy

The platform implements a multi-tier caching strategy using Beaker and Redis:

Cache Regions

cache_regions = {
    'ultra_short_term': {
        'expire': CACHE_ULTRA_SHORT_TERM,
        'type': 'ext:redis',
        'url': BEAKER_REDIS_URL
    },
    'mini_short_term': {
        'expire': CACHE_MINI_SHORT_TERM,
        'type': 'ext:redis'
    },
    'short_term': {
        'expire': CACHE_SHORT_TERM,
        'type': 'ext:redis'
    },
    'long_term': {
        'expire': CACHE_LONG_TERM,
        'type': 'ext:redis'
    },
    'ultra_long_term': {
        'expire': CACHE_ULTRA_LONG_TERM,
        'type': 'ext:redis'
    },
    'major_long_term': {
        'expire': CACHE_MAJOR_LONG_TERM,
        'type': 'ext:redis'
    }
}

Redis Instances

Multiple Redis instances serve different purposes:

Instance	Purpose	Configuration
Primary Redis	General caching, Beaker backend	`REDIS_HOST:REDIS_PORT`
User Redis	User session data, auth cache	`USER_REDIS_HOST:USER_REDIS_PORT`
Payment Redis	Payment processing state	`PAYMENT_REDIS_HOST:PAYMENT_REDIS_PORT`
Buffer Redis	Inventory buffer, real-time stock	`REDIS_BUFFER_HOST:REDIS_BUFFER_PORT`
Blacklist Redis	IP/user-agent blacklisting	`BLACKLIST_REDIS_HOST:BLACKLIST_REDIS_PORT`
CMS Redis	Content management cache	`CMS_REDIS_HOST:CMS_REDIS_PORT`

The use of dedicated Redis instances prevents cache invalidation conflicts and allows for independent scaling based on workload.

API Versioning

The API supports multiple versions through URL prefixes:

API_PREFIX = '/api/v2'      # Main API version
NEW_API_PREFIX = '/api/v3'   # Next generation endpoints
HAPTIK_API_PREFIX = '/api/v2/haptik'  # Chatbot integration
EXTERNAL_API_PREFIX = '/api/v2/external'  # Third-party apps

Background Processing

Asynchronous tasks are handled by Celery with multiple queues:

CELERY_KINESIS_ORDER_QUEUE - Order stream processing
CELERY_KINESIS_PRODUCT_QUEUE - Product sync to Kinesis
CELERY_CANCEL_ORDER_QUEUE - Order cancellation workflows
CELERY_ORDER_REFUND_QUEUE - Refund processing
CELERY_COMMS_QUEUE - Communication events (email, SMS)
SYNC_QUEUE - Data synchronization tasks

Infrastructure Components

AWS Kinesis

Real-time data streaming for:

Order events
Product updates
Analytics pipelines

AWS SQS

Message queuing for:

Webhook logging
User blocking events
Warehouse assignments

AWS S3

Object storage for:

Product images
Generated sitemaps
Export files

Gunicorn + WSGI

Production server:

Multi-worker processes
Custom gunicorn configuration
Health check endpoints

CORS Configuration

The API supports CORS for authorized domains:

cors = CORS(
    allow_origins_list=[
        'https://www.thesouledstore.com',
        'https://uat.thesouledstore.com',
        'https://dev.thesouledstore.ml',
        # ... additional domains
    ],
    allow_all_headers=True,
    allow_all_methods=True
)

Performance Optimizations

Connection Pooling

All database connections use pooling to reduce overhead:

pool_size=5          # Base connections
max_overflow=30      # Peak load capacity
pool_pre_ping=True   # Connection health checks
pool_recycle=60      # Recycle connections every 60s
pool_timeout=60      # Wait up to 60s for connection

Public Endpoint Optimization

Public catalog endpoints skip user authentication database queries when no auth token is provided, significantly reducing database load:

PUBLIC_API_ENDPOINTS = [
    "/api/v2/product/",
    "/api/v2/products/",
    "/api/v2/category/",
    "/api/v2/graphql",
    # ...
]

Cart Middleware Whitelisting

Cart data is only loaded for endpoints that actually need it, avoiding unnecessary database queries:

CART_REQUIRED_ENDPOINTS = [
    "/api/v2/cart",
    "/api/v2/validatecheckout",
    "/api/v2/processorder",
    # ...
]

These optimizations reduce database queries by up to 70% for anonymous browsing traffic.

Deployment Architecture

The application is containerized using Docker:

Dockerfile - Main application container
Dockerfile-celery - Celery worker container
Dockerfile-flower - Celery monitoring
docker-compose.yml - Multi-service orchestration

Monitoring & Observability

The platform integrates with multiple monitoring services:

New Relic - Application performance monitoring
Elasticsearch - Log aggregation and search
Slack - Exception notifications and alerts
Health check endpoint: /api/v2/health

Get Started

Core Concepts

Guides

System Architecture

Technology Stack

Core Framework

Database Layer

MySQL

MongoDB (DocumentDB)

Redis

Elasticsearch

Database Configuration

Middleware Pipeline

Middleware Components

Caching Strategy

Cache Regions

Redis Instances

API Versioning

Background Processing

Infrastructure Components

AWS Kinesis

AWS SQS

AWS S3

Gunicorn + WSGI

CORS Configuration

Performance Optimizations

Connection Pooling

Public Endpoint Optimization

Cart Middleware Whitelisting

Deployment Architecture

Monitoring & Observability

Build docs developers (and LLMs) love

Get Started

Core Concepts

Guides

​System Architecture

​Technology Stack

​Core Framework

​Database Layer

MySQL

MongoDB (DocumentDB)

Redis

Elasticsearch

​Database Configuration

​Middleware Pipeline

​Middleware Components

​Caching Strategy

​Cache Regions

​Redis Instances

​API Versioning

​Background Processing

​Infrastructure Components

AWS Kinesis

AWS SQS

AWS S3

Gunicorn + WSGI

​CORS Configuration

​Performance Optimizations

​Connection Pooling

​Public Endpoint Optimization

​Cart Middleware Whitelisting

​Deployment Architecture

​Monitoring & Observability

Build docs developers (and LLMs) love

System Architecture

Technology Stack

Core Framework

Database Layer

Database Configuration

Middleware Pipeline

Middleware Components

Caching Strategy

Cache Regions

Redis Instances

API Versioning

Background Processing

Infrastructure Components

CORS Configuration

Performance Optimizations

Connection Pooling

Public Endpoint Optimization

Cart Middleware Whitelisting

Deployment Architecture

Monitoring & Observability