Architecture Overview¶

CalcBridge is a multi-tenant Excel calculation platform designed for enterprise financial services. This section provides comprehensive technical documentation of the system architecture.

Technology Stack¶

High-Level Architecture¶

graph TB
    subgraph Clients["Clients"]
        WEB["Web App<br/>(Next.js 14)"]
        API_CLIENT["API Clients"]
    end

    subgraph LoadBalancer["Load Balancer"]
        LB["NGINX / ALB"]
    end

    subgraph APILayer["API Layer"]
        FASTAPI["FastAPI<br/>(Async Python)"]
    end

    subgraph CoreServices["Core Services"]
        CALC["Calculation Engine"]
        PARSER["Formula Parser"]
        AUTH["Auth Service"]
        TENANT["Tenant Service"]
    end

    subgraph Workers["Worker Layer"]
        CELERY["Celery Workers"]
    end

    subgraph DataLayer["Data Layer"]
        PG["PostgreSQL 16<br/>(RLS Enabled)"]
        VALKEY["Valkey<br/>(Cache + Rate Limits)"]
    end

    WEB --> LB
    API_CLIENT --> LB
    LB --> FASTAPI
    FASTAPI --> CALC
    FASTAPI --> AUTH
    FASTAPI --> TENANT
    CALC --> PARSER
    FASTAPI --> CELERY
    FASTAPI --> PG
    FASTAPI --> VALKEY
    CELERY --> PG
    CELERY --> VALKEY

Key Architectural Decisions¶

1. AST-Based Formula Parsing¶

Decision: Use Abstract Syntax Tree (AST) parsing instead of dynamic code execution.

Rationale: - Security: Prevents code injection attacks - no arbitrary code execution - Performance: Compile once, execute many times - Extensibility: Easy to add new functions - Debugging: Better error messages with source location

2. Row-Level Security for Multi-Tenancy¶

Decision: Implement tenant isolation at the database level using PostgreSQL RLS.

Rationale: - Defense in Depth: Even application bugs cannot leak tenant data - Performance: PostgreSQL optimizes RLS policies - Audit: Database-level isolation simplifies compliance

3. JSONB for Flexible Data Storage¶

Decision: Store Excel cell data and metadata in PostgreSQL JSONB columns.

Rationale: - Schema Flexibility: Handle varying Excel structures - Query Performance: JSONB indexes enable efficient queries - Type Preservation: Maintain original Excel data types

4. Vectorized Calculations¶

Decision: Process calculations using pandas/numpy vectorized operations.

Rationale: - Performance: 100x faster than row-by-row iteration - Memory Efficiency: Batch operations reduce overhead - Financial Precision: Decimal support for monetary calculations

Architecture Deep-Dives¶

Performance Characteristics¶

Directory Structure¶

calcbridge/
├── src/
│   ├── api/                 # FastAPI routes and middleware
│   ├── core/                # Auth, tenant context, config
│   ├── calculations/        # Formula parser and engine
│   │   ├── parser/          # Tokenizer, AST nodes, translator
│   │   ├── functions/       # Vectorized Excel functions
│   │   └── services/        # Calculation orchestration
│   ├── db/                  # SQLAlchemy models and repos
│   ├── services/            # Business logic services
│   └── workers/             # Celery task definitions
├── db/migrations/           # Flyway SQL migrations
├── frontend/                # Next.js application
├── config/                  # Prometheus, Grafana configs
└── tests/                   # Comprehensive test suite

Integration Points¶

External Systems¶

Internal Services¶

Next Steps¶

1. System Design - Detailed component architecture
2. Data Flow - Excel processing pipeline
3. Formula Engine - Safe formula evaluation
4. Multi-Tenancy - Tenant isolation patterns
5. Security - Authentication and encryption