Skip to content

Getting Started with CalcBridge

Welcome to CalcBridge, the enterprise Excel calculation platform built for financial professionals. This guide will walk you through everything you need to start automating your compliance testing and trade analysis.

What You'll Achieve

By the end of this guide, you'll have:

  • A fully configured CalcBridge environment
  • Your first workbook uploaded and parsed
  • Compliance tests running automatically
  • Understanding of the platform architecture

Prerequisites

Before you begin, ensure you have the following tools installed:

Requirement Version Purpose Installation
Python 3.11+ Backend API and calculations python.org
Docker 24.0+ PostgreSQL and Valkey containers docker.com
Docker Compose 2.20+ Service orchestration Included with Docker Desktop
Node.js 18+ Frontend development (optional) nodejs.org
Git 2.30+ Source control git-scm.com

Version Check Commands

python3 --version   # Should show 3.11.x or higher
docker --version    # Should show 24.x or higher
docker compose version  # Should show 2.20.x or higher
node --version      # Should show 18.x or higher (if using frontend)

Quick Navigation

Choose your path based on your goals:

  • 5-Minute Quickstart

    Get CalcBridge running in minutes with our streamlined quickstart guide.

    Quickstart

  • Full Installation

    Complete installation guide for development environments with all options.

    Installation

  • Your First Workbook

    Learn how to upload, parse, and work with Excel files in CalcBridge.

    First Workbook

  • Configuration

    Environment variables, security settings, and advanced configuration options.

    Configuration

Architecture Overview

CalcBridge is built on a modern, scalable architecture designed for financial workloads:

flowchart TB
    subgraph Client["Client Layer"]
        UI["Web UI<br/>(Next.js)"]
        API_CLIENT["API Clients<br/>(REST/SDK)"]
    end

    subgraph API["API Layer"]
        FASTAPI["FastAPI Server<br/>(Port 8000)"]
        AUTH["JWT + API Key<br/>Authentication"]
        RATE["Rate Limiting<br/>(Tier-based)"]
    end

    subgraph Workers["Background Workers"]
        CELERY_PARSE["Parse Worker<br/>(Excel processing)"]
        CELERY_CALC["Calculation Worker<br/>(Formula evaluation)"]
        CELERY_BEAT["Scheduler<br/>(Periodic tasks)"]
    end

    subgraph Data["Data Layer"]
        PG[("PostgreSQL 16<br/>+ RLS")]
        VALKEY[("Valkey<br/>(Redis-compatible)")]
    end

    subgraph Observability["Observability"]
        PROM["Prometheus"]
        GRAFANA["Grafana"]
        OTEL["OpenTelemetry"]
    end

    UI --> FASTAPI
    API_CLIENT --> FASTAPI
    FASTAPI --> AUTH
    AUTH --> RATE
    RATE --> PG
    RATE --> VALKEY
    FASTAPI --> CELERY_PARSE
    FASTAPI --> CELERY_CALC
    CELERY_BEAT --> CELERY_PARSE
    CELERY_PARSE --> PG
    CELERY_CALC --> PG
    CELERY_PARSE --> VALKEY
    FASTAPI --> PROM
    PROM --> GRAFANA
    FASTAPI --> OTEL

    style FASTAPI fill:#3B82F6,stroke:#1E40AF,color:#fff
    style PG fill:#336791,stroke:#1E3A5F,color:#fff
    style VALKEY fill:#DC382D,stroke:#8B0000,color:#fff

Key Components

Component Technology Purpose
API Server FastAPI REST API with OpenAPI documentation
Database PostgreSQL 16 Data storage with Row-Level Security
Cache Valkey Session management and rate limiting
Task Queue Celery Async Excel parsing and calculations
Frontend Next.js Modern React-based web interface

Core Concepts

Multi-Tenancy

CalcBridge is designed from the ground up for multi-tenant deployments:

  • Complete Data Isolation: PostgreSQL Row-Level Security ensures tenants can never access each other's data
  • Tenant-scoped API Keys: All API operations are automatically scoped to the authenticated tenant
  • Subscription Tiers: Free, Starter, Professional, and Enterprise with different rate limits

Workbooks and Sheets

The fundamental data model mirrors Excel:

Tenant
  └── Workbooks (Excel files)
        └── Sheets (individual tabs)
              └── Data Rows (JSONB storage)

Formula Engine

CalcBridge includes a production-grade Excel formula parser:

  • 50+ Functions: VLOOKUP, XLOOKUP, SUMIFS, IF/IFS, and more
  • Safe Execution: AST-based parsing with no arbitrary code execution
  • Vectorized: 100x faster than row-by-row Excel processing
  • Cross-Sheet: Handles references across multiple sheets

Typical Workflow

sequenceDiagram
    participant User
    participant CalcBridge
    participant Database

    User->>CalcBridge: 1. Upload Excel workbook
    CalcBridge->>CalcBridge: 2. Parse and validate
    CalcBridge->>Database: 3. Store sheets and data
    CalcBridge-->>User: 4. Workbook ready

    User->>CalcBridge: 5. Configure compliance tests
    CalcBridge->>Database: 6. Run calculations
    CalcBridge-->>User: 7. Test results + cushion analysis

    User->>CalcBridge: 8. Create what-if scenario
    CalcBridge->>CalcBridge: 9. Simulate trade impact
    CalcBridge-->>User: 10. Before/after comparison

Next Steps

  1. Quickstart - Get running in 5 minutes
  2. Full Installation - Complete development setup
  3. Your First Workbook - Upload and explore data
  4. Configuration - Environment and security settings

Getting Help

Need Help?