From 0d7cf4a45441e3447e6cc89f642d0d30d92ad233 Mon Sep 17 00:00:00 2001 From: Mannu Date: Thu, 7 May 2026 02:03:45 +0530 Subject: [PATCH] Project spec --- PROJECT.md | 214 +++++ RE_Financial_Modeling_Platform PRD.md | 1074 +++++++++++++++++++++++++ sprints/.DS_Store | Bin 0 -> 6148 bytes sprints/SPRINT_00.md | 19 + sprints/SPRINT_01.md | 16 + sprints/SPRINT_02.md | 18 + sprints/SPRINT_03.md | 15 + 7 files changed, 1356 insertions(+) create mode 100644 PROJECT.md create mode 100644 RE_Financial_Modeling_Platform PRD.md create mode 100644 sprints/.DS_Store create mode 100644 sprints/SPRINT_00.md create mode 100644 sprints/SPRINT_01.md create mode 100644 sprints/SPRINT_02.md create mode 100644 sprints/SPRINT_03.md diff --git a/PROJECT.md b/PROJECT.md new file mode 100644 index 0000000..ccc8565 --- /dev/null +++ b/PROJECT.md @@ -0,0 +1,214 @@ +Project: REmodel +A Python calculation engine + FastAPI backend + Next.js frontend for Indian renewable energy (Solar + Wind + BESS) project finance modeling. Replaces an Excel-macro workflow currently used by senior finance professionals at ReNew Power for bid preparation. +Owner: Manohar (senior finance professional, self-taught dev, India). Builds in evening/weekend hours. +Goal: Compute optimal flat tariff and full 25-year project financials for hybrid RTC RE projects in <30 seconds per scenario, with 50-scenario sensitivity sweeps in <10 minutes. +Vision +Three layers of architecture, in order of foundation to UI: + +Calculation engine (packages/engine) — pip-installable, UI-agnostic Python library. Takes a Pydantic ScenarioInput, returns a Pydantic ScenarioResult. Can be driven by CLI, Jupyter, or the API. This is the durable asset. +API layer (packages/api) — FastAPI + Arq async workers. Schedules scenario runs, persists results to SQLite + Parquet. Exposes REST + SSE for the UI. +Web UI (packages/web) — Next.js 14 App Router + shadcn/ui + Tailwind. Configurable KPI dashboard, scenario wizard, results viewer, sensitivity tornado. + +Domain context (essential reading) + +Indian RE bidding workflow: developer wins a PPA (power purchase agreement) at a tariff (₹/kWh) bid into auctions (SECI, state DISCOMs). Tariff must clear target equity IRR (typically 15-20%) given debt sizing constraints (D:E ≤ 75:25, DSCR ≥ 1.20). +Hybrid RTC project: delivers ~24×7 power from a combination of solar + wind + BESS (battery firming). Contracted at a "RTC CUF" — the developer commits to a specific load factor, e.g., 57.64%. Shortfall triggers DSM (deviation settlement mechanism) penalties. +Construction takes 18-36 months. During this time, debt is drawn progressively, and interest accrues — this is IDC (Interest During Construction). IDC is a major capex item and a primary lever for tariff optimization. +Indian tax regime: Section 115BAA applies → 22% + cess = 25.17%, no MAT, no carry-forward. Book and tax depreciation differ (SLM book vs WDV 40% tax for solar/wind plant), creating deferred tax. +Currency: INR Crore (Cr) = 10 million; Lakh = 100 thousand. Capex typically quoted in Cr/MW or INR/Wp. + +Key architectural decisions (don't relitigate) + +Engine is UI-agnostic. Importable Python package. Web UI is one of three drivers (web, CLI, notebook). No web logic in engine. +CostItem table model, not flat fields. Every capex line item is a record with basis (INR/Wp, Cr/MW, Lakh/Acre, etc.), depreciation class, attribution (solar/wind/BESS/common), and a phasing curve. +Three nested iterations in the solver: tariff (brentq) → debt sizing (fixed-point) → IDC (fixed-point). Each converges in 5-20 iters. +IDC has independent equity and debt drawdown schedules. Equity can bridge (>100% momentarily), debt can replace equity later (negative cum equity delta). Both editable by user. +Two compliance knobs for DSCR: raise tariff OR reshape debt schedule. User chooses; system supports both. +Sync-async hybrid: all scenario runs go through Arq queue (Redis-backed). UI polls/subscribes via SSE. Even single runs use the queue to avoid refactor later. +Storage: SQLite (v0) + Parquet for timeseries. Migrate to Postgres in v2 when multi-user. +DataGrid component is a shared React component used in 5+ places (CostItem table, phasing matrix, equity/debt schedules, opex table, debt repayment %). Build once, well. +Excel parity is the trust gate. Three parity gates at Sprints 2, 3, 4, 7. We don't ship a sprint if its parity gate fails. + +Tech stack (locked) + +Backend: Python 3.12, Poetry, Pydantic v2, FastAPI, Arq, Redis, SQLAlchemy + SQLite, Pandas, NumPy, scipy, numpy_financial, pyarrow, openpyxl +Frontend: Node 20, Next.js 14 App Router, TypeScript strict, shadcn/ui, Tailwind, Recharts, AG Grid Community (for DataGrid), TanStack Query, Zustand (lightweight state) +Tooling: Ruff, mypy strict, pytest, pytest-cov, pre-commit, GitHub Actions, Docker Compose +Deployment target (later): Hetzner. Local-first for v0. + +Repo structure +remodel/ +├── packages/ +│ ├── engine/ Python package +│ │ ├── pyproject.toml +│ │ ├── src/remodel_engine/ +│ │ │ ├── __init__.py +│ │ │ ├── schemas/ Pydantic models (single source of truth) +│ │ │ ├── catalog/ Default values, CostItem catalog, profiles +│ │ │ ├── generation/ solar.py, wind.py, bess_state.py +│ │ │ ├── dispatch/ hybrid_rtc.py, mcp_settlement.py +│ │ │ ├── commercial/ ppa.py, dsm.py, charges.py, losses.py +│ │ │ ├── capex/ cost_items.py, phasing.py, idc.py +│ │ │ ├── financial/ pnl.py, cfs.py, bs.py, depreciation.py, tax.py, working_capital.py +│ │ │ ├── debt/ sizing.py, sculpting.py, schedule.py, compliance.py +│ │ │ ├── irr/ metrics.py +│ │ │ ├── solver/ tariff.py +│ │ │ ├── scenarios/ runner.py, sweep.py +│ │ │ ├── io/ parquet_io.py, excel_export.py +│ │ │ └── cli.py Typer-based CLI +│ │ └── tests/ +│ │ ├── fixtures/ Gold scenarios from user's Excel +│ │ ├── unit/ +│ │ └── integration/ +│ ├── api/ +│ │ ├── pyproject.toml +│ │ └── src/remodel_api/ +│ │ ├── main.py +│ │ ├── routers/ scenarios, sensitivities, dashboard, templates +│ │ ├── workers/ Arq tasks +│ │ ├── db/ SQLAlchemy models, migrations +│ │ └── deps.py +│ └── web/ +│ ├── package.json +│ ├── next.config.mjs +│ └── src/ +│ ├── app/ +│ │ ├── (dashboard)/ +│ │ ├── scenarios/ +│ │ └── api-types/ Auto-generated from OpenAPI +│ ├── components/ +│ │ ├── DataGrid/ +│ │ ├── KpiCard/ +│ │ ├── Wizard/ +│ │ └── Charts/ +│ └── lib/ +├── docker-compose.yml +├── .github/workflows/ci.yml +├── PROJECT.md This file +├── sprints/ +│ ├── SPRINT_00.md +│ ├── SPRINT_01.md +│ └── ... +└── README.md +Module specs (summary — full detail in sprint files) +Generation + +Solar 25y: 8760 profile × scaling × DC losses × inverter × AC losses → clipping at MW_AC → availability → soiling → degradation Y1..Y25 +Wind 25y: power curve lookup at hub-height-corrected wind speed → wakes → electrical → availability → degradation +BESS state: nameplate × capacity_factor(year) where capacity_factor = degradation_curve(cum_cycles) + augmentation_steps + +Dispatch (Hybrid RTC) + +Per timestamp: target = ppa_capacity (flat 24×7), gen = solar+wind, surplus → charge BESS or curtail/MCP, deficit → discharge BESS or shortfall (DSM) +SOC update with RTE on charge, 1/RTE on discharge, aux load +User toggle: surplus when BESS full → curtail (zero rev) OR MCP merchant sale (uses MCP forecast input) + +Commercial + +Revenue = injection × tariff × (1 - aux_loss) × (1 - tx_loss) × (1 - dsm_loss) +DSM loss% absorbs RTC penalty exposure (per user requirement) +Receivables, bad debt provision + +Capex (CostItem catalog + IDC) + +~30 standard CostItem records, user-extensible +Tier 1 fields exposed prominently (module INR/Wp, BOS INR/Wp, WTG Cr/MW, WTG BOP, land Lakh/Acre + lease/yr); Tier 2/3 collapsed +Phasing matrix: items × construction months, % per cell, rows sum to 100% +Equity drawdown: cumulative %, allowed >100% temporarily (bridge), settles at 100% by COD +Debt drawdown: cumulative %, monotonic, settles at 100% by COD +IDC: monthly waterfall, fixed-point converging IDC + total cost + debt = consistent + +Financial (3-statement) + +P&L: Revenue → OpEx → EBITDA → Depreciation → EBIT → Interest → PBT → Tax → PAT +CFS: indirect method, CFO/CFI/CFF +BS: assets = liab + equity, reconciled within ₹1 each year +Depreciation by asset class (book SLM + tax WDV 40% for plant) +Tax: 115BAA hardcoded v0 +WC: receivable_days, payable_days, inventory_days + +Debt + +Sizing: 3 constraints (D:E cap, min DSCR, avg DSCR), take binding +Schedule shapes: equal_principal, equal_installment, dscr_sculpted, custom_pct_vector, balloon +Compliance: try sculpting first; if equity_irr below target, raise tariff; if infeasible, warn user + +Solver + +brentq on tariff in [2.0, 8.0] ₹/kWh +Inner: debt sizing fixed-point +Innermost: IDC fixed-point + +Sensitivities (the "frequent 7") + +CAPEX, Module price, WTG price, Interest rate, CUF, Tariff, DSCR target + +Pydantic schema sketch (canonical types) +pythonclass CostItem(BaseModel): + id: str + name: str + category: Literal["BOS","HardCost","SoftCost","EPCOverhead","EPCMargin","FinancingCost"] + basis: Literal["PER_WP_DC","PER_MW_AC","PER_MWP_DC","PER_ACRE","PER_KWH_USD","PCT_OF_HARDCOST","ABS_INR_CR","PER_MW_SOLAR","PER_MW_WIND"] + value: float + fx_rate: Optional[float] = None + depr_class: Literal["Plant","BESS","Building","Land_NoDepr","LandLease_Amortized","Intangible","Capitalized_NoDepr","Expensed"] + escalation_pct: float = 0.0 + phasing_id: str + attribution: Literal["SolarOnly","WindOnly","BESSOnly","Common"] + +class ScenarioInput(BaseModel): + project: ProjectInfo + solar: Optional[SolarConfig] + wind: Optional[WindConfig] + bess: Optional[BessConfig] + commercial: CommercialConfig + capex: CapexConfig # contains list[CostItem] + phasing curves + equity/debt curves + opex: OpexConfig + debt: DebtConfig # rate, tenor, target_dscr, schedule_shape, ... + tax: TaxConfig + solver: SolverConfig # target_equity_irr OR fixed_tariff + +class ScenarioResult(BaseModel): + inputs: ScenarioInput + status: Literal["queued","running","success","failed"] + solved_tariff: Optional[float] + kpis: KpiSummary # equity_irr, project_irr, min_dscr, avg_dscr, rtc_cuf, capex, idc, ... + financials: Financials # pnl_25y, cfs_25y, bs_25y as DataFrames + timeseries_uri: str # parquet path + debt_schedule: list[DebtYearRow] + warnings: list[str] + runtime_s: float +Working agreements + +Always read PROJECT.md and the active SPRINT_XX.md at session start. The sprint file lists tasks; pick one, complete it, mark it done, commit. +One task per commit. Commit message format: [S2-T03] Implement IDC fixed-point solver. +Tests before features. Every public function gets a unit test. Every module gets an integration test. Coverage target ≥85%. +Type strict. mypy strict mode. No Any except at JSON boundaries. +Lint clean. Ruff pre-commit hook; CI fails on lint errors. +Pydantic for all I/O. No raw dicts crossing module boundaries. +No magic numbers. Defaults live in catalog/defaults.py. +Comments explain WHY, not WHAT. Code shows what; comments show why a non-obvious decision was made. +When in doubt, ask the user. Don't silently make architectural choices. Add a # DECISION NEEDED: comment with options. +Excel parity is sacred. When a parity test fails, stop adding features. Debug the diff. Don't paper over with tolerance bumps. +Don't optimize prematurely. Vectorize when slow. Pure-Python loops are fine for v0 if they pass tests. +Frontend types come from backend. Run openapi-typescript in CI. Never hand-write API types. +One DataGrid component. Don't create a second grid implementation, no matter how convenient. +Reference scenarios live in tests/fixtures/. When the user supplies new ones, add them as new fixtures, never modify existing. +README in every package. Setup steps, common commands, troubleshooting. + +Definition of Done (per sprint) + +All sprint tasks ticked off in SPRINT_XX.md +All tests pass locally and in CI +Coverage ≥85% on new code +Parity gate (if applicable) passes +Sprint demo runnable (CLI command or UI flow) +Sprint retro added to SPRINT_XX.md (what worked, what didn't, carryover) + +When to bring back Opus +Stop and ask the user to consult Opus when: + +A parity test fails by >0.5% and the cause isn't obvious in 30 minutes +An architectural decision arises that wasn't covered in PROJECT.md or sprint specs +A module is shaping up to be >800 LOC — likely needs decomposition +Performance is >2× the budget for a sprint deliverable \ No newline at end of file diff --git a/RE_Financial_Modeling_Platform PRD.md b/RE_Financial_Modeling_Platform PRD.md new file mode 100644 index 0000000..b8aa0ee --- /dev/null +++ b/RE_Financial_Modeling_Platform PRD.md @@ -0,0 +1,1074 @@ +# RE Financial Modeling Platform - Product Requirements Document (PRD) + +## Document Information +- **Version:** 1.0 +- **Date:** 2026-05-07 +- **Status:** Draft for Review +- **Author:** Product Team +- **Classification:** Internal + +--- + +# 1. Executive Summary + +## 1.1 Purpose +This document defines the requirements, specifications, and implementation plan for building a **Renewable Energy (RE) Financial Modeling Platform** - a web-based application that automates the financial modeling of RE projects (Solar, Wind, Battery) over a 25-year lifecycle. + +## 1.2 Problem Statement +Currently, the team performs financial modeling for RE projects using Excel with VBA macros. This approach suffers from: +- **Brittle automation** - Macros break easily, difficult to maintain +- **Limited scenario comparison** - Running multiple cases is manual and time-consuming +- **No version control** - Changes to models are not tracked +- **Single-user limitation** - Excel files don't support concurrent editing +- **Scalability issues** - Complex models with 8760-hour profiles become sluggish + +## 1.3 Solution Overview +A Python-backed web application that: +1. Accepts input parameters via a modern web UI +2. Runs 25-year financial simulations using Python (fast, maintainable) +3. Generates complete financial statements (income, balance, cash flow) +4. Calculates all financial metrics (IRR, NPV, LCOE, DSCR, payback) +5. Supports advanced analysis (sensitivity tables, Monte Carlo, scenario comparison) +6. Derives tariff based on target IRR thresholds +7. Allows comparison of multiple configurations side-by-side + +## 1.4 Target Users +- **Primary:** Internal RE development team +- **Secondary:** Finance team, investment committee +- **Access:** On-premise deployment (self-hosted) + +--- + +# 2. User Personas + +## 2.1 Persona 1: RE Project Analyst +**Name:** Sarah, Senior RE Analyst +**Background:** 5+ years in RE project finance, expert in Excel modeling + +| Attribute | Details | +|-----------|---------| +| Role | Builds financial models for solar/wind/battery projects | +| Goals | Quickly run multiple scenarios, compare configurations, derive tariff | +| Pain Points | Excel macros break, manual case switching takes hours | +| Technical Skill | Comfortable with web apps, knows Python basics | + +**Use Cases:** +- Input project parameters (capacity, CAPEX, OPEX, degradation) +- Run simulation and view financial statements +- Adjust inputs and re-run to optimize IRR +- Compare 3+ configurations side-by-side + +## 2.2 Persona 2: Finance Manager +**Name:** Raj, Finance Manager +**Background:** 10+ years in project finance, CFA + +| Attribute | Details | +|-----------|---------| +| Role | Reviews models, approves tariff recommendations | +| Goals | Validate assumptions, run sensitivity analysis, check stress scenarios | +| Pain Points | Can't easily trace back how tariff was derived | +| Technical Skill | Basic Excel, comfortable with dashboards | + +**Use Cases:** +- Review summary dashboard with key metrics +- Run Monte Carlo for risk assessment +- Export reports for investment committee +- View sensitivity tables (IRR vs. key variables) + +## 2.3 Persona 3: System Administrator +**Name:** Alex, DevOps/IT +**Background:** Infrastructure and deployment specialist + +| Attribute | Details | +|-----------|---------| +| Role | Deploy and maintain the platform | +| Goals | Ensure uptime, security, backups | +| Pain Points | Need clear deployment docs, easy updates | +| Technical Skill | Expert in Docker, PostgreSQL, nginx | + +**Use Cases:** +- Deploy platform on-premise +- Configure authentication (local accounts/LDAP) +- Manage backups and monitoring +- Apply updates without downtime + +--- + +# 3. Functional Requirements + +## 3.1 Core Features + +### 3.1.1 Project Configuration Management + +| ID | Feature | Description | Priority | +|----|---------|-------------|----------| +| F1.1 | Create Project | Create new RE project with name, type, location | Must Have | +| F1.2 | Project Templates | Pre-configured templates for Solar/Wind/Battery | Should Have | +| F1.3 | Import/Export | Import/export project configs as JSON | Must Have | +| F1.4 | Project List | View all projects with status, last modified | Must Have | +| F1.5 | Clone Project | Duplicate existing project as starting point | Should Have | +| F1.6 | Project Archives | Archive inactive projects | Could Have | + +### 3.1.2 Input Parameter Management + +**Solar Asset Inputs:** +| ID | Parameter | Unit | Default | Range | +|----|-----------|------|---------|-------| +| F2.1 | Installed Capacity | MW | 100 | 0.1 - 1000 | +| F2.2 | CAPEX | $/kW | 800 | 500 - 2000 | +| F2.3 | OPEX | $/kW/year | 15 | 5 - 50 | +| F2.4 | Degradation Rate | %/year | 0.5 | 0 - 2 | +| F2.5 | Annual Production Profile | 8760 kWh/kWp | From profile | Import | +| F2.6 | Useful Life | years | 25 | 15 - 35 | +| F2.7 | Capacity Factor | % | Calculate | - | - | +| F2.8 | DC/AC Ratio | - | 1.2 | 1.0 - 2.0 | +| F2.9 | Land Cost | $/acre | 0 | 0 - 50000 | +| F2.10 | Interconnection Cost | $ | 0 | 0 - 10M | + +**Wind Asset Inputs:** +| ID | Parameter | Unit | Default | Range | +|----|-----------|------|---------|-------| +| F3.1 | Installed Capacity | MW | 100 | 1 - 1000 | +| F3.2 | CAPEX | $/kW | 1200 | 800 - 2500 | +| F3.3 | OPEX | $/kW/year | 25 | 10 - 60 | +| F3.4 | Degradation Rate | %/year | 0.7 | 0 - 2 | +| F3.5 | Wind Speed Profile | 8760 m/s | From profile | Import | +| F3.6 | Power Curve | kW vs m/s | Import | - | +| F3.7 | Availability | % | 97 | 90 - 99 | +| F3.8 | Hub Height | m | 80 | 50 - 150 | +| F3.9 | Turbines Count | - | Calculate | - | + +**Battery Asset Inputs:** +| ID | Parameter | Unit | Default | Range | +|----|-----------|------|---------|-------| +| F4.1 | Storage Capacity | MWh | 50 | 1 - 1000 | +| F4.2 | Power Rating | MW | 25 | 1 - 500 | +| F4.3 | CAPEX | $/kWh | 300 | 150 - 600 | +| F4.4 | OPEX | $/kW/year | 10 | 5 - 30 | +| F4.5 | Round-trip Efficiency | % | 85 | 70 - 95 | +| F4.6 | degradation Profile | 8760 cycles | From profile | Import | +| F4.7 | Calendar Degradation | %/year | 2 | 0 - 5 | +| F4.8 | Cycle Limit | cycles | 5000 | 2000 - 10000 | +| F4.9 | DoD Limit | % | 90 | 80 - 100 | +| F4.10 | RTE Degradation Curve | %/year | 1.5 | 0 - 5 | + +### 3.1.3 Financial Structure Inputs + +**Capital Structure:** +| ID | Parameter | Description | +|----|-----------|-------------| +| F5.1 | Total CAPEX | Sum of all asset CAPEX + soft costs | +| F5.2 | Debt Amount | Principal amount of debt | +| F5.3 | Equity Amount | Sponsor equity contribution | +| F5.4 | Debt/Equity Ratio | Calculated from above | +| F5.5 | Debt Service Reserve | Months of reserve | + +**Debt Terms:** +| ID | Parameter | Unit | Default | Range | +|----|-----------|------|---------|-------| +| F6.1 | Debt Interest Rate | % | 6 | 2 - 12 | +| F6.2 | Debt Tenor | years | 15 | 5 - 25 | +| F6.3 | Amortization Type | bullet/level/inflating | level | - | +| F6.4 | Cash Sweep | % of excess cash | 75 | 0 - 100 | +| F6.5 | Debt Origination Fee | % | 1.5 | 0 - 3 | +| F6.6 | Debt Service Reserve | months | 6 | 0 - 18 | + +**Tax & Incentives:** +| ID | Parameter | Unit | Default | Range | +|----|-----------|------|---------|-------| +| F7.1 | ITC Rate | % | 30 | 0 - 50 | +| F7.2 | PTC Rate | $/MWh | 0 | 0 - 30 | +| F7.3 | MACRS Schedule | 5/7/10/20 year | 5 | - | +| F7.4 | State Rebate | $ | 0 | 0 - 1M | +| F7.5 | Grant Amount | $ | 0 | 0 - 10M | +| F7.6 | Tax Rate (Federal) | % | 21 | 0 - 35 | +| F7.7 | Tax Rate (State) | % | 5 | 0 - 15 | +| F7.8 | NOL Carryforward | years | 20 | 0 - 25 | + +### 3.1.4 Revenue Parameters + +| ID | Parameter | Unit | Default | Range | +|----|-----------|------|---------|-------| +| F8.1 | PPA Tariff | $/MWh | 25 | 10 - 100 | +| F8.2 | Tariff Escalator | %/year | 0 | -3 - 5 | +| F8.3 | PPA Term | years | 15 | 5 - 25 | +| F8.4 | Merchant Period | years | 10 | 0 - 25 | +| F8.5 | Merchant Price | $/MWh | 35 | 10 - 100 | +| F8.6 | Price Escalator | %/year | 2 | 0 - 5 | +| F8.7 | Curtailment | % | 2 | 0 - 10 | +| F8.8 | T&D Credits | $/MWh | 0 | 0 - 10 | + +### 3.1.5 Operating Expenses + +| ID | Parameter | Unit | Default | Range | +|----|-----------|------|---------|-------| +| F9.1 | O&M Contract | % of CAPEX | 1 | 0 - 3 | +| F9.2 | Land Lease | $/acre | 500 | 0 - 5000 | +| F9.3 | Insurance | % of CAPEX | 0.5 | 0 - 2 | +| F9.4 | Management Fee | $/kW/year | 5 | 0 - 20 | +| F9.5 | Asset Management | % of revenue | 2 | 0 - 5 | +| F9.6 | Variable O&M | $/MWh | 2 | 0 - 10 | + +### 3.1.6 8760-Hour Profile Management + +| ID | Feature | Description | +|----|---------|-------------| +| F10.1 | Profile Upload | Upload 8760-hour profiles (CSV, Excel) | +| F10.2 | Profile Editor | View/edit profiles in tabular/grid format | +| F10.3 | Profile Library | Save/manage reusable profiles | +| F10.4 | Profile Visualization | Plot generation profiles over time | +| F10.5 | Profile Metrics | Show capacity factor, CF histogram | +| F10.6 | Battery Degradation | Import degradation by cycle count | +| F10.7 | Scalability | Handle profiles up to 10 years | + +### 3.1.7 Simulation Engine + +| ID | Feature | Description | +|----|---------|-------------| +| F11.1 | Run Simulation | Execute 25-year simulation | +| F11.2 | Progress Indicator | Show progress for long simulations | +| F11.3 | Year-by-Year | View detailed year-by-year output | +| F11.4 | Monthly Cash Flow | View monthly breakdown | +| F11.5 | Recalculate | Re-run with modified inputs | +| F11.6 | Partial Recalc | Re-run only affected years | + +### 3.1.8 Financial Statement Generation + +**Income Statement (Annual):** +| Line | Description | +|------|-------------| +| IS1 | Revenue (PPA + Merchant) | +| IS2 | Less: Curtailment | +| IS3 | Gross Revenue | +| IS4 | Less: O&M Costs | +| IS5 | Less: Insurance | +| IS6 | Less: Land Lease | +| IS7 | Less: Management Fee | +| IS8 | Operating Expenses | +| IS9 | EBITDA | +| IS10 | Less: Depreciation | +| IS11 | Less: Interest (Debt) | +| IS12 | EBT | +| IS13 | Less: Taxes | +| IS14 | Net Income | + +**Balance Sheet (Annual):** +| Line | Description | +|------|-------------| +| BS1 | Assets | +| BS2 | Net PP&E | +| BS3 | Construction-in-Progress | +| BS4 | Cash & Equivalents | +| BS5 | Debt Reserve | +| BS6 | Total Assets | +| BS7 | Liabilities | +| BS8 | Debt | +| BS9 | Total Liabilities | +| BS10 | Equity | +| BS11 | Retained Earnings | +| BS12 | Total Equity | + +**Cash Flow Statement (Annual):** +| Line | Description | +|------|-------------| +| CF1 | Operating Activities | +| CF2 | Net Income | +| CF3 | + Depreciation | +| CF4 | - CapEx | +| CF5 | - Debt Repayment | +| CF6 | - Distributions | +| CF7 | Net Cash Flow | + +### 3.1.9 Financial Metrics Calculation + +| ID | Metric | Description | Formula | +|----|-------|-------------|---------| +| F12.1 | IRR | Internal Rate of Return | NPV = 0 | +| F12.2 | Equity IRR | IRR on equity | On distributions | +| F12.3 | NPV | Net Present Value | PV inflows - outflows | +| F12.4 | LCOE | Levelized Cost of Energy | Total cost / Total production | +| F12.5 | DSCR | Debt Service Coverage Ratio | CFADS / Debt Service | +| F12.6 | Min DSCR | Minimum DSCR over life | Lowest DSCR | +| F12.7 | Payback | Simple payback | Investment / Annual CF | +| F12.8 | MOIC | Multiple on Investment | Total distributions / Equity | +| F12.9 | CapEx/kW | Specific CAPEX | Total CAPEX / Capacity | +| F12.10 | Debt Yield | NOI / Debt | NOI / Total Debt | + +### 3.1.10 Tariff Derivation + +| ID | Feature | Description | +|----|---------|-------------| +| F13.1 | Target IRR Input | Set target equity IRR | +| F13.2 | Auto-Calculate | Derive required tariff | +| F13.3 | Tariff Sensitivity | Show required tariff vs. IRR | +| F13.4 | Breakeven Tariff | Minimum tariff for NPV > 0 | +| F13.5 | Tariff Scenarios | Multiple tariff assumptions | + +### 3.1.11 Scenario Management + +| ID | Feature | Description | +|----|---------|-------------| +| F14.1 | Clone Scenario | Duplicate scenario | +| F14.2 | Scenario List | View all scenarios | +| F14.3 | Compare Side-by-Side | Compare 2-5 scenarios | +| F14.4 | Diff View | Highlight differences | +| F14.5 | Scenario Groups | Organize by project stage | +| F14.6 | Scenario Notes | Add context to scenarios | + +### 3.1.12 Sensitivity Analysis + +| ID | Feature | Description | +|----|---------|-------------| +| F15.1 | One-way Sensitivity | Vary one parameter | +| F15.2 | Two-way Sensitivity | Vary two parameters | +| F15.3 | Results Table | Show IRR/tariff vs. variable | +| F15.4 | Tornado Chart | Visual sensitivity | +| F15.5 | Auto-ranges | Smart +/- ranges | + +### 3.1.13 Monte Carlo Simulation + +| ID | Feature | Description | +|----|---------|-------------| +| F16.1 | Variable Selection | Select which inputs to vary | +| F16.2 | Distribution Choice | Normal/Uniform/Triangle | +| F16.3 | Correlation | Correlate inputs | +| F16.4 | Run Count | Number of simulations | +| F16.5 | Results Histogram | Distribution of IRR/NPV | +| F16.6 | Percentile Table | P10/P50/P90 values | +| F16.7 | Probability Plot | Probability curve | +| F16.8 | Convergence | Show convergence | + +### 3.1.14 Reporting & Export + +| ID | Feature | Description | +|----|---------|-------------| +| F17.1 | Summary Report | One-page executive summary | +| F17.2 | Full Report | All statements and metrics | +| F17.3 | Export Excel | Export as Excel | +| F17.4 | Export PDF | Export as PDF | +| F17.5 | Scheduled Export | Auto-email reports | +| F17.6 | Branding | Custom logo/colors | + +### 3.1.15 Dashboard & Visualization + +| ID | Feature | Description | +|----|---------|-------------| +| F18.1 | KPI Summary | Key metrics at a glance | +| F18.2 | IRR Gauge | Visual IRR gauge | +| F18.3 | Cash Flow Chart | Annual CF bar chart | +| F18.4 | Revenue Breakdown | Stacked revenue | +| F18.5 | LCOE Breakdown | Donut chart | +| F18.6 | DSCR Timeline | Line chart over years | +| F18.7 | Profile Chart | 8760 profile overlay | + +--- + +# 4. Non-Functional Requirements + +## 4.1 Performance + +| Requirement | Target | +|------------|--------| +| Simulation Time | < 30 seconds for 25-year model | +| Concurrent Users | 10 users simultaneous | +| Profile Size | Up to 10 years × 8760 hours | +| Dashboard Load | < 3 seconds | +| API Response | < 1 second for queries | + +## 4.2 Security + +| Requirement | Implementation | +|------------|---------------| +| Authentication | Local accounts / LDAP integration | +| Authorization | Role-based access (Admin, Analyst, Viewer) | +| Data Encryption | TLS 1.3 in transit | +| At-rest Encryption | Database encryption | +| Audit Logging | Log all data changes | +| Session Timeout | 30 minutes idle | + +## 4.3 Availability + +| Requirement | Target | +|------------|--------| +| Uptime | 99.5% availability | +| Backup | Daily automated backup | +| Recovery | < 4 hour RTO | +| Monitoring | Health check endpoints | + +## 4.4 Scalability + +| Requirement | Target | +|------------|--------| +| Project Storage | 100+ projects | +| Scenario Storage | 500+ scenarios | +| Profile Storage | 10GB+ for profiles | + +--- + +# 5. Technical Architecture + +## 5.1 System Architecture + +``` +┌─────────────────────────────────────────────────────────────┐ +│ Web UI Layer │ +│ (React + TypeScript + Material UI + Recharts) │ +└─────────────────────────────────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────────────────────────┐ +│ API Layer │ +│ (FastAPI + Python 3.10+) │ +├─────────────────────────────────────────────────────────────┤ +│ • Projects API • Scenarios API • Profiles API │ +│ • Simulation API • Metrics API • Reports API │ +└─────────────────────────────────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────────────────────────┐ +│ Calculation Engine │ +│ (NumPy + Pandas + Numba for performance) │ +├─────────────────────────────────────���─���─────────────────────┤ +│ • Financial Simulator • Profile Processor • Metrics Calc │ +│ • Sensitivity Engine • Monte Carlo Engine │ +└─────────────────────────────────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────────────────────────┐ +│ Data Layer │ +│ (SQLAlchemy + PostgreSQL) │ +├─────────────────────────────────────────────────────────────┤ +│ • Projects Table • Scenarios Table • Profiles Table │ +│ • Simulations Table • Results Table • Users Table │ +└─────────────────────────────────────────────────────────────┘ +``` + +## 5.2 Technology Stack + +| Layer | Technology | Version | +|-------|------------|---------| +| Frontend | React | 18.x | +| Frontend | TypeScript | 5.x | +| UI Library | Material UI | 5.x | +| Charts | Recharts | 2.x | +| API | FastAPI | 0.100+ | +| Python | Python | 3.10+ | +| DB ORM | SQLAlchemy | 2.x | +| Database | PostgreSQL | 15.x | +| Compute | NumPy | 1.24+ | +| Compute | Pandas | 2.0+ | +| Compute | Numba | 0.58+ | +| Testing | pytest | 7.x | +| Container | Docker | 24.x | + +## 5.3 Data Model + +### Projects Table +```python +class Project(Base): + id: UUID + name: str + project_type: Enum(SOLAR, WIND, BATTERY, HYBRID) + location: str + description: str + created_at: datetime + updated_at: datetime + created_by: UUID + status: Enum(DRAFT, ACTIVE, ARCHIVED) +``` + +### SolarAsset Table +```python +class SolarAsset(Base): + project_id: UUID + capacity_mw: float + capex_per_kw: float + opex_per_kw: float + degradation_rate: float + dc_ac_ratio: float + land_cost: float + interconnection_cost: float + capacity_factor: float # calculated +``` + +### WindAsset Table +```python +class WindAsset(Base): + project_id: UUID + capacity_mw: float + capex_per_kw: float + opex_per_kw: float + degradation_rate: float + availability: float + hub_height: float +``` + +### BatteryAsset Table +```python +class BatteryAsset(Base): + project_id: UUID + storage_mwh: float + power_mw: float + capex_per_kwh: float + opex_per_kw: float + round_trip_efficiency: float + calendar_degradation: float + cycle_limit: float + dod_limit: float +``` + +### FinancialStructure Table +```python +class FinancialStructure(Base): + project_id: UUID + total_capex: float + debt_amount: float + equity_amount: float + debt_interest_rate: float + debt_tenor: int + amortization_type: Enum(BULLET, LEVEL, INFLATING) + itc_rate: float + ptc_rate: float + macrs_schedule: int + grant_amount: float + tax_rate_federal: float + tax_rate_state: float +``` + +### Revenue Table +```python +class Revenue(Base): + project_id: UUID + ppa_tariff: float + tariff_escalator: float + ppa_term: int + merchant_period: int + merchant_price: float + price_escalator: float + curtailment: float +``` + +### Profile Table +```python +class GenerationProfile(Base): + id: UUID + name: str + asset_type: Enum(SOLAR, WIND) + data: JSON # 8760 array + capacity_factor: float + uploaded_at: datetime +``` + +### Scenario Table +```python +class Scenario(Base): + id: UUID + project_id: UUID + name: str + description: str + inputs: JSON + results: JSON + target_irr: float + derived_tariff: float + created_at: datetime +``` + +### SimulationResult Table +```python +class SimulationResult(Base): + id: UUID + scenario_id: UUID + year: int + revenue: float + opex: float + ebitda: float + depreciation: float + interest: float + taxes: float + net_income: float + cash_flow: float + debt_balance: float + equity_balance: float + dscr: float +``` + +--- + +# 6. UI/UX Specifications + +## 6.1 Layout Structure + +``` +┌────────────────────────────────────────────────────────────────┐ +│ Header: Logo | Projects ▼ | Notifications | User Menu │ +├──────────┬───────────────────────────────────────────────────────┤ +│ │ │ +│ Sidebar │ Main Content Area │ +│ │ │ +│ • Home │ ┌─────────────────────────────────────────────┐ │ +│ • Proj │ │ Page Header + Actions │ │ +│ • Scen │ ├─────────────────────────────────────────────┤ │ +│ • Analy │ │ │ │ +│ • Rep │ │ Content (Forms/Charts/Tables) │ │ +│ • Set │ │ │ │ +│ │ └─────────────────────────────────────────────┘ │ +│ │ │ +└──────────┴───────────────────────────────────────────────────────┘ +``` + +## 6.2 Design System + +### Color Palette +| Role | Color | Hex | +|------|-------|-----| +| Primary | Deep Blue | #1565C0 | +| Primary Dark | Navy | #0D47A1 | +| Secondary | Amber | #FFA000 | +| Success | Green | #2E7D32 | +| Error | Red | #C62828 | +| Warning | Orange | #EF6C00 | +| Background | Light Gray | #F5F5F5 | +| Surface | White | #FFFFFF | +| Text Primary | Dark Gray | #212121 | +| Text Secondary | Medium Gray | #757575 | +| Border | Light Gray | #E0E0E0 | + +### Typography +| Element | Font | Size | Weight | +|---------|------|------|--------| +| H1 | Inter | 32px | 700 | +| H2 | Inter | 24px | 600 | +| H3 | Inter | 20px | 600 | +| H4 | Inter | 16px | 600 | +| Body | Inter | 14px | 400 | +| Caption | Inter | 12px | 400 | +| Button | Inter | 14px | 500 | + +### Spacing System +- Base unit: 8px +- Margins: 16px, 24px, 32px +- Padding: 8px, 16px, 24px +- Grid gap: 16px, 24px + +### Components +- Input fields: Rounded (8px), outlined +- Buttons: Rounded (4px), primary/secondary/outline +- Cards: Elevated (2dp shadow), rounded (12px) +- Tables: Striped rows, sticky header + +## 6.3 Key Screens + +### 6.3.1 Dashboard +- Project summary cards (total, active, draft) +- Recent projects list +- Quick actions (new project, quick run) +- Key metrics summary (top IRR, average LCOE) + +### 6.3.2 Project Details +- Project header (name, type, status) +- Tab navigation: Overview | Assets | Financial | Revenue | Operating +- Form sections with validation +- Save/Run buttons + +### 6.3.3 Scenario Comparison +- Scenario selector (multi-select) +- Side-by-side table showing key metrics +- Diff highlighting +- Export options + +### 6.3.4 Sensitivity Analysis +- Variable selector dropdowns +- Range inputs +- Generate button +- Results table +- Tornado chart + +### 6.3.5 Monte Carlo +- Variable configuration grid +- Distribution selector per variable +- Run button with progress +- Results histogram +- Percentile table + +### 6.3.6 Reports +- Report type selector +- Preview panel +- Export buttons (PDF, Excel) + +--- + +# 7. Sprint Breakdown + +## Overview +- **Total Duration:** 14 weeks (3.5 months) +- **Sprints:** 7 sprints × 2 weeks each +- **MVP Goal:** Core simulation + basic scenario management + +## Sprint 1: Foundation (Week 1-2) +**Goal:** Project structure, database, authentication + +| Task ID | Task Description | Estimated | +|--------|------------------|-----------| +| S1.1 | Create project structure and repo | 1 day | +| S1.2 | Set up PostgreSQL database | 1 day | +| S1.3 | Implement database models | 3 days | +| S1.4 | Implement authentication | 2 days | +| S1.5 | Create project CRUD API | 3 days | +| S1.6 | Frontend layout and routing | 2 days | +| **Total** | | **12 days** | + +**Deliverables:** +- Repository with Docker setup +- Database schema +- Backend API for projects +- Frontend shell with login + +## Sprint 2: Asset Management (Week 3-4) +**Goal:** Asset input forms and storage + +| Task ID | Task Description | Estimated | +|--------|------------------|-----------| +| S2.1 | Implement asset models | 2 days | +| S2.2 | Create asset input API | 3 days | +| S2.3 | Build solar input form | 2 days | +| S2.4 | Build wind input form | 2 days | +| S2.5 | Build battery input form | 2 days | +| S2.6 | Frontend validation | 1 day | +| **Total** | | **12 days** | + +**Deliverables:** +- All asset input forms +- Asset API endpoints +- Data validation + +## Sprint 3: Profile Management (Week 5-6) +**Goal:** Profile upload, storage, visualization + +| Task ID | Task Description | Estimated | +|--------|------------------|-----------| +| S3.1 | Profile database models | 1 day | +| S3.2 | Profile upload API | 2 days | +| S3.3 | Profile storage (PostgreSQL) | 2 days | +| S3.4 | Profile visualization | 2 days | +| S3.5 | Profile metrics calculation | 2 days | +| S3.6 | Profile library UI | 1 day | +| **Total** | | **10 days** | + +**Deliverables:** +- Profile upload/download +- Profile visualization +- Saved profiles library + +## Sprint 4: Core Simulation (Week 7-8) +**Goal:** Financial simulation engine + +| Task ID | Task Description | Estimated | +|--------|------------------|-----------| +| S4.1 | Simulation engine architecture | 2 days | +| S4.2 | Income statement calculation | 2 days | +| S4.3 | Balance sheet calculation | 2 days | +| S4.4 | Cash flow calculation | 2 days | +| S4.5 | Results storage | 1 day | +| S4.6 | Results API | 1 day | +| **Total** | | **10 days** | + +**Deliverables:** +- Working simulation engine +- Results storage +- API for results + +## Sprint 5: Metrics & Tariff (Week 9-10) +**Goal:** Metrics calculation, tariff derivation + +| Task ID | Task Description | Estimated | +|--------|------------------|-----------| +| S5.1 | IRR/NPV calculation | 2 days | +| S5.2 | LCOE calculation | 1 day | +| S5.3 | DSCR calculation | 1 day | +| S5.4 | Tariff derivation | 2 days | +| S5.5 | Dashboard UI | 2 days | +| S5.6 | Results visualization | 2 days | +| **Total** | | **10 days** | + +**Deliverables:** +- All financial metrics +- Tariff auto-calculation +- Dashboard with charts + +## Sprint 6: Scenario & Sensitivity (Week 11-12) +**Goal:** Scenario management, analysis tools + +| Task ID | Task Description | Estimated | +|--------|------------------|-----------| +| S6.1 | Scenario models | 1 day | +| S6.2 | Scenario API | 2 days | +| S6.3 | Comparison UI | 2 days | +| S6.4 | Sensitivity analysis API | 2 days | +| S6.5 | Sensitivity UI | 2 days | +| S6.6 | Testing | 3 days | +| **Total** | | **12 days** | + +**Deliverables:** +- Scenario management +- Comparison tool +- Sensitivity analysis + +## Sprint 7: Advanced Analysis & Polish (Week 13-14) +**Goal:** Monte Carlo, reporting, polish + +| Task ID | Task Description | Estimated | +|--------|------------------|-----------| +| S7.1 | Monte Carlo engine | 3 days | +| S7.2 | Monte Carlo UI | 2 days | +| S7.3 | PDF export | 2 days | +| S7.4 | Excel export | 2 days | +| S7.5 | Final QA and polish | 3 days | +| S7.6 | Documentation | 2 days | +| **Total** | | **14 days** | + +**Deliverables:** +- Monte Carlo simulation +- Export capabilities +- MVP complete + +--- + +# 8. Task Breakdown + +## Detailed Task List + +### Phase 1: Infrastructure (Week 1-2) + +#### Task 1.1: Project Setup +- [ ] Initialize Git repository +- [ ] Create project structure (frontend/backend) +- [ ] Add Dockerfile for backend +- [ ] Add Dockerfile for frontend +- [ ] Create docker-compose.yml +- [ ] Add Makefile +- [ ] Set up pre-commit hooks + +#### Task 1.2: Database Setup +- [ ] Set up PostgreSQL container +- [ ] Create base migration system +- [ ] Define database connection +- [ ] Add database health check +- [ ] Configure backup job + +#### Task 1.3: Authentication +- [ ] Implement user model +- [ ] Create login API endpoint +- [ ] Implement JWT tokens +- [ ] Add role-based access +- [ ] Create session management + +#### Task 1.4: Projects CRUD +- [ ] Create project model +- [ ] API: Create project +- [ ] API: List projects +- [ ] API: Get project +- [ ] API: Update project +- [ ] API: Delete project + +#### Task 1.5: Frontend Shell +- [ ] Initialize React app +- [ ] Set up Material UI theme +- [ ] Create layout components +- [ ] Add React Router +- [ ] Create login page + +### Phase 2: Asset Input (Week 3-4) + +#### Task 2.1: Asset Models +- [ ] SolarAsset model +- [ ] WindAsset model +- [ ] BatteryAsset model +- [ ] Validation rules + +#### Task 2.2: Financial Models +- [ ] FinancialStructure model +- [ ] Revenue model +- [ ] OperatingExpenses model + +#### Task 2.3: Asset Forms +- [ ] Solar form component +- [ ] Wind form component +- [ ] Battery form component +- [ ] Tab navigation +- [ ] Form validation + +#### Task 2.4: Financial Forms +- [ ] Capital structure form +- [ ] Debt terms form +- [ ] Tax/incentives form + +### Phase 3: Profiles (Week 5-6) + +#### Task 3.1: Profile Upload +- [ ] File upload API +- [ ] CSV parser +- [ ] Excel parser +- [ ] Validation + +#### Task 3.2: Profile Storage +- [ ] Profile model +- [ ] Data storage (JSON) +- [ ] Profile retrieval + +#### Task 3.3: Profile UI +- [ ] Upload component +- [ ] Profile selector +- [ ] Profile metrics display +- [ ] Profile chart + +### Phase 4: Simulation (Week 7-8) + +#### Task 4.1: Simulation Engine +- [ ] Engine architecture +- [ ] Year loop +- [ ] Production calculation +- [ ] Revenue calculation + +#### Task 4.2: Financial Statements +- [ ] Income statement +- [ ] Balance sheet +- [ ] Cash flow statement + +#### Task 4.3: Results Storage +- [ ] Results model +- [ ] Store yearly results +- [ ] Aggregate results + +### Phase 5: Metrics (Week 9-10) + +#### Task 5.1: Metrics Calculation +- [ ] IRR calculation (NumPy) +- [ ] NPV calculation +- [ ] LCOE calculation +- [ ] DSCR calculation +- [ ] Payback calculation + +#### Task 5.2: Tariff Derivation +- [ ] Target IRR input +- [ ] Binary search algorithm +- [ ] Breakeven calculation + +#### Task 5.3: Dashboard +- [ ] Summary cards +- [ ] KPI display +- [ ] Charts integration + +### Phase 6: Scenarios (Week 11-12) + +#### Task 6.1: Scenario Management +- [ ] Scenario model +- [ ] Clone functionality +- [ ] Version tracking + +#### Task 6.2: Comparison +- [ ] Compare API +- [ ] Side-by-side UI +- [ ] Diff highlighting + +#### Task 6.3: Sensitivity +- [ ] One-way sensitivity +- [ ] Two-way sensitivity +- [ ] Tornado chart + +### Phase 7: Advanced (Week 13-14) + +#### Task 7.1: Monte Carlo +- [ ] Variable configuration +- [ ] Simulation runner +- [ ] Distribution sampling +- [ ] Results histogram +- [ ] Percentile calculation + +#### Task 7.2: Export +- [ ] PDF generation +- [ ] Excel generation +- [ ] Report templates + +--- + +# 9. Timeline Summary + +| Sprint | Duration | Goal | Milestone | +|--------|----------|------|----------| +| 1 | Week 1-2 | Foundation | API shell + auth | +| 2 | Week 3-4 | Asset forms | All inputs work | +| 3 | Week 5-6 | Profiles | Upload/view work | +| 4 | Week 7-8 | Simulation | Core simulation runs | +| 5 | Week 9-10 | Metrics | Dashboard works | +| 6 | Week 11-12 | Scenarios | Compare works | +| 7 | Week 13-14 | Advanced | MC + exports | + +**MVP Release:** End of Sprint 7 + +--- + +# 10. Risks & Mitigations + +| Risk | Impact | Mitigation | +|------|--------|-------------| +| Profile performance | High | Use NumPy arrays, lazy loading | +| IRR convergence | Medium | Multiple solver methods | +| Excel migration | Medium | Keep export capability | +| Data validation | High | Extensive validation rules | +| User adoption | Medium | Training, documentation | + +--- + +# 11. Success Metrics + +| Metric | Target | +|--------|--------| +| Model accuracy | Match Excel ±1% | +| Simulation time | < 30 seconds | +| User satisfaction | > 4/5 | +| Adoption | Full team in 2 months | +| Error rate | < 1% | + +--- + +# 12. Out of Scope (v1.0) + +The following are intentionally excluded for v1.0: +- Multi-user collaboration (same scenario) +- Real-time market data integration +- GIS mapping +- Custom report designer +- Mobile app +- API for third-party integration +- Cloud deployment (v1.0 is on-prem only) + +--- + +# Appendices + +## Appendix A: Glossary + +| Term | Definition | +|------|-------------| +| CAPEX | Capital Expenditure | +| CFADS | Cash Available for Debt Service | +| DC/AC | Direct Current to Alternating Current ratio | +| DoD | Depth of Discharge | +| DSCR | Debt Service Coverage Ratio | +| IRR | Internal Rate of Return | +| ITC | Investment Tax Credit | +| LCOE | Levelized Cost of Energy | +| MOIC | Multiple on Investment | +| NOL | Net Operating Loss | +| NPV | Net Present Value | +| O&M | Operations & Maintenance | +| PPA | Power Purchase Agreement | +| PTC | Production Tax Credit | +| ROC | Return on Capital | +| RTE | Round Trip Efficiency | + +--- + +*Document Version: 1.0* +*Last Updated: 2026-05-07* +*Next Review: After stakeholder feedback* \ No newline at end of file diff --git a/sprints/.DS_Store b/sprints/.DS_Store new file mode 100644 index 0000000000000000000000000000000000000000..5008ddfcf53c02e82d7eee2e57c38e5672ef89f6 GIT binary patch literal 6148 zcmeH~Jr2S!425mzP>H1@V-^m;4Wg<&0T*E43hX&L&p$$qDprKhvt+--jT7}7np#A3 zem<@ulZcFPQ@L2!n>{z**++&mCkOWA81W14cNZlEfg7;MkzE(HCqgga^y>{tEnwC%0;vJ&^%eQ zLs35+`xjp>T0 pd.DataFrame returning 25y × 8760 rows with columns year, hour, dc_power_mw, ac_power_mw_pre_clip, ac_power_mw, degradation_factor. + S1-T04 Solar logic: scaling, DC losses, inverter η, AC losses, clipping at MW_AC, availability, soiling (monthly profile or flat), Y1 + 0.7%, Y2-25 + 0.5% degradation. + S1-T05 Tests: CUF reasonable (15-25% range for solar), clipping captures DC excess correctly, degradation factors monotonic. + S1-T06 generation/wind.py: power curve lookup, wind shear correction, wake losses, electrical, availability, degradation. + S1-T07 Wind tests: PLF reasonable (25-40%), edge cases (zero wind, gale wind = power=0). + S1-T08 generation/bess_state.py: function simulate_bess_capacity(config: BessConfig, cum_cycles_per_year: list[float]) -> pd.Series returning usable MWh per year. Note: dispatch happens elsewhere; this module only models physical capacity. Augmentation as input list of (year, additional_mwh). + S1-T09 CLI: remodel simulate-gen --input scenario.json --output gen.parquet. + S1-T10 Parity test: load tests/fixtures/nagasamudra_inputs.json, run, compare year-1 generation against Excel value (within 0.1%). User to provide expected output. + S1-T11 Documentation: packages/engine/docs/generation.md explaining the module and how to extend. + +Definition of Done: CLI generates 25y output for the user's reference scenario. Year-1 CUF matches Excel within 0.1%. All tests pass. \ No newline at end of file diff --git a/sprints/SPRINT_02.md b/sprints/SPRINT_02.md new file mode 100644 index 0000000..b080ff3 --- /dev/null +++ b/sprints/SPRINT_02.md @@ -0,0 +1,18 @@ +Goal: Capex modeling including the full CostItem catalog and the IDC fixed-point solver. Critical sprint — IDC parity gate. +Tasks: + + S2-T01 Schema: CostItem, PhasingCurve, EquityCurve, DebtCurve, CapexConfig in engine/schemas/capex.py. + S2-T02 Catalog: ~30 default CostItems in engine/catalog/cost_items.py matching the user's Excel structure (BOS subcomponents, hard cost items, soft cost items). Each with realistic 2026-level defaults. + S2-T03 Catalog: phasing templates solar_standard_18mo, wind_standard_24mo, hybrid_rtc_36mo with reasonable distributions per item. + S2-T04 capex/cost_items.py: function to compute total capex in INR Cr from a list of CostItems given project capacity, FX rate, etc. Each basis (PER_WP_DC, PER_MW_AC, etc.) has its own conversion. + S2-T05 capex/phasing.py: validation (rows sum to 100%), template loader, custom override. + S2-T06 capex/idc.py: the fixed-point IDC solver. Algorithm in PROJECT.md. Iterates until debt converges within ₹0.01 Cr. + S2-T07 Test: deterministic 2-month construction with hand-computed expected IDC. Solver matches. + S2-T08 Test: 36-month hybrid RTC scenario with equity bridge pattern (cum equity going to 110% then back to 100%). Solver matches. + S2-T09 Test: zero debt → zero IDC. Edge case. + S2-T10 CLI: remodel compute-idc --input scenario.json --output idc.json. + S2-T11 PARITY GATE: load tests/fixtures/nagasamudra_inputs.json. Run IDC. Total IDC must match user's Excel within 0.5%. User to walk Sonnet through the Apr-Jun-27 negative cum equity rows if mismatch. + S2-T12 Documentation: packages/engine/docs/capex.md covering CostItem model, phasing, IDC algorithm. + +Definition of Done: IDC parity gate passed. Catalog has 30 items with sensible defaults. Phasing templates work. CLI runs end-to-end. +ESCALATION: If IDC parity fails by >0.5% after 4 hours of debug, stop and consult Opus with the diff. \ No newline at end of file diff --git a/sprints/SPRINT_03.md b/sprints/SPRINT_03.md new file mode 100644 index 0000000..73e7fcb --- /dev/null +++ b/sprints/SPRINT_03.md @@ -0,0 +1,15 @@ +Goal: Full 3-statement model (P&L, CFS, BS) for 25 years with depreciation, tax, working capital. Parity gate on statements. +Tasks: + + S3-T01 Schema: OpexConfig, TaxConfig, Financials, PnLRow, CFSRow, BSRow. + S3-T02 financial/depreciation.py: book SLM by asset class (Plant 25y, BESS 12y, Building 30y, Intangible 25y, Land never), tax WDV 40% for plant. IDC capitalized proportionally. + S3-T03 financial/tax.py: 115BAA computation. PBT × 25.17%. Deferred tax from book/tax depreciation diff. + S3-T04 financial/working_capital.py: receivables, payables, inventory based on days inputs. + S3-T05 financial/pnl.py: 25-row P&L from revenue + opex + depreciation + interest schedule (passed in) + tax. + S3-T06 financial/cfs.py: CFO from PAT + depr - ΔWC; CFI from capex; CFF from debt + equity flows. + S3-T07 financial/bs.py: gross block, accumulated depr, net block, cash, receivables, equity, reserves, debt, payables, deferred tax. Reconciliation assertion. + S3-T08 Tests: each module unit tested. Integration test: dummy scenario, statements reconcile. + S3-T09 PARITY GATE: load nagasamudra_inputs.json, run with user's actual tariff. Each P&L line for years 1, 5, 10, 15, 25 within 0.5% of Excel. BS reconciles each year. + S3-T10 Documentation. + +ESCALATION: Parity miss > 0.5% on any statement line → Opus.