PROJECT OVERVIEW:
The application, tentatively named 'Enerji Geleceği' (Future Energy), is a SaaS platform designed to empower homeowners and businesses to make informed decisions about adopting solar and battery energy systems. The core problem it addresses is the complexity and perceived high upfront cost associated with transitioning to renewable energy. By leveraging current and projected cost data for solar panels and batteries, alongside regional energy pricing and solar insolation data, the platform provides personalized, cost-benefit analyses. The value proposition is clear: enable users to significantly reduce their electricity bills and carbon footprint by identifying the most cost-effective and efficient solar and battery solutions tailored to their specific needs and location, thereby democratizing access to affordable, sustainable energy.
TECH STACK:
- Frontend Framework: React (using Vite for fast development)
- Styling: Tailwind CSS for rapid UI development and utility-first styling.
- State Management: Zustand for efficient and simple global state management.
- Routing: React Router DOM for client-side navigation.
- Charting Library: Chart.js or Recharts for visualizing energy production, consumption, and cost savings.
- API Calls: Axios for making HTTP requests to potential backend services (or for fetching mock data during MVP).
- Form Handling: React Hook Form for efficient and reusable form management.
- Icons: Heroicons for a clean and consistent icon set.
CORE FEATURES:
1. **User Input & Profile Creation:**
* **User Flow:** Upon first visit, users are greeted with a brief onboarding explaining the platform's benefits. They are then prompted to create a profile. This involves entering their location (country, city/region for precise solar data), average monthly electricity bill, household/business size (e.g., number of occupants, square footage), roof orientation and pitch (simplified input, e.g., 'South-facing, moderate pitch'), and typical energy usage patterns (e.g., high daytime usage, evening peak).
* **Details:** Location is crucial for solar insolation and grid electricity pricing. Usage patterns help in sizing battery storage appropriately. Input fields should be intuitive with clear labels and helper text. Validation will ensure necessary data is provided.
2. **Cost & Savings Analysis Engine:**
* **User Flow:** After profile creation, the system processes the user's data. It queries an internal database (or mock data source) for current solar panel costs, battery costs, installation fees, and government incentives applicable to the user's region. It also fetches solar insolation data for the provided location and calculates potential energy generation. The engine then projects the total system cost, potential energy savings based on current electricity rates, and estimates a payback period (Return on Investment - ROI).
* **Details:** This is the core logic. It needs to consider factors like degradation rates of panels and batteries over time, electricity price inflation, and system efficiency. The output should be presented clearly with key metrics highlighted.
3. **System Recommendation & Comparison:**
* **User Flow:** Based on the analysis, the platform suggests 2-3 optimized system configurations (e.g., 'Small Rooftop Solar + Mid-Size Battery', 'Large Solar Array with High-Capacity Battery'). Users can click on these recommendations to view detailed breakdowns, including specific component suggestions (hypothetical models), estimated generation/storage capacity, total cost, monthly savings, and ROI.
* **Details:** Users should be able to compare these recommended configurations side-by-side, allowing them to weigh different options based on upfront cost, long-term savings, or capacity.
4. **Simulation & Visualization:**
* **User Flow:** For a selected recommendation, users can access a simulation module. This allows them to visualize their potential energy production vs. consumption over a typical day or month, showing how the solar panels and battery would interact to meet their needs and reduce reliance on the grid. Charts will illustrate savings over time.
* **Details:** Interactive charts are key here. Users should see how much energy is self-consumed, how much is stored, and how much is drawn from the grid (ideally showing a significant reduction).
UI/UX DESIGN:
- **Layout:** Single Page Application (SPA) with a clean, intuitive navigation. A header for branding and main navigation (e.g., 'Analyze', 'My Systems', 'Settings'). A main content area that dynamically updates based on user interaction. A footer with links to About, Contact, and Terms of Service.
- **Color Palette:** Primary: A calming, trustworthy blue (#4A90E2). Secondary: An energetic, positive green (#50E3C2) for savings and success indicators. Accent: A neutral grey (#F5F5F5) for backgrounds and cards. Text: Dark grey (#333333) for readability. Warnings/Errors: A subtle orange/red (#F5A623).
- **Typography:** A clean, modern sans-serif font like Inter or Poppins for headings and body text. Ensure good hierarchy using font weights and sizes.
- **Responsive Design:** Mobile-first approach. Use Tailwind's responsive modifiers (sm:, md:, lg:) extensively. Ensure all components adapt gracefully to different screen sizes, from small mobile devices to large desktop monitors. Grids and flexbox will be used for layout.
- **Interactions:** Subtle hover effects on buttons and interactive elements. Smooth transitions for route changes and modal popups. Clear loading indicators (spinners, skeleton screens) for data fetching.
COMPONENT BREAKDOWN:
- **`App.jsx`**: Main application component, sets up routing and global layout.
- Props: None
- Responsibility: Renders `Header`, `Footer`, and the main `Router` outlet.
- **`Header.jsx`**: Navigation bar.
- Props: `logo` (string), `navItems` (array of objects {name: string, path: string})
- Responsibility: Displays application logo and navigation links.
- **`Footer.jsx`**: Footer containing utility links.
- Props: `links` (array of objects {name: string, url: string})
- Responsibility: Displays footer links.
- **`HomePage.jsx`**: Landing page, directs users to analysis or login.
- Props: None
- Responsibility: Introduces the app, calls to action.
- **`AnalysisPage.jsx`**: Main page for user input and displaying results.
- Props: None
- Responsibility: Orchestrates the user input forms, analysis engine calls, and displays results components.
- **`UserInputForm.jsx`**: Form for collecting user data (location, consumption, etc.).
- Props: `onSubmit` (function)
- Responsibility: Renders form fields, handles input changes, validates, and calls onSubmit.
- **`ResultsDisplay.jsx`**: Displays the analysis results, recommendations, and charts.
- Props: `analysisData` (object)
- Responsibility: Renders summary metrics, recommendations, and triggers simulation/comparison views.
- **`RecommendationCard.jsx`**: Displays a single system recommendation.
- Props: `recommendation` (object {title: string, cost: number, roi: number, savings: number}), `onClick` (function)
- Responsibility: Shows key details of one recommendation option.
- **`ComparisonTable.jsx`**: Allows side-by-side comparison of multiple recommendations.
- Props: `recommendations` (array of objects)
- Responsibility: Displays detailed feature comparison.
- **`SimulationChart.jsx`**: Renders interactive charts for energy simulation.
- Props: `simulationData` (object), `chartType` (string)
- Responsibility: Visualizes energy flow and savings over time.
- **`LoadingSpinner.jsx`**: Reusable loading indicator.
- Props: None
- Responsibility: Provides visual feedback during data loading.
DATA MODEL:
- **Global State (`store.js` using Zustand):**
```javascript
{
userProfile: {
location: { lat: number | null, lon: number | null, city: string, country: string },
consumption: { avgMonthlyBill: number, usagePattern: 'low' | 'medium' | 'high' },
property: { roofOrientation: string, roofPitch: string }
} | null,
analysisResults: {
potentialGeneration: number, // kWh/year
totalSystemCost: number, // EUR
estimatedSavings: number, // EUR/year
roi: number, // years
recommendations: Array<{ id: string, title: string, description: string, systemDetails: object, cost: number, roi: number, savings: number }>
} | null,
isLoading: boolean
}
```
- **Mock Data (`mockData.js`):
```javascript
// Example for a specific location/profile scenario
const mockAnalysisData = {
location: { city: 'Berlin', country: 'Germany', lat: 52.52, lon: 13.40 },
consumption: { avgMonthlyBill: 150, usagePattern: 'medium' },
property: { roofOrientation: 'south', roofPitch: 'moderate' },
potentialGeneration: 4500, // kWh/year
totalSystemCost: 12000, // EUR
estimatedSavings: 800, // EUR/year
roi: 15, // years
recommendations: [
{
id: 'rec1',
title: 'Standard Rooftop Solar + Battery',
description: 'A balanced system for average needs.',
systemDetails: { panels: { wattage: 5000, count: 15 }, battery: { capacity: 10, type: 'Li-ion' } },
cost: 12000,
roi: 15,
savings: 800
},
{
id: 'rec2',
title: 'High-Efficiency Solar Only',
description: 'Maximize generation with less storage.',
systemDetails: { panels: { wattage: 6000, count: 18 }, battery: { capacity: 0, type: 'None' } },
cost: 10000,
roi: 12,
savings: 700
}
]
};
// Mock data for regional solar insolation, energy prices etc. would also be here.
const mockRegionData = {
'Germany': { avgSolarInsolation: 1000, avgPricePerKwh: 0.30, incentives: [ { name: 'Federal Subsidy', value: 1000 } ] },
// ... more regions
};
```
ANIMATIONS & INTERACTIONS:
- **Hover Effects:** Subtle scale-up or background color change on buttons, links, and cards.
- **Transitions:** Smooth fade-in/fade-out for components appearing or disappearing (e.g., when switching between analysis steps). Route transitions using `CSSTransition` or `Framer Motion` for a polished feel.
- **Loading States:** Use skeleton loaders for forms and results sections while data is being fetched. Display a prominent spinner component (`LoadingSpinner.jsx`) for longer operations.
- **Micro-interactions:** Input field focus states, subtle animations on chart data points appearing, smooth expansion/collapse of sections in the comparison table.
EDGE CASES:
- **Empty States:** When no analysis has been performed yet, the results area should display a clear message guiding the user to complete the input form. Similarly, if a user has no saved systems, the 'My Systems' page should indicate this clearly.
- **Error Handling:** Network errors during data fetching should be caught and displayed gracefully to the user (e.g., 'Could not fetch data, please try again.'). Form validation errors should be clearly highlighted next to the relevant input fields.
- **Validation:** Implement robust client-side validation for all input fields in `UserInputForm.jsx` (e.g., ensuring numbers are within reasonable ranges, required fields are filled). Consider basic server-side validation if a backend is introduced.
- **Accessibility (a11y):** Use semantic HTML elements. Ensure proper ARIA attributes where necessary. Keyboard navigation should be fully supported. Color contrast ratios must meet WCAG AA standards. Focus management for modals and interactive elements.
SAMPLE DATA:
(See DATA MODEL section for mock data examples. Additional examples would include:
- More `mockAnalysisData` for different user profiles (e.g., high-consumption business, low-consumption apartment).
- Detailed `mockRegionData` including hourly electricity price variations and detailed solar insolation by month.
- `mockIncentiveData` specific to various countries and regions.)
DEPLOYMENT NOTES:
- **Build Tool:** Vite is recommended for its speed. `npm run build` command.
- **Environment Variables:** Use `.env` files to manage API keys, base URLs, and feature flags. Ensure sensitive information is not committed to version control.
- **Performance Optimizations:** Code splitting with React.lazy for routes/components. Image optimization. Memoization (`React.memo`, `useMemo`, `useCallback`) to prevent unnecessary re-renders. Lazy loading of components not immediately visible.
- **Hosting:** Static site hosting platforms like Vercel, Netlify, or GitHub Pages are suitable for the frontend. If a backend is added, consider scalable cloud solutions (e.g., AWS, Google Cloud, Azure).
- **HTTPS:** Essential for security, especially when handling any user data.