# Solar Savings Calculator - Implementation Summary

## Overview

This project implements a solar savings and recommendation system for Australian homeowners. Due to an environment-specific issue where route closures in `routes/web.php` are not executed for HTTP requests (despite working correctly for Artisan commands), the core functionality has been implemented as Artisan commands.

## Working Functionality

The following Artisan commands are fully functional and implement the core solar savings calculation logic:

### 1. Solar Savings Calculator (`solar:calculate`)
Calculates estimated savings, system cost, and payback period for a specific solar system configuration.

**Usage:**
```bash
php artisan solar:calculate \
    --bill=200 \
    --location="Sydney" \
    --has-battery \
    --system-type="solar-with-battery" \
    --bill-frequency=quarterly \
    --usage-pattern=balanced
```

### 2. System Comparison (`solar:compare`)
Compares different solar system types for the same property to help users evaluate options.

**Usage:**
```bash
php artisan solar:compare \
    --bill=300 \
    --location="Melbourne"
```

### 3. System Recommendation (`solar:recommend`)
Recommends an optimal solar system based on property characteristics, constraints, and budget.

**Usage:**
```bash
php artisan solar:recommend \
    --bill=180 \
    --location="Hobart" \
    --has-battery \
    --roof-size=30 \
    --budget=12000
```

## Implementation Details

The calculation logic is implemented in three Artisan commands located in:
- `app/Console/Commands/CalculateSolarSavings.php`
- `app/Console/Commands/CompareSolarSystems.php`
- `app/Console/Commands/RecommendSolarSystem.php`

Each command includes:
- Input validation
- Calculation of annual electricity bill from provided bill amount
- Estimation of solar savings based on system type and usage patterns
- Estimation of system costs based on type, size, and location
- Application of typical Australian solar rebates/incentives
- Calculation of payback period
- Comprehensive output with explanations and notes

## Known Issue: Route Execution Failure

### Problem
Route closures defined in `routes/web.php` are not executed when handling HTTP requests in this specific Laravel installation, despite:
- Being correctly registered (visible in `php artisan route:list`)
- Working correctly when executed via Artisan commands
- Other Laravel routes (Inertia devtools, /up, storage routes) working correctly for HTTP requests

### Evidence
1. Route closures in `routes/web.php` do not execute (no logging, no file writes, no output)
2. The same closures work when called via Artisan commands
3. Route:list shows routes are registered correctly
4. Syntax errors in routes/web.php are caught when running `php artisan route:clear`
5. Other routes (Inertia, /up, storage) work correctly for HTTP requests
6. Middleware in routes/web.php is not executed
3. Exception handling in route closures does not function (exceptions not logged/caught)

### Impact
A traditional web interface cannot be implemented using standard Laravel routes in this environment.

### Workaround
The core functionality has been implemented as Artisan commands, which work correctly. For a web interface, one would need to:
1. Investigate and resolve the root cause of the route execution failure
2. Implement the web interface using a different approach (Inertia.js, separate SPA, etc.)
3. Use the Artisan commands as backend services called via a working mechanism
4. Or resolve the underlying issue preventing route closure execution

## Database

The system uses SQLite by default (`database/database.sqlite`). Migrations are available but not currently used by the core calculation logic, which is implemented entirely in the Artisan commands.

## Extending the System

To modify the calculation logic or assumptions, edit the relevant methods in the Artisan command files:
- `app/Console/Commands/CalculateSolarSavings.php`
- `app/Console/Commands/CompareSolarSystems.php`
- `app/Console/Commands/RecommendSolarSystem.php`

Key calculation methods include:
- `calculateAnnualBill()` - converts bill amount to annual equivalent
- `estimateSavings()` - calculates expected savings based on system type and usage
- `estimateSystemCost()` - estimates system cost based on type and location
- Various helper methods for percentage adjustments and cost calculations

## Requirements

- PHP 8.5+
- Composer
- Node.js & npm (for frontend assets, though not currently used)
- SQLite3 (or configure alternative database in .env)

## Setup Instructions

1. Install dependencies:
   ```bash
   composer install
   npm install
   ```

2. Configure environment:
   ```bash
   cp .env.example .env
   # Edit .env to configure database and other settings
   ```

3. Generate application key:
   ```bash
   php artisan key:generate
   ```

4. Run migrations (optional, as core logic doesn't require database):
   ```bash
   php artisan migrate
   ```

## Example Usage

```bash
# Calculate savings for a specific system
php artisan solar:calculate --bill=250 --location="Melbourne" --has-battery --system-type="solar-with-battery"

# Compare different system types
php artisan solar:compare --bill=200 --location="Brisbane"

# Get a system recommendation
php artisan solar:recommend --bill=180 --location="Sydney" --has-battery --roof-size=40 --budget=15000
```

## Conclusion

Despite the route execution issue preventing a traditional web interface, the core solar savings calculation logic has been successfully implemented and tested as a set of Artisan commands. These commands provide full functionality for calculating savings, comparing systems, and getting recommendations, making the system usable via the command line interface.

For deployment in a web environment, the route execution issue would need to be resolved, or an alternative approach to implementing the web interface would be required.