Developer Guide¶

Welcome to the CalcBridge Developer Guide. This documentation provides everything you need to contribute to CalcBridge, extend its functionality, or integrate it with other systems.

Who This Is For¶

Core Contributors

Engineers adding features or fixing bugs in CalcBridge

Integration Developers

Teams building integrations with CalcBridge APIs

Function Authors

Adding new Excel functions to the calculation engine

DevOps Engineers

Deploying and operating CalcBridge in production

Development Environment Setup¶

Prerequisites¶

Requirement	Version	Purpose
Python	3.11+	Backend runtime
Docker	24+	Container runtime
Docker Compose	2.20+	Local development stack
Node.js	18+	Frontend development
PostgreSQL	16	Database (via Docker)
Valkey	8+	Cache (via Docker)

Quick Setup¶

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

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

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

# Copy environment configuration
cp .env.example .env

# Start infrastructure services
docker-compose up -d postgres valkey

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

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

# Verify setup
curl http://localhost:8000/health

IDE Configuration¶

VS CodePyCharm

Recommended extensions:

Python (ms-python.python)
Pylance (ms-python.vscode-pylance)
Ruff (charliermarsh.ruff)
Docker (ms-azuretools.vscode-docker)

.vscode/settings.json

{
  "python.defaultInterpreterPath": ".venv/bin/python",
  "[python]": {
    "editor.formatOnSave": true,
    "editor.defaultFormatter": "charliermarsh.ruff"
  },
  "python.analysis.typeCheckingMode": "basic"
}

Open the project directory
Configure Python interpreter: .venv/bin/python
Enable Ruff plugin for formatting
Set line length to 120 in Editor > Code Style > Python

Project Structure¶

calcbridge/
├── src/                        # Application source code
│   ├── api/                    # FastAPI application
│   │   ├── main.py            # App factory with middleware
│   │   ├── routes/            # API endpoints
│   │   ├── middleware/        # Request processing middleware
│   │   └── dependencies.py    # Dependency injection
│   ├── calculations/           # Calculation engine
│   │   ├── parser/            # Excel formula parser (AST-based)
│   │   ├── functions/         # Vectorized function implementations
│   │   └── services/          # Calculation orchestration
│   ├── core/                   # Core utilities
│   │   ├── config.py          # Environment configuration
│   │   ├── security.py        # JWT and password handling
│   │   └── tenant/            # Multi-tenant context
│   ├── db/                     # Database layer
│   │   ├── models/            # SQLAlchemy ORM models
│   │   ├── repositories/      # Data access layer
│   │   └── session.py         # Connection management
│   ├── services/              # Business logic services
│   └── workers/               # Celery background tasks
├── tests/                      # Test suite
│   ├── unit/                  # Unit tests (no external deps)
│   ├── integration/           # Integration tests (with testcontainers)
│   ├── security/              # Security vulnerability tests
│   └── load/                  # Load testing (Locust)
├── frontend/                   # Next.js frontend
├── db/migrations/             # Flyway SQL migrations
├── config/                    # Infrastructure configs
├── docs-site/                 # Documentation (you are here)
└── scripts/                   # Operations scripts

Quick Links¶

Code Style

Formatting, linting, and naming conventions

Testing

Writing and running tests

Adding Functions

Implementing new Excel functions

Adding Endpoints

Creating new API routes

Deployment

Production deployment guide

Git Workflow

Branching and PR process

Contribution Workflow¶

1. Pick an Issue¶

Browse GitHub Issues for tasks labeled:

good first issue - Suitable for new contributors
help wanted - Community contributions welcome
bug - Bug fixes
enhancement - New features

2. Create a Branch¶

# Sync with main
git checkout main
git pull origin main

# Create feature branch
git checkout -b feature/CB-123-add-xlookup-function

3. Implement and Test¶

# Make your changes
# ...

# Run tests
PYTHONPATH=. pytest tests/ -v

# Check code style
ruff check src/ tests/
ruff format src/ tests/

4. Submit a Pull Request¶

Push your branch to GitHub
Open a pull request against main
Fill out the PR template
Request review from maintainers
Address feedback and iterate

5. Merge¶

Once approved, your PR will be merged by a maintainer.

Getting Help¶

Documentation: You are here
GitHub Issues: Report bugs or request features
Discussions: Ask questions

Tech Stack Summary¶

Layer	Technology	Purpose
API	FastAPI	REST API framework
Database	PostgreSQL 16	Primary data store with JSONB
Cache	Valkey	Redis-compatible caching
Task Queue	Celery	Async background jobs
Frontend	Next.js 14	React-based web UI
Testing	pytest	Test framework with testcontainers
Linting	Ruff	Python linter and formatter
Monitoring	Prometheus + Grafana	Metrics and dashboards
Tracing	OpenTelemetry	Distributed tracing