1074 lines
No EOL
34 KiB
Markdown
1074 lines
No EOL
34 KiB
Markdown
# 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) │
|
||
├─────────────────────────────────────<EFBFBD><EFBFBD><EFBFBD>─<EFBFBD><EFBFBD><EFBFBD>─────────────────────┤
|
||
│ • 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* |