Skip to content

Backend Overview

The backend is a Python monorepo using Poetry for dependency management, with packages organized by functionality.

Package Structure

backend/
├── apps/                    # Applications
│   ├── api/                # FastAPI services
│   │   └── search/        # Main search API
│   ├── cli/               # Command-line tools
│   ├── evaluation/        # Evaluation utilities
│   └── jobs/              # Background jobs
├── packages/               # Shared packages
│   ├── ixinfra/          # Core infrastructure
│   ├── ixchat/           # Chat functionality
│   ├── ixrag/            # RAG processing
│   ├── ixllm/            # LLM abstractions
│   ├── ixneo4j/          # Neo4j management
│   ├── ixmongo/          # MongoDB storage
│   ├── ixapi_helpers/    # API utilities
│   ├── ixdata/           # Data access
│   └── ixweb/            # FastAPI components
└── justfile               # Backend commands

Core Packages

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.

ixchat - LangGraph Chatbot

LangGraph-based chatbot with retrieval capabilities and conversation memory.

Features:

  • LangGraph state management for complex conversation flows
  • Retrieval-augmented generation (RAG)
  • Conversation memory across queries
  • Fallback mechanisms for URL loading failures
  • OpenAI integration (default: gpt-4o-mini)

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

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.