> ## Documentation Index > Fetch the complete documentation index at: https://zarna.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # 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 See the complete list of backend technologies ## Architecture ### Main Application **Location**: `api/app/main.py` The application entry point configures FastAPI with: ```python theme={null} 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 Company CRUD operations, search, filtering Contact management and relationships Deal pipeline, stages, workflows Meetings, calls, notes tracking Financial records and metrics Notes management and search ### File Management Routers Upload, process, extract documents Drive sync and file operations SharePoint integration Egnyte file management Basecamp project integration ### Communication Routers Email tracking and history Automated email handling Google Calendar integration ### AI & Analytics Routers AI-powered report generation AI company sourcing with Exa Multi-agent AI chat system ### Management Routers User management operations Firm management AI prompt operations Team staffing management Utility endpoints 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. 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 Understand document processing ### Email Agent **Directory**: `scripts/email_agent_microservice/` Automated email handling with Gmail/Outlook integration. Explore the email agent ### Report Generation **Files**: Report generation services with streaming AI-powered report generation with real-time streaming to frontend. See report generation service ### Agentic Chat **Directory**: `scripts/agentic_chat/` **Files**: Agent pool, orchestrator, tools Multi-agent system with pool manager for performance. Dive into the agentic system ## Authentication & Security ### JWT Authentication **Middleware**: `api/app/middleware/JWTAuthMiddleware` All routes are protected by JWT authentication: ```python theme={null} # 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`: ```bash theme={null} # 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 ``` Learn about JWT authentication ## Database Integration ### Supabase Client The backend uses Supabase for PostgreSQL database access: ```python theme={null} 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. Explore the database architecture ## Development Workflow ### Starting the Server ```bash theme={null} 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](http://localhost:8000/docs) * **ReDoc**: [http://localhost:8000/redoc](http://localhost:8000/redoc) ### Hot Reload Development server automatically reloads on file changes. ### Health Check ```bash theme={null} curl http://localhost:8000/health # Response: {"status": "healthy"} ``` ## API Patterns ### Request/Response Models All endpoints use Pydantic models for validation: ```python theme={null} 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: ```python theme={null} 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: ```python theme={null} @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. Learn about performance optimization ### Background Tasks Long-running operations use background tasks: ```python theme={null} 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: ```python theme={null} 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: ```bash theme={null} 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 Learn about JWT authentication Explore all API routers Understand core services Database architecture ## Resources * [FastAPI Documentation](https://fastapi.tiangolo.com) * [Pydantic Documentation](https://docs.pydantic.dev) * [Uvicorn Documentation](https://www.uvicorn.org) * [Supabase Python Client](https://supabase.com/docs/reference/python/introduction)