Architecture

Bizon Platform is designed as a modular, scalable system with clear separation of concerns between components.

System Overview

┌─────────────────────────────────────────────────────────────────┐
│                         Load Balancer                           │
└───────────────────────────┬─────────────────────────────────────┘
                            │
        ┌───────────────────┼───────────────────┐
        ▼                   ▼                   ▼
┌───────────────┐   ┌───────────────┐   ┌───────────────┐
│   React UI    │   │   FastAPI     │   │    Agent      │
│   (nginx)     │   │     API       │   │  (LangGraph)  │
└───────────────┘   └───────┬───────┘   └───────┬───────┘
                            │                   │
                            ▼                   ▼
                    ┌───────────────────────────────────┐
                    │           PostgreSQL              │
                    │   (data + job queue + checkpoints)│
                    └───────────────────────────────────┘
                                    │
                    ┌───────────────┼───────────────┐
                    ▼               ▼               ▼
            ┌───────────┐   ┌───────────┐   ┌───────────┐
            │  Worker 1 │   │  Worker 2 │   │  Worker N │
            └───────────┘   └───────────┘   └───────────┘

Core Components

API Server (FastAPI)

The central API server handles:

• RESTful endpoints for all platform operations
• Authentication (JWT + API keys + OAuth)
• Request validation and authorization
• Scheduler process (APScheduler) for cron jobs

Key directories:

• bizon_platform/api/ - Routes and schemas
• bizon_platform/auth/ - Authentication and permissions
• bizon_platform/db/ - Database models and sessions

Worker Processes

Workers poll the job queue and execute pipelines:

# Simplified worker loop
while True:
    async with session.begin():
        run = await session.execute(
            select(PipelineRun)
            .where(PipelineRun.status == "pending")
            .with_for_update(skip_locked=True)
            .limit(1)
        )
        if run:
            run.status = "running"
            await execute_pipeline(run)

Key features:

• SELECT FOR UPDATE SKIP LOCKED for safe concurrency
• Configurable polling interval
• Horizontal scaling via docker compose up --scale worker=N

AI Agent (LangGraph)

The agent provides conversational pipeline creation:

• Main agent - Creates pipelines from natural language
• Sandbox agent - Generates custom source code from docs

Architecture:

• PostgreSQL checkpointer for conversation persistence
• SSE streaming for real-time token delivery
• Tool calls for connector discovery and pipeline creation

Database (PostgreSQL)

Single PostgreSQL instance serves multiple purposes:

• Application data (pipelines, users, organizations)
• Job queue (pipeline runs with status tracking)
• LangGraph checkpoints (conversation state)
• Bizon-core cursor storage

Data Flow

Pipeline Execution

1. User creates pipeline via UI/API
2. API validates and encrypts config, stores in DB
3. User triggers run (manual or scheduled)
4. API creates PipelineRun with status="pending"
5. Worker claims run with SELECT FOR UPDATE SKIP LOCKED
6. Worker executes bizon-core pipeline
7. Worker updates run status and stores output
8. UI polls for status updates

Authentication Flow

1. User authenticates (password or OAuth)
2. API issues JWT access + refresh tokens
3. Client includes token in Authorization header
4. API validates token and extracts org context
5. Permission guards check user role
6. Request proceeds if authorized

Storage Architecture

Database Storage

• Encrypted configs - Pipeline and connector configs use Fernet encryption
• Soft deletes - API keys use revoked_at for audit trail
• Indexes - Optimized for common query patterns

File Storage

Pipeline outputs and custom sources support pluggable backends:

Backend	Use Case
local	Development, single-node deployments
gcs	Production, multi-node deployments

Security Model

Multi-tenancy

• Organizations isolate data completely
• Users belong to organizations via Memberships
• All queries are scoped to the current organization

Permission System

Owner → Admin → Member → Viewer
  ↓        ↓        ↓        ↓
 All    Most     Create    Read
       (no own-    Edit    Only
        ership)

Domain role overrides allow elevated permissions within specific domains without changing org-level role.

Encryption

• At rest - Config fields encrypted with Fernet (AES-128-CBC + HMAC-SHA256)
• In transit - TLS recommended for production
• Passwords - bcrypt hashed
• API keys - bcrypt hashed, only prefix stored for lookup

Scalability

Horizontal Scaling

Component	Scaling Method
API	Multiple instances behind load balancer
Workers	docker compose up --scale worker=N
Database	Read replicas, connection pooling

Performance Optimizations

• Lazy database engine initialization
• Async SQLAlchemy for non-blocking I/O
• Connection pooling in production
• Indexed queries for common access patterns