Compare household impacts with and without Rhode Island CTC reform.
This calculator models the Rhode Island Child Tax Credit reform proposal, showing how different household configurations would be affected by the CTC implementation. The calculator uses PolicyEngine US's microsimulation model to provide accurate benefit calculations.
Key Features:
- Baseline vs. Reform: Compare household finances with and without RI CTC
- Income Analysis: See how credits change across income levels
- Household Flexibility: Model different family configurations
- RI-Specific: Focused on Rhode Island residents
This project has two main components:
- Backend: FastAPI REST API (Python)
- Frontend: Next.js/React application (TypeScript)
- Legacy: Streamlit app (still available but deprecated)
- Python 3.10+ (Python 3.11 recommended)
- Node.js 21+ (for frontend)
- Windows: Long path support enabled (see Windows Setup)
You need to run both the backend and frontend:
# Navigate to backend directory
cd backend
# Install Python dependencies
pip install -r requirements.txt
# Start the FastAPI server
python -m uvicorn app.main:app --reload --host 0.0.0.0 --port 8080Backend will be available at:
- API: http://localhost:8080
- API Docs: http://localhost:8080/docs
Note: First startup may take 30-60 seconds to download and load the RI microsimulation dataset from HuggingFace.
# Navigate to frontend directory
cd frontend
# Install Node.js dependencies
npm install
# Start the Next.js dev server
npm run devFrontend will be available at:
The original Streamlit version is still available but no longer maintained:
# Install dependencies
pip install -r requirements.txt
# Run the Streamlit app
streamlit run app.pyThe app will open at http://localhost:8501
Based on PolicyEngine US PR #6643:
- Eligibility: Children under age 18
- Credit Structure: Non-refundable child tax credit
- Phase-out: Based on AGI (Adjusted Gross Income)
- State: Rhode Island residents only
On Windows, you need to enable long path support for the PolicyEngine dataset:
-
Enable Long Paths in Windows (requires admin):
# Run PowerShell as Administrator New-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem" -Name "LongPathsEnabled" -Value 1 -PropertyType DWORD -Force
-
Enable Long Paths in Git (if cloning the repo):
git config --system core.longpaths true -
Restart your terminal after making these changes.
Without long path support, you'll get ModuleNotFoundError when importing policyengine_us.
.
├── backend/ # FastAPI backend
│ ├── app/
│ │ ├── main.py # FastAPI application
│ │ ├── api/
│ │ │ ├── routes/ # API endpoints
│ │ │ └── models/ # Request/response models
│ │ ├── core/
│ │ │ ├── config.py # Configuration
│ │ │ └── dataset.py # Dataset manager
│ │ └── services/
│ │ └── calculator.py # Business logic
│ ├── requirements.txt # Python dependencies
│ └── Dockerfile # Production deployment
├── frontend/ # Next.js frontend
│ ├── app/
│ │ ├── layout.tsx # Root layout
│ │ ├── page.tsx # Main page
│ │ └── globals.css # Global styles
│ ├── components/ # React components
│ │ ├── HouseholdForm.tsx
│ │ ├── ImpactAnalysis.tsx
│ │ └── AggregateImpact.tsx
│ ├── hooks/ # React hooks
│ ├── lib/
│ │ ├── api.ts # API client
│ │ └── types.ts # TypeScript types
│ ├── package.json
│ └── Dockerfile # Production deployment
├── ri_ctc_calc/ # Calculator package (shared)
│ ├── __init__.py
│ └── calculations/ # Calculation modules
│ ├── __init__.py
│ ├── household.py # Household building
│ ├── ctc.py # CTC calculations
│ ├── microsimulation.py # Aggregate calculations
│ └── reforms.py # Reform definitions
├── app.py # Legacy Streamlit app
├── requirements.txt # Python dependencies (legacy)
└── tests/ # Test files
The backend provides the following REST API endpoints:
Calculate household-specific impact across income range.
Request:
{
"age_head": 35,
"age_spouse": null,
"dependent_ages": [5, 8],
"income": 50000,
"reform_params": {
"ri_ctc_amount": 1000,
"phase_out_start": 200000,
"phase_out_rate": 0.05
}
}Calculate statewide impact using RI microsimulation dataset.
Note: This endpoint takes ~90 seconds to compute due to microsimulation calculations.
Request:
{
"reform_params": {
"ri_ctc_amount": 1000,
"phase_out_start": 200000,
"phase_out_rate": 0.05
}
}Health check endpoint.
Get RI dataset summary statistics.
Interactive API Documentation: http://localhost:8080/docs
Problem: Frontend shows "Network Error" when calculating aggregate impact.
Cause: The aggregate calculation takes ~90 seconds, which was exceeding the default 30-second timeout.
Solution: The timeout has been increased to 120 seconds in frontend/lib/api.ts:27. If you still see this error:
- Check that the backend is running on port 8080
- Check backend logs for errors
- The first calculation may take longer (~2 minutes) as the dataset loads
Problem: Backend fails to start with module not found error.
Cause: Windows long path limit preventing proper package installation.
Solution: See Windows Setup section above.
Problem: Error: Address already in use
Solution:
# Windows - Find and kill process on port 8080
netstat -ano | findstr :8080
taskkill /PID <PID> /F
# Or use a different port
python -m uvicorn app.main:app --reload --port 8081Problem: Frontend shows connection errors.
Check:
- Backend is running: http://localhost:8080/api/health
- CORS is configured correctly (already set up for localhost:3000)
- Firewall isn't blocking the ports
# Backend tests
cd backend
pytest tests/
# Frontend tests (if available)
cd frontend
npm test# Python
black .
isort .
# JavaScript/TypeScript
cd frontend
npm run lintBuilt with:
- Backend:
- FastAPI: Modern Python web framework
- PolicyEngine US: Open-source tax-benefit microsimulation
- Pydantic: Data validation
- Uvicorn: ASGI server
- Frontend:
- Next.js 14: React framework
- React Query: Data fetching and caching
- Recharts: Data visualization
- Tailwind CSS: Styling
- TypeScript: Type safety
- Legacy:
Open source - see PolicyEngine US license for underlying calculations.
Calculations powered by PolicyEngine US