Backend Architecture

The Magnet AI backend is built with Python and Litestar, providing a high-performance, asynchronous API layer and AI orchestration capabilities.

Project Structure

api/
├── src/
│   ├── app.py                 # Application entry point & Factory
│   ├── api/                   # API Controllers (Endpoints)
│   ├── config/                # Configuration (Pydantic settings)
│   ├── core/                  # Core infrastructure
│   │   ├── db/                # Database session & config
│   │   ├── server/            # Server plugins & middleware
│   │   └── domain/            # Domain models & logic
│   ├── data_sources/          # Data source integrations
│   ├── guards/                # Authorization guards
│   ├── middlewares/           # Request/response middlewares
│   ├── open_ai/               # OpenAI integration
│   ├── plugins/               # Plugin system
│   ├── routes/                # Route registration
│   ├── services/              # Business services
│   ├── stores/                # Data access layer
│   ├── tools/                 # AI tools (RAG, retrieval)
│   └── utils/                 # Utility functions
├── scripts/                   # Database and setup scripts
├── tests/                     # Test suite
├── pyproject.toml             # Dependencies (Poetry)
└── run.py                     # Development server wrapper

Core Components

Application Layer (app.py)

• Litestar application factory
• Plugin registration (CORS, SQLAlchemy, OpenAPI, etc.)
• Middleware configuration
• Exception handlers

Models (models.py / core/domain)

SQLAlchemy Async ORM models representing:

• Agents
• Prompt Templates
• Knowledge Sources
• RAG Tools
• Retrieval Tools
• Conversations
• Usage metrics

API Layer (/api)

Litestar Controllers organized by resource:

• TagsController - Tag management
• AgentsController - Agent management
• PromptTemplatesController - Prompt template CRUD
• KnowledgeSourcesController - Knowledge source management

Services (/services)

Business logic layer containing:

• Agent execution service
• RAG orchestration service
• Embedding generation service
• Model management service
• Evaluation service

Plugin System (/plugins)

Extensible plugin architecture:

• Base plugin interface
• Plugin discovery and loading
• Plugin lifecycle management
• External plugin support

Data Sources (/data_sources)

Connectors for various data sources:

• File uploads
• External APIs (Salesforce, HubSpot, etc.)
• Database connections
• Vector stores

Key Architectural Patterns

1. Controller-Service-Repository Pattern

• Controllers: Handle HTTP requests, validation (Pydantic), and response formatting.
• Services: Contain business logic.
• Repositories/Stores: Handle database interactions.

2. Dependency Injection (DI)

Litestar's powerful DI system is used to inject dependencies into handlers:

@get("/")
async def get_agent(
    agent_id: UUID,
    service: AgentService
) -> Agent:
    return await service.get(agent_id)

3. Asynchronous Design

The entire backend is async-first, utilizing Python's asyncio and asyncpg for non-blocking I/O, which is crucial for AI applications that often wait for external LLM APIs.

4. Plugin Pattern

Extensions are loaded dynamically via a registry, allowing for modular additions of knowledge sources and tools.

Database Integration

SQLAlchemy Async ORM

• Models defined using declarative base.
• Migrations managed with Alembic.
• PostgreSQL + pgvector: The standard production database, supporting vector similarity search natively.

AI Integration

OpenAI Service

• GPT model integration
• Streaming support
• Token usage tracking
• Error handling and retries

LlamaIndex / LangChain

• Used for RAG (Retrieval Augmented Generation) pipelines.
• Document indexing and retrieval.
• Agentic workflows.

Configuration Management

Pydantic Settings

Configuration is managed via Pydantic models in src/config/, loading values from environment variables (.env).

• OPENAI_API_KEY
• DATABASE_URL
• VECTOR_DB_TYPE

Error Handling

• Global exception handlers convert exceptions to standardized JSON responses (Problem Details).
• Structured logging via structlog.

Testing

Located in /tests:

• Pytest: The testing framework.
• Async Tests: Fully async test suite.
• Fixtures: Extensive use of pytest fixtures for DB sessions and mock services.

API Documentation

• OpenAPI / Swagger UI: Automatically generated by Litestar.
• Accessible at /schema/swagger or /schema/redoc.

Next Steps

• Frontend Architecture - Frontend details
• Database Schema - Data models
• REST API - API reference