Skip to main content

​
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

Authentication Details

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

CRM Architecture

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

Processing Pipeline

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

Agentic Architecture

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

Data Flow

Request/response lifecycle

Auth Flow

Authentication patterns

CRM System

CRM architecture

Agent Pool

Performance optimization

File Processing

Document pipeline

Agentic System

Multi-agent design