Backend Overview

FastAPI Python backend with 25+ routers and AI services

Introduction

The Zarna backend is a modern FastAPI application providing a comprehensive REST API for CRM operations, document processing, AI-powered analysis, and external integrations. The backend powers all Zarna features, including the Zarna AI chatbot.

Technology Stack

• FastAPI - Modern, high-performance web framework
• Python 3.8+ - Language runtime
• Uvicorn - ASGI server with auto-reload
• Pydantic - Data validation using Python type hints
• Supabase - PostgreSQL database client
• Anthropic Claude - AI-powered analysis
• Docling - Advanced document processing
• AutoGen - Multi-agent AI orchestration

Full Tech Stack

See the complete list of backend technologies

Architecture

Main Application

Location: api/app/main.py

The application entry point configures FastAPI with:

app = FastAPI(
    title="Zarna API",
    description="API for Zarna application",
    version="0.1.0"
)

Key Features:

• OpenAPI Documentation: Auto-generated at /docs and /redoc
• CORS Middleware: Configured for localhost:3000, localhost:3001, localhost:8000
• JWT Authentication: Middleware for protected routes
• Exception Handling: Custom handlers for clean error responses
• Startup/Shutdown Events: Agent pool initialization and cleanup

Project Structure

zarna-backend/
├── api/                          # FastAPI application
│   ├── app/
│   │   ├── main.py              # Application entry point
│   │   ├── routers/             # API endpoints (25+ routers)
│   │   ├── middleware/          # JWT auth, CORS
│   │   └── auth/                # Authentication logic
│   ├── run.py                   # Development server
│   └── run_prod.py              # Production server
│
├── scripts/                      # Business logic (145+ files)
│   ├── agentic_chat/            # Multi-agent chat system
│   ├── batched_cim_service.py   # Batch CIM processing
│   ├── crm_agent.py             # AI-powered CRM operations
│   ├── email_agent_microservice/ # Email automation
│   ├── enhanced_extraction_service.py
│   └── ...                      # Many more services
│
├── requirements.txt              # Python dependencies
└── .env                         # Environment variables

API Routers

The backend has 25+ routers organized by domain:

CRM Routers

Companies

Company CRUD operations, search, filtering

Contacts

Contact management and relationships

Deals

Deal pipeline, stages, workflows

Interactions

Meetings, calls, notes tracking

Financials

Financial records and metrics

Notes

Notes management and search

File Management Routers

Files

Upload, process, extract documents

Google Drive

Drive sync and file operations

SharePoint

SharePoint integration

Egnyte

Egnyte file management

Basecamp

Basecamp project integration

Communication Routers

Emails

Email tracking and history

Email Bot

Automated email handling

Calendar

Google Calendar integration

AI & Analytics Routers

Reports

AI-powered report generation

Sourcing

AI company sourcing with Exa

Agentic Chat

Multi-agent AI chat system

Management Routers

Users

User management operations

Firms

Firm management

Prompts

AI prompt operations

Staffing

Team staffing management

Utilities

Utility endpoints

Chat History

Chat conversation history

Core Services

The backend includes several major services in the scripts/ directory:

CRM Agent

File: scripts/crm_agent.py Size: 51KB

AI-powered CRM operations that understand natural language queries.

Learn More

Explore the CRM agent service

Document Processing

Files: Multiple services for document extraction

• enhanced_extraction_service.py - Main extraction service
• batched_cim_service.py - Batch CIM processing
• cim_analysis_service.py - CIM analysis

Learn More

Understand document processing

Email Agent

Directory: scripts/email_agent_microservice/

Automated email handling with Gmail/Outlook integration.

Learn More

Explore the email agent

Report Generation

Files: Report generation services with streaming

AI-powered report generation with real-time streaming to frontend.

Learn More

See report generation service

Agentic Chat

Directory: scripts/agentic_chat/ Files: Agent pool, orchestrator, tools

Multi-agent system with pool manager for performance.

Learn More

Dive into the agentic system

Authentication & Security

JWT Authentication

Middleware: api/app/middleware/JWTAuthMiddleware

All routes are protected by JWT authentication:

# Protected endpoint example
@router.get("/companies")
async def get_companies(current_user: User = Depends(get_current_user)):
    # Only authenticated users can access
    return companies

Environment Variables

Required variables in .env:

# Database
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_KEY=your-service-role-key
SUPABASE_JWT_SECRET=your-jwt-secret

# AI Services
ANTHROPIC_API_KEY=sk-ant-xxxxx
OPENAI_API_KEY=sk-xxxxx

# OAuth (Composio)
COMPOSIO_API_KEY=your-key
COMPOSIO_GMAIL_AUTH_CONFIG_ID=your-config
COMPOSIO_OUTLOOK_AUTH_CONFIG_ID=your-config

# Search
EXA_API_KEY=your-exa-key

# Server
PORT=8000
HOST=0.0.0.0

Authentication Guide

Learn about JWT authentication

Database Integration

Supabase Client

The backend uses Supabase for PostgreSQL database access:

from supabase import create_client

supabase = create_client(
    os.getenv("SUPABASE_URL"),
    os.getenv("SUPABASE_KEY")
)

# Query data
companies = supabase.table("companies").select("*").execute()

Row Level Security

All tables have RLS policies for firm-level data isolation.

Database Guide

Explore the database architecture

Development Workflow

Starting the Server

cd zarna-backend/api
python run.py

Expected output:

[STARTUP] 🚀 Starting Zarna API with Agent Pool Manager...
[STARTUP] ✅ Agent Pool Manager started successfully
[STARTUP] ✅ Zarna API startup complete
INFO:     Uvicorn running on http://0.0.0.0:8000

API Documentation

Once running, access interactive API docs:

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc

Hot Reload

Development server automatically reloads on file changes.

Health Check

curl http://localhost:8000/health
# Response: {"status": "healthy"}

API Patterns

Request/Response Models

All endpoints use Pydantic models for validation:

from pydantic import BaseModel

class CompanyCreate(BaseModel):
    name: str
    industry: str | None = None
    revenue: float | None = None

class CompanyResponse(BaseModel):
    id: str
    name: str
    industry: str | None
    revenue: float | None
    created_at: str

@router.post("/companies", response_model=CompanyResponse)
async def create_company(company: CompanyCreate):
    # Validation happens automatically
    return created_company

Error Handling

Consistent error responses:

from fastapi import HTTPException

# 404 Not Found
raise HTTPException(status_code=404, detail="Company not found")

# 400 Bad Request
raise HTTPException(status_code=400, detail="Invalid company data")

# 401 Unauthorized
raise HTTPException(status_code=401, detail="Authentication required")

Async/Await

All endpoints use async for non-blocking I/O:

@router.get("/companies/{company_id}")
async def get_company(company_id: str):
    company = await fetch_company(company_id)  # Non-blocking
    return company

Performance

Agent Pool System

Eliminates 5-11s cold start latency for AI agents.

Agent Pool Guide

Learn about performance optimization

Background Tasks

Long-running operations use background tasks:

from fastapi import BackgroundTasks

@router.post("/process-document")
async def process_document(
    file: UploadFile,
    background_tasks: BackgroundTasks
):
    background_tasks.add_task(process_file, file)
    return {"status": "processing"}

Streaming Responses

Reports and chat use Server-Sent Events (SSE) for real-time streaming:

from fastapi.responses import StreamingResponse

@router.get("/stream-report")
async def stream_report():
    async def generate():
        for chunk in report_chunks:
            yield f"data: {chunk}\n\n"

    return StreamingResponse(generate(), media_type="text/event-stream")

Deployment

Production Server

File: api/run_prod.py

Uses Gunicorn with Uvicorn workers:

gunicorn app.main:app -w 4 -k uvicorn.workers.UvicornWorker

Environment Configuration

• Development: run.py with reload
• Production: run_prod.py without reload
• Dockerized deployment ready

Next Steps

Authentication

Learn about JWT authentication

Routers

Explore all API routers

Services

Understand core services

Database

Database architecture

Resources

• FastAPI Documentation
• Pydantic Documentation
• Uvicorn Documentation
• Supabase Python Client