> ## 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. # System Overview > Complete system architecture and design patterns for Zarna ## System Architecture Zarna is built as a **monorepo** with three main applications working together to deliver a comprehensive private equity workflow platform. ## High-Level Architecture ``` ┌─────────────────────── USER LAYER ───────────────────────┐ │ │ │ ┌──────────────┐ ┌───────────────────┐ │ │ │ Frontend │ │ Marketing Site │ │ │ │ React + Vite │ │ (Next.js) │ │ │ │ │ │ │ │ │ │ Port: 3000 │ │ Port: 3001 │ │ │ └──────┬───────┘ └───────────────────┘ │ │ │ │ └─────────┼────────────────────────────────────────────────┘ │ │ REST API (HTTPS/JSON) │ WebSocket (Real-time) │ ┌─────────▼────────── APPLICATION LAYER ───────────────────┐ │ │ │ Zarna Backend │ │ (FastAPI + Python) │ │ │ │ ┌────────────────────────────────────────────────────┐ │ │ │ 25+ API Routers │ │ │ │ CRM · Files · Email · Calendar · Reports │ │ │ │ Drive · SharePoint · Egnyte · Basecamp · etc. │ │ │ └────────────────────────────────────────────────────┘ │ │ │ │ ┌────────────────────────────────────────────────────┐ │ │ │ Core Services (145+ files) │ │ │ │ • CRM Agent (AI CRM operations) │ │ │ │ • Document Processing (Docling, OCR, AI) │ │ │ │ • Email Agent (Automation) │ │ │ │ • Report Generation (Streaming AI) │ │ │ │ • Agentic Chat (Multi-agent with pool) │ │ │ └────────────────────────────────────────────────────┘ │ │ │ │ Port: 8000 │ └───────────┬──────────────────┬───────────────────────────┘ │ │ │ │ ┌───────────▼───────┐ ┌──────▼────────────────────────────┐ │ │ │ │ │ Supabase │ │ External Services │ │ (PostgreSQL) │ │ │ │ │ │ • Anthropic Claude (AI) │ │ • CRM Tables │ │ • OpenAI (AI) │ │ • Auth │ │ • Composio (OAuth) │ │ • Storage │ │ • Exa (Sourcing) │ │ • Real-time │ │ • Google Drive │ │ • RLS Policies │ │ • Microsoft Graph │ │ │ │ • Egnyte │ └───────────────────┘ └───────────────────────────────────┘ ``` ## Data Flow ### Request Lifecycle ``` 1. User Interaction (Frontend) │ ├─> User clicks "Create Company" │ ↓ 2. Frontend Request │ ├─> React component calls API service ├─> Includes JWT token in Authorization header │ ↓ 3. API Gateway (Backend) │ ├─> CORS Middleware validates origin ├─> JWT Middleware authenticates user ├─> Extracts user_id and firm_id │ ↓ 4. Router Layer │ ├─> Route matches /api/companies ├─> Pydantic validates request body ├─> Calls service layer │ ↓ 5. Service Layer │ ├─> Business logic execution ├─> May call AI services (Claude, etc.) ├─> Prepares database query │ ↓ 6. Database Layer │ ├─> Supabase client executes query ├─> RLS policies enforce firm isolation ├─> Returns data │ ↓ 7. Response Assembly │ ├─> Service formats response ├─> Router returns JSON ├─> Middleware adds headers │ ↓ 8. Frontend Update │ ├─> React state updated ├─> UI re-renders └─> Success toast shown ``` ## Core Subsystems ### 1. Authentication System ``` ┌─────────────┐ │ User │ │ Login │ └──────┬──────┘ │ ↓ ┌──────────────┐ │ Supabase │ │ Auth │ └──────┬───────┘ │ ↓ ┌──────────────┐ │ JWT Token │ │ Generated │ └──────┬───────┘ │ ↓ ┌──────────────┐ │ Frontend │ │ Stores │ │ Token │ └──────────────┘ ``` **Key Components**: * Supabase Auth for user management * JWT tokens for API authentication * Refresh token mechanism * Row Level Security for data isolation See the complete authentication flow ### 2. CRM System The CRM is the core of Zarna: **Data Model**: * **Companies**: Primary entities * **Contacts**: People at companies * **Deals**: Opportunities and transactions * **Interactions**: Meetings, calls, emails * **Financials**: Financial records * **Notes**: Unstructured notes **Features**: * Relationship management * Activity tracking * Pipeline visualization * AI-powered insights Explore the CRM system design ### 3. Document Processing Pipeline ``` ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ Upload │ -> │ Docling │ -> │ OCR │ -> │ AI │ │ │ │ Extract │ │ (if scan)│ │ Analysis │ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │ ↓ ┌──────────┐ │ Store │ │ JSON │ └──────────┘ ``` **Technologies**: * **Docling**: Primary extraction engine * **EasyOCR**: Scanned document processing * **PDFPlumber**: Fallback PDF processing * **Claude AI**: Post-processing and analysis See the document processing architecture ### 4. Agentic System Multi-agent AI system with specialization: **Agent Types**: * **Manager Agent**: Coordinates other agents * **Data Retrieval Agent**: Queries database * **Analysis Agent**: Performs calculations * **Web Search Agent**: External research * **Report Writing Agent**: Generates reports **Key Features**: * Parallel agent execution * Tool use capabilities * Conversation memory * Agent pool for performance Explore the multi-agent system ### 5. Integration Layer Connects to external services: **OAuth Integrations** (via Composio): * Gmail/Google Workspace * Outlook/Microsoft 365 * Google Drive * Google Calendar **Direct Integrations**: * SharePoint * Egnyte * Basecamp **AI Services**: * Anthropic Claude * OpenAI * AutoGen * Exa (sourcing) ## Deployment Architecture ### Development ``` Local Machine ├── Frontend: localhost:3000 (Vite dev server) ├── Backend: localhost:8000 (Uvicorn with reload) └── Database: cloud.supabase.co (shared dev) ``` ### Production ``` Cloud Infrastructure ├── Frontend: Vercel/Netlify │ ├── CDN distribution │ ├── Automatic SSL │ └── Edge caching │ ├── Backend: Railway/Render │ ├── Container deployment │ ├── Auto-scaling │ ├── Health checks │ └── Environment secrets │ └── Database: Supabase Production ├── PostgreSQL cluster ├── Automatic backups ├── Point-in-time recovery └── Connection pooling ``` ## Security Architecture ### Multi-Layer Security ``` ┌─────────────── Layer 1: Network ──────────────┐ │ • HTTPS/TLS encryption │ │ • CORS policies │ │ • Rate limiting │ └───────────────────┬───────────────────────────┘ │ ┌─────────────── Layer 2: Authentication ───────┐ │ • JWT token validation │ │ • Token expiration (24h) │ │ • Refresh token rotation │ └───────────────────┬───────────────────────────┘ │ ┌─────────────── Layer 3: Authorization ────────┐ │ • Role-based access control │ │ • Firm-level data isolation │ │ • Row Level Security (RLS) │ └───────────────────┬───────────────────────────┘ │ ┌─────────────── Layer 4: Data ─────────────────┐ │ • Encrypted at rest │ │ • Encrypted in transit │ │ • Audit logging │ │ • Sensitive field encryption │ └───────────────────────────────────────────────┘ ``` ## Performance Optimizations ### Frontend * **Code Splitting**: Lazy-loaded routes * **Tree Shaking**: Remove unused code * **Image Optimization**: WebP, lazy loading * **Bundle Analysis**: Optimize bundle size * **Caching**: Service worker (coming soon) ### Backend * **Agent Pools**: Eliminate cold starts (5-11s savings) * **Database Indexing**: Fast queries * **Connection Pooling**: Reuse connections * **Async I/O**: Non-blocking operations * **Response Streaming**: Incremental delivery ### Database * **Indexes**: Strategic column indexing * **Partitioning**: Time-based (coming soon) * **Materialized Views**: Pre-computed aggregations * **Read Replicas**: Separate read/write (coming soon) ## Scalability ### Horizontal Scaling ``` ┌─────────────────────────────────────────┐ │ Load Balancer │ └───────┬─────────┬─────────┬─────────────┘ │ │ │ ┌────▼───┐ ┌──▼────┐ ┌──▼────┐ │Backend │ │Backend│ │Backend│ │ 1 │ │ 2 │ │ 3 │ └────┬───┘ └───┬───┘ └───┬───┘ │ │ │ └─────────┼─────────┘ │ ┌──────▼──────┐ │ Database │ │ Cluster │ └─────────────┘ ``` ### Vertical Scaling * Increase container resources * Optimize database queries * Add Redis caching * Implement CDN ## Monitoring & Observability ### Application Metrics * Request rate, latency, errors * Agent pool health * Database query performance * AI service usage ### Infrastructure Metrics * CPU, memory, disk usage * Network throughput * Container health * Database connections ### Business Metrics * Active users * API calls per feature * Document processing volume * Report generation count ## Disaster Recovery ### Backup Strategy * **Database**: Daily automated backups (Supabase) * **Files**: S3-compatible storage with versioning * **Code**: Git version control * **Configurations**: Environment variable backups ### Recovery Plan * **RTO** (Recovery Time Objective): \< 1 hour * **RPO** (Recovery Point Objective): \< 1 hour * **Backup Retention**: 30 days ## Next Steps Request/response lifecycle Authentication patterns CRM architecture Performance optimization Document pipeline Multi-agent design