Skip to content

Backend Overview

The backend is a Python monorepo using Poetry for dependency management. Packages are organized into agent-specific packages and shared infrastructure that can be reused across multiple agents.

Package Architecture

flowchart TB subgraph Agents["Agent-Specific Packages"] ixchat[ixchat<br/>Website Agent] end subgraph Shared["Shared Infrastructure"] ixrag[ixrag<br/>RAG System] ixllm[ixllm<br/>LLM Abstractions] ixmongo[ixmongo<br/>MongoDB Storage] ixneo4j[ixneo4j<br/>Neo4j Storage] ixdata[ixdata<br/>External Data] ixweb[ixweb<br/>FastAPI Components] ixinfra[ixinfra<br/>Core Utilities] ixapi_helpers[ixapi_helpers<br/>Auth Middleware] ixtagging[ixtagging<br/>Classification] end ixchat --> ixrag ixchat --> ixinfra ixchat --> ixdata ixrag --> ixllm ixrag --> ixmongo ixrag --> ixneo4j ixllm --> ixinfra ixmongo --> ixinfra ixneo4j --> ixinfra ixdata --> ixinfra ixweb --> ixinfra ixweb --> ixapi_helpers ixtagging --> ixllm

Package Structure

backend/
├── apps/                    # Applications
│   ├── api/                # FastAPI services
│   │   └── search/        # Website Agent API
│   ├── cli/               # Command-line tools
│   ├── evaluation/        # Evaluation utilities
│   └── jobs/              # Background jobs
├── packages/               # Shared packages
│   ├── ixchat/           # Website Agent core (agent-specific)
│   ├── ixrag/            # RAG processing (shared)
│   ├── ixllm/            # LLM abstractions (shared)
│   ├── ixmongo/          # MongoDB storage (shared)
│   ├── ixneo4j/          # Neo4j management (shared)
│   ├── ixdata/           # Data access (shared)
│   ├── ixweb/            # FastAPI components (shared)
│   ├── ixinfra/          # Core infrastructure (shared)
│   ├── ixapi_helpers/    # API utilities (shared)
│   ├── ixtagging/        # Conversation tagging (shared)
│   └── ixpromptclassifier/  # Prompt analysis (shared)
└── justfile               # Backend commands

Agent-Specific Packages

ixchat - Website Agent Core

LangGraph-based chatbot powering the Website Agent. This is the main backend package for the Website Agent.

Features:

  • LangGraph state management for complex conversation flows
  • Multi-agent router architecture with intent classification
  • Retrieval-augmented generation (RAG)
  • Conversation memory across queries
  • Visitor enrichment pipeline
  • Azure OpenAI integration (default: gpt-4o-mini)

See IXChat Package for detailed architecture documentation.

Shared Infrastructure

These packages are designed to be reused by future agents.

ixinfra - Infrastructure Components

Core utilities and shared configuration for all backend services.

Features:

  • Configuration management (environment-based TOML configs)
  • Logging setup and utilities
  • Networking utilities
  • Path management

Usage: Foundation package used by all other packages.

ixrag - Advanced RAG Implementation

LightRAG integration with intelligent document limiting and multi-modal retrieval.

Features:

  • Document Limiter: Intelligent allocation across chunks, entities, and relationships
  • RAG Mode Optimization: Different strategies for global/local/hybrid modes
  • Multi-Modal Retrieval: Balanced retrieval from text chunks, entities, and relationships
  • Tenant Isolation: Multi-tenant RAG instance management

ixllm - Language Model Abstractions

Unified interface for language model clients with retry logic.

Features:

  • Client factory (OpenAI, Azure OpenAI)
  • Message conversion utilities
  • Automatic retry logic with exponential backoff
  • Observability integration

ixapi_helpers - API Middleware

Reusable API authentication and middleware components.

Features:

  • Authentication middleware for FastAPI
  • Token management and caching
  • User caching
  • Storage utilities

Multi-Tenancy Architecture

MongoDB Multi-Tenant Storage (ixmongo)

Custom implementation solving MongoDB Atlas vector index limitations.

Problem: MongoDB Atlas limits vector search indexes per cluster.

Solution: Shared collections with tenantId property filtering.

Aspect Implementation
Collections Shared across all tenants
Isolation tenantId field on all documents
IDs Composite format: tenant_id:original_id
Queries Filter: {"tenantId": tenant_id}
Vector Index Single shared index (vector_knn_index_shared_v2)

Neo4j Multi-Tenant Storage (ixneo4j)

Property-based tenant isolation for Neo4j knowledge graphs.

Implementation:

  • Property-based isolation using tenantId on all nodes/edges
  • Query injection: All Cypher queries include WHERE n.tenantId = $tenant_id
  • Wraps LightRAG's Neo4JStorage

Features:

  • Database name sanitization for company names
  • Automatic database creation per tenant
  • Connection management with retries
  • CLI interface for database administration

Agent Configuration (Supabase)

Per-site agent behavior configuration stored in the agent_config table:

Column Group Purpose
Identity company_name, website_url, client_description
Prompt content (prompt_*) Pricing responses, case studies, calculators
Behavior (behavior_*) Interest signals, thresholds, suggested answers rules

Configuration is resolved with cascading lookup: site-specific → global → default.

Configuration

Environment Variables

The application uses IX_ENVIRONMENT to determine configuration:

# Available environments
IX_ENVIRONMENT=test        # Local testing
IX_ENVIRONMENT=staging     # Staging
IX_ENVIRONMENT=production  # Production
IX_ENVIRONMENT=development # Development

Prompt Configuration

The chat configuration system has intelligent defaults:

  • If prompt_label is defined in TOML config, that value is used
  • If not present, defaults to the current environment name
  • Configuration file fallback: Falls back to production.toml if env-specific file not found

Quick Commands

cd backend

# Development
just dev staging              # Start dev server

# Testing
poetry run pytest             # All tests
poetry run pytest -m unit     # Unit tests only
poetry run pytest -m integration  # Integration tests

# Code quality
poetry run ruff check         # Linting
poetry run ruff format        # Format code

# Deployment
just deploy staging           # Deploy to staging
just release                  # Production release

See Backend Setup for detailed setup instructions.