5-Minute Quickstart¶

Get CalcBridge running and execute your first compliance test in just 5 minutes. This guide covers the fastest path to a working environment.

Prerequisites

Docker and Docker Compose installed
Git installed
5 minutes of your time

Step 1: Clone and Start Services¶

Clone the repository and start the infrastructure with a single command:

# Clone the repository
git clone https://github.com/InsightCapital/calcbridge.git
cd calcbridge

# Start PostgreSQL and Valkey
docker compose up -d postgres valkey

# Wait for services to be healthy (about 10 seconds)
docker compose ps

Expected Output

NAME                  STATUS          PORTS
calcbridge-postgres   Up (healthy)    0.0.0.0:5433->5432/tcp
calcbridge-valkey     Up (healthy)    0.0.0.0:6380->6379/tcp

Step 2: Set Up Python Environment¶

Create a virtual environment and install dependencies:

# Create virtual environment
python3 -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies
pip install -e ".[dev,test]"

# Copy environment file
cp .env.example .env

Step 3: Initialize the Database¶

Run the database migrations to set up the schema:

# Apply all migrations
for migration in db/migrations/V*.sql; do
  PGPASSWORD=calcbridge_dev psql -h localhost -p 5433 -U calcbridge -d calcbridge -f "$migration"
done

Alternative: Single Command

# Using docker exec
docker exec -i calcbridge-postgres psql -U calcbridge -d calcbridge < db/migrations/V001__initial_schema.sql

Step 4: Start the API Server¶

Launch the FastAPI server with hot reload:

# Start the API server
PYTHONPATH=. uvicorn src.api.main:app --reload --port 8000

Server Running

You should see:

INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
INFO:     Started reloader process

Open http://localhost:8000/docs to see the API documentation.

Step 5: Create Your Account¶

Register a new user and organization:

cURLHTTPiePython

curl -X POST http://localhost:8000/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "analyst@example.com",
    "password": "SecurePass123!",
    "full_name": "Jane Analyst",
    "organization_name": "Acme Capital"
  }'

http POST localhost:8000/api/v1/auth/register \
  email=analyst@example.com \
  password=SecurePass123! \
  full_name="Jane Analyst" \
  organization_name="Acme Capital"

import requests

response = requests.post(
    "http://localhost:8000/api/v1/auth/register",
    json={
        "email": "analyst@example.com",
        "password": "SecurePass123!",
        "full_name": "Jane Analyst",
        "organization_name": "Acme Capital"
    }
)
tokens = response.json()
print(f"Access Token: {tokens['access_token'][:50]}...")

Response

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type": "bearer"
}

Save your access token for the next steps:

export TOKEN="eyJhbGciOiJIUzI1NiIs..."

Step 6: Upload Your First Workbook¶

Upload an Excel file with your portfolio data:

cURLPython

curl -X POST http://localhost:8000/api/v1/workbooks/upload \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@sample_portfolio.xlsx"

import requests

with open("sample_portfolio.xlsx", "rb") as f:
    response = requests.post(
        "http://localhost:8000/api/v1/workbooks/upload",
        headers={"Authorization": f"Bearer {TOKEN}"},
        files={"file": f}
    )

workbook = response.json()
print(f"Workbook ID: {workbook['id']}")
print(f"Sheets: {workbook['sheet_count']}")
print(f"Rows: {workbook['row_count']}")

Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "sample_portfolio",
  "status": "ready",
  "sheet_count": 3,
  "row_count": 1250,
  "original_filename": "sample_portfolio.xlsx"
}

Step 7: Run a Quick Compliance Test¶

Evaluate a formula to test your data:

curl -X POST http://localhost:8000/api/v1/calculations/evaluate \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "formula": "=SUM(1, 2, 3, 4, 5)",
    "context": {}
  }'

Response

{
  "result": 15,
  "result_type": "number",
  "execution_time_ms": 2.5
}

Step 8: View Your Data¶

List the sheets in your workbook and fetch data:

# Get workbook details
curl -H "Authorization: Bearer $TOKEN" \
  http://localhost:8000/api/v1/workbooks/$WORKBOOK_ID

# List sheets
curl -H "Authorization: Bearer $TOKEN" \
  http://localhost:8000/api/v1/workbooks/$WORKBOOK_ID/sheets

# Get sheet data (first 100 rows)
curl -H "Authorization: Bearer $TOKEN" \
  "http://localhost:8000/api/v1/workbooks/$WORKBOOK_ID/sheets/Holdings/data?page=1&page_size=100"

What's Next?¶

Congratulations! You've successfully set up CalcBridge and uploaded your first workbook. Here's what to explore next:

Compliance Testing

Learn how to configure and run automated compliance test suites.

Compliance Guide
What-If Scenarios

Simulate trades and see compliance impact before execution.

What-If Guide
Workbook Deep Dive

Learn about Excel parsing, formulas, and data management.

First Workbook
API Reference

Explore the complete REST API documentation.

API Docs

Quick Reference¶

Default Ports¶

Service	Port	URL
API Server	8000	http://localhost:8000
API Docs	8000	http://localhost:8000/docs
PostgreSQL	5433	localhost:5433
Valkey	6380	localhost:6380
Frontend	3002	http://localhost:3002

Useful Commands¶

# Check service health
curl http://localhost:8000/health

# View API documentation
open http://localhost:8000/docs

# Stop all services
docker compose down

# View logs
docker compose logs -f api

Troubleshooting¶

Common Issues

Port already in use?

# Find process using port 8000
lsof -i :8000
# Kill it or use a different port
PYTHONPATH=. uvicorn src.api.main:app --reload --port 8001

Database connection failed?

# Check if PostgreSQL is running
docker compose ps postgres
# Restart if needed
docker compose restart postgres

Import errors?

# Make sure PYTHONPATH is set
export PYTHONPATH=.
# Or run with prefix
PYTHONPATH=. python -c "from src.api.main import app; print('OK')"

For more detailed troubleshooting, see the Troubleshooting Guide.