GiveCalc

Calculate how charitable giving affects your taxes. Powered by PolicyEngine.

Overview

GiveCalc helps donors understand the true cost of their charitable contributions by calculating federal and state tax impacts. It uses PolicyEngine-US for accurate microsimulation of the US tax and benefit system.

Features:

• Calculate tax savings for any donation amount
• Find the donation needed to achieve a target net income reduction
• Support for all 50 states + DC (including NYC local taxes)
• State-specific charitable tax credit programs (AZ, MS, VT, CO, NH)
• Interactive charts showing tax impact across donation levels

Architecture

givecalc/
├── givecalc/           # Core Python calculation package
├── api/                # FastAPI backend
├── frontend/           # React + Vite + TypeScript frontend
├── ui/                 # Legacy Streamlit UI components
└── app.py              # Legacy Streamlit entry point

Development

Prerequisites

• Python 3.11+
• Node.js 20+
• uv (recommended for Python)

Quick Start

# Install everything
make install-all

# Start the API (terminal 1)
make api

# Start the frontend (terminal 2)
make frontend

• API: http://localhost:8000 (docs at /docs)
• Frontend: http://localhost:5173

Legacy Streamlit App

make run-streamlit

Testing

make test           # Run all tests
make test-cov       # Run with coverage
make perf           # Run performance benchmarks

Formatting

make format         # Format Python and JS/TS code

Deployment

Frontend (Vercel)

The frontend is auto-deployed to Vercel on push to main.

• Production: https://givecalc.org

Backend (Google Cloud Run)

The backend is deployed via Cloud Build trigger in GCP Console:

1. Go to Cloud Build Triggers
2. Find the givecalc trigger
3. Click "Run" to manually deploy, or push to main to auto-deploy

Manual deployment:

cd api
gcloud builds submit --tag gcr.io/PROJECT_ID/givecalc
gcloud run deploy givecalc \
  --image gcr.io/PROJECT_ID/givecalc \
  --platform managed \
  --region europe-west1 \
  --allow-unauthenticated

• Production API: https://givecalc-578039519715.europe-west1.run.app

Environment Variables

Frontend (build-time):

• VITE_API_URL: Backend API URL

Backend:

• PORT: Server port (default: 8080, set by Cloud Run)

API Endpoints

Endpoint	Method	Description
/api/states	GET	List supported states
/api/tax-programs/{state}	GET	Get tax program info for a state
/api/calculate	POST	Calculate donation tax impact
/api/target-donation	POST	Find donation for target reduction
/api/health	GET	Health check

License

MIT

Contributing

See CLAUDE.md for development guidelines.