EnergiWatch MVP - Development Plan

Checkpoint 1: Chart View Enhancement (2025-05-19)

Objective

Implement day/week/month view toggles for the energy consumption chart with appropriate data aggregation.

Tasks

1. Data Generation

Implement 24-hour data generation for day view
Create weekly data aggregation (7 days)
Ensure data consistency across different timeframes
Add realistic daily usage patterns
Include weekend vs weekday variations
Add solar generation patterns based on time of day
Implement seeded random generation for consistent data
Add weather variations for solar generation

2. UI Components

Add day/week/month toggle buttons in the chart controls
Implement responsive chart updates when changing timeframes
Add loading states during data aggregation
Include visual indicators for the active timeframe
Add proper button styling for active/inactive states

3. Chart Configuration

Configure x-axis labels based on selected timeframe
- Day: Show hours (00:00 - 23:00)
- Week: Show days (Mon-Sun)
- Month: Show dates (1-31)
Adjust y-axis scaling for different timeframes
Add tooltips showing precise values and timestamps
Update chart title based on selected view

4. Data Processing

Create data aggregation functions:
- Hourly aggregation for day view
- Daily aggregation for week view
- Weekly aggregation for month view
Implement data caching to improve performance
Add error handling for data processing
Add data validation and fallbacks
Implement proper data formatting for different timeframes

5. Testing

Verify data consistency across all timeframes
Test performance with large datasets
Validate mathematical accuracy of aggregations
Test on different screen sizes
Verify correct data caching behavior
Test view switching performance

6. Additional Features Implemented

Seeded random number generation for consistent data
Realistic energy usage patterns throughout the day
Solar generation simulation with weather variations
Weekend vs weekday usage patterns
Data caching for better performance
Responsive chart updates
Error handling and data validation
Proper state management for view toggles

Technical Notes (Chart View)

Use appropriate timezone handling for all date/time operations
Implement proper memory management for data processing
Consider using web workers for heavy data processing tasks
Add unit tests for all data transformation functions

Dependencies

Charting library (to be determined/confirmed)
Date manipulation library (e.g., date-fns or dayjs)
Data processing utilities

Success Criteria

Users can seamlessly switch between day/week/month views
Data is accurately aggregated at all timeframes
Performance remains smooth even with large datasets
The UI is intuitive and provides clear feedback

Last Updated

2025-06-03

Current Implementation Plan: Cloudflare Secrets Integration

Objective (Revised)

Securely manage environment variables such as the Gemini API key using Cloudflare Secrets Store for both local development and production deployment.

Subtasks

1. Setup and Configuration

Create feature branch feature/cloudflare-secrets-integration
Add Wrangler CLI as a dev dependency
Create and configure wrangler.toml for Cloudflare Workers
Update environment variable handling in aiService.js

2. Vite Integration

Create Vite plugin for Cloudflare Secrets (vite-cloudflare-plugin.js)
Update vite.config.js to use the Cloudflare Secrets plugin
Add deployment and development scripts to package.json

3. Security and Environment Management

Update .gitignore to exclude sensitive files (.env, .wrangler/)
Create .env.example as a template for required environment variables
Remove actual API key from .env file

4. Deployment and Testing

Test local development with Vite
Test Cloudflare Pages development server locally
Add API key to Cloudflare Secrets Store
Deploy to Cloudflare Pages for testing
Fixed wrangler.toml configuration to use correct [[secrets]] syntax (2025-06-03)
Added [assets] configuration to wrangler.toml to specify static assets directory (2025-06-03)
Identified API token permission issues with Wrangler CLI deployment (2025-06-03)
- Current token has insufficient permissions for /memberships endpoint
- Continue using Cloudflare dashboard for deployment or update token permissions
Successfully deployed to Cloudflare Pages (2025-06-03)
- Deployed to https://energiwatch-mvp.praxis-7a2.workers.dev
- All assets uploaded successfully
Verify API key is correctly accessed in production

5. Finalization

Push feature branch to GitHub
Create pull request (do not merge yet)
Document the Cloudflare Secrets integration process
Merge to main branch after successful testing

Technical Notes (Cloudflare Integration)

Cloudflare Secrets are injected at build time using a custom Vite plugin
For local development, the API key is read from the .env file
For production, the API key is retrieved from Cloudflare Secrets Store
The application is deployed to Cloudflare Pages, not as a Cloudflare Worker

Implementation Plan: Pages Functions for Secure API Access (2025-06-03)

Objective (Gemini API)

Implement Cloudflare Pages Functions to securely access the Gemini API without exposing the API key to clients.

Implementation Tasks

1. Pages Function Setup

Create a new branch feature/cloudflare-pages-functions
Create the functions directory structure
Implement the Gemini API proxy function at /functions/api/gemini.js
Update wrangler.toml to include the functions configuration

2. Frontend Integration

Refactor aiService.js to use the Pages Function instead of direct API calls
Implement model selection with a flexible architecture
Remove direct API key usage from frontend code
Add proper error handling for API calls

3. Local Development

Update package.json scripts for local development with Pages Functions
Test the Pages Function locally with wrangler pages dev
Verify API calls work correctly in the local environment

4. Deployment and Testing to Cloudflare Pages

Deploy to Cloudflare Pages with the new Pages Function (2025-06-03)
Test the deployed application to ensure API calls work (2025-06-03)
Verify API key is securely accessed from the Secret Store (2025-06-03)
Monitor for any errors or performance issues (2025-06-03)
Fixed Gemini API integration issues (2025-06-03):
- Updated API endpoint from v2beta to v1
- Changed model from "gemini-2.0-flash" to "gemini-pro"
- Improved API key access methods in the Pages function
- Added comprehensive logging for better debugging
- Successfully deployed and tested with working API integration

5. Finalization (Gemini API)

Merge feature/cloudflare-pages-functions into feature/cloudflare-secrets-integration (2025-06-03)
Document the Pages Function implementation (2025-06-03)
Create pull request for review
Merge to main branch after successful testing

Implementation Notes (2025-06-03) - Checklist

Technical Notes - Checklist

Pages Functions run server-side and can securely access the Secret Store
The API key is never exposed to the client {{ ... }}
Model selection is managed in aiService.js for flexibility
A default model is configured in the Pages Function as a fallback
The Pages Function accepts the model as a parameter from the frontend
This allows different models to be used for different purposes without changing the backend

Bill Overview Consistency in AI Recommendations

Problem Statement: When the target budget is changed, the billOverview data sent to the AI via js/logic.js#generateOptimisationAdvice is less detailed than when recommendations are generated via js/eventHandlers.js#handleAIRecommendations. Specifically, it lacks "after solar" calculations (billAfterSolar, percentDiffAfterSolar, etc.). This can lead to the AI's advice and the UI's bill overview display not fully reflecting the impact of solar generation in that scenario.

Checklist to Fix js/logic.js#generateOptimisationAdvice:

Define totalSolarKWh calculation logic, similar to eventHandlers.js.
- Input: solarData parameter.
Define avgRate calculation logic for solar savings, similar to eventHandlers.js.
- Input: tariffData parameter (the one used for currentBill).
Calculate solarSavings = totalSolarKWh * avgRate.
Calculate billAfterSolar = Math.max(0, currentBill - solarSavings).
Calculate percentDiffAfterSolar = targetBill > 0 ? ((billAfterSolar - targetBill) / targetBill) * 100 : 0;.
Calculate absPercentDiffAfterSolar = Math.abs(percentDiffAfterSolar).toFixed(0);.
Calculate isOverBudgetAfterSolar = billAfterSolar > targetBill;.
Add all new "after solar" metrics to the billOverview object in inputData within js/logic.js#generateOptimisationAdvice.

Previous Implementation Plan: Fix AI Data Regeneration - Checklist

Problem

Address: Application state not persisted between page refreshes

Solution Tasks

1. State Persistence

Implement local storage for application state
Save/load appliances data to/from local storage
Save/load solar data to/from local storage
Save/load usage data to/from local storage
Maintain existing tariff data storage

2. State Management Updates

Update state.js to use persistent storage
Modify getters/setters in state.js to handle storage operations
Add error handling for storage operations in state.js

3. Initialization Flow

Load existing state from local storage on app start
Only generate new AI data if no existing data is found in local storage
Maintain ability to manually regenerate data when needed

4. Error Handling (for State Persistence)

Add proper error handling for local storage operations
Provide user feedback when data loading/saving from/to local storage fails
Fall back to in-memory state if local storage is unavailable or fails

5. Testing (State Persistence for AI Data Regeneration)

Verify data persistence across page refreshes
Test state persistence with different browsers
Verify error handling and edge cases for state persistence

Checkpoint 3: AI Data Transparency (2025-06-06)

Problem (AI Data Transparency)

No visual indicator showing the source of the currently displayed data
Different Gemini model capabilities may produce different quality results

Solution

Track Data Source
- Add isAIGenerated (boolean) and aiModelUsed (string) fields to the data returned by the AI service. (Note: Server (functions/api/gemini.js) currently logs the AI model used, e.g., gemini-2.0-flash. This information needs to be formally included in the JSON response to the client.)
- Ensure the client-side aiService.js parses these new fields from the /api/gemini function's response.
- Store this data source information (e.g., isAIGenerated: true, aiModelUsed: 'gemini-2.0-flash', or isAIGenerated: false if AI fails and an error/alternative is shown) in the application's state (e.g., in js/state.js).
Visual Indicator
- Create a UI element (e.g., a small text label or icon) in index.html to display the source of the energy recommendations.
- Style this indicator. For example: "AI: Gemini Flash" (blue text/icon), "AI: Gemini Pro 1.5" (purple text/icon), or "Recommendations unavailable" (grey text/icon).
- Add a hover tooltip to the indicator providing more context, like "Powered by Google Gemini 2.0 Flash model." or "AI recommendations could not be generated at this time."
Gemini Model Updates [COMPLETED - Primary Objective]
- ~~Update available Gemini models to include newer versions~~ Investigated model availability using list-gemini-models.js script. Found gemini-2.5-flash-preview and gemini-2.0-pro were unavailable (404 errors).
- ~~Add Gemini 2.5 Flash Preview for improved reasoning capabilities~~ Prioritized available models: gemini-2.0-flash (primary), gemini-1.5-pro (fallback 1), gemini-pro (fallback 2).
- Keep configuration flexible for future model updates - Implemented in js/aiService.js (client) and functions/api/gemini.js (server proxy) with clear model lists and fallback logic.
- Resolved 500 error in functions/api/gemini.js caused by ReferenceError: modelToUse is not defined.
- Ensured client (dist folder) and server code are synchronized during deployments.
Testing
- Verify indicator correctly shows data source
- Test fallback scenario when AI API fails
- Confirm indicator persists across page refreshes

FilesExpand file tree

TODO.md

Latest commit

History