# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

REmodel is a Python calculation engine + FastAPI backend + Next.js frontend for Indian renewable energy (Solar + Wind + BESS) project finance modeling. It computes optimal flat tariff and full 25-year project financials for hybrid RTC RE projects.

## Prerequisites

- Python ≥ 3.12, Poetry ≥ 2.0
- Node.js ≥ 20, pnpm ≥ 10
- Docker (for Redis)

## Common Commands

```bash
# Full stack
make setup    # Install all deps (Poetry + pnpm)
make dev      # Start Redis, API, Arq worker, web dev server
make test    # Run pytest + jest
make lint    # ruff + mypy + tsc + eslint
make clean   # Remove build artefacts

# Single test (Python)
cd packages/engine && poetry run pytest tests/unit/test_xxx.py::test_name -v

# Individual packages
cd packages/engine && poetry run mypy src/
cd packages/api && poetry run uvicorn remodel_api.main:app --reload --port 8000
cd packages/web && pnpm dev
```

## Architecture

```
packages/web (Next.js App Router)
         │ REST + SSE
packages/api (FastAPI + Arq + SQLite)
         │ Python import
packages/engine (Pydantic + NumPy + SciPy)
```

## Key Context

- **Domain**: Indian RE bidding — PPA tariff bids, SECI/DISCOM auctions, 15-20% target equity IRR, D:E ≤ 75:25, DSCR ≥ 1.20
- **Hybrid RTC**: Solar + Wind + BESS (battery firming), 57.64% RTC CUF commitment, DSM penalties
- **Tax**: Section 115BAA → 22% + cess = 25.17%
- **Currency**: INR Crore (Cr) = 10 million, Lakh = 100 thousand

## Working Agreements

- Always read PROJECT.md and active SPRINT_XX.md at session start
- One task per commit, format: `[S2-T03] Implement IDC fixed-point solver`
- Excel parity is sacred — debug diffs, don't bump tolerances
- Type strict (mypy strict), no Any except at JSON boundaries
- Pydantic for all I/O, no raw dicts crossing module boundaries
- No magic numbers — defaults in catalog/defaults.py
- Comments explain WHY, not WHAT

## Engine Structure

Key modules (read in this order for domain understanding):

1. **schemas/** — Pydantic models (single source of truth)
2. **solver/** — Three nested iterations: tariff (brentq) → debt sizing → IDC
3. **generation/** — Solar, wind, BESS simulation
4. **dispatch/** — Hybrid RTC scheduling, MCP settlement
5. **commercial/** — PPA revenue, DSM, charges, losses
6. **capex/** — CostItem catalog + IDC calculation
7. **financial/** — P&L, cash flow, balance sheet
8. **debt/** — Sizing, sculpting, schedule, DSCR compliance
9. **irr/** — Equity/project IRR metrics

## API Structure

- **routers/** — REST endpoints (scenarios, sensitivities, templates)
- **workers/** — Arq async tasks (run via Redis queue)
- **db/** — SQLAlchemy models + migrations
- **main.py** — FastAPI app factory