Solar Panel Calculator - Desktop & Mobile App

🌞 Professional solar PV financial & technical analysis dashboard with glassmorphism UI, high-precision modeling, AI-powered assistance, and Google Solar API integration.

📥 Quick Download (Pick your OS)

Click your operating system to download the latest installer directly:

🪟 Windows (Installer): https://github.com/leothefleo49/Solar-Panel-Calculator/releases/latest/download/Solar-Panel-Calculator-Windows.msi
🪟 Windows (Portable EXE): https://github.com/leothefleo49/Solar-Panel-Calculator/releases/latest/download/Solar-Panel-Calculator-Windows.exe
🍎 macOS (Universal DMG): https://github.com/leothefleo49/Solar-Panel-Calculator/releases/latest/download/Solar-Panel-Calculator-macOS.dmg
🐧 Linux (AppImage): https://github.com/leothefleo49/Solar-Panel-Calculator/releases/latest/download/Solar-Panel-Calculator-Linux.AppImage
🐧 Linux (Debian/Ubuntu .deb): https://github.com/leothefleo49/Solar-Panel-Calculator/releases/latest/download/Solar-Panel-Calculator-Linux.deb
📱 Android (APK): https://github.com/leothefleo49/Solar-Panel-Calculator/releases/latest/download/Solar-Panel-Calculator-Android.apk
🍏 iOS (Simulator App – for developers): https://github.com/leothefleo49/Solar-Panel-Calculator/releases/latest/download/Solar-Panel-Calculator-iOS-Simulator.zip

Important for Desktop Users:

🔄 Auto-updater requires v1.4.28+: Download and install this version manually to enable automatic updates for future releases!
Once installed, the app will notify you of new versions and offer one-click updates

Platform Notes:

Windows: Use the MSI if unsure. The EXE is a portable run-and-go.
macOS: If blocked, right‑click the app → Open (first run).
Linux AppImage: Right‑click file → Properties → make executable.
Android: Enable "Install unknown apps" in your device settings.
iOS: See iOS Deployment Options below for web/PWA/self-build instructions.

✨ Features

Core Capabilities

🌍 Google Solar API Integration (Enhanced in v1.4.28+):
- Analyze any property address with real-world roof data from Google's Solar API
- Automatic geocoding and coordinate lookup
- Detailed roof segment analysis (pitch, azimuth, area, sun exposure)
- AI-powered recommendations using actual roof geometry
- Financial projections based on real sun exposure data
- Enhanced Setup Wizard: 3 recommended paths (easiest, most free, best quality)
- Instant Config Updates: Save Changes button applies settings without restart
- API Validation (v1.4.28): Pre-save key testing with detailed error messages
- Quota Monitoring (v1.4.28): Real-time usage tracking with visual indicators
- Flexible key management (unified or separate for Solar/Maps/Shopping)
- Optional - app works fully without Google APIs
🛒 Shopping Cart with AI Search (Enhanced in v1.4.28):
- Smart product search supporting names, model numbers, UPC, ASIN, brand names
- AI-powered query enhancement for better results
- Multi-site fallbacks with source attribution (Amazon, Walmart, Home Depot, Lowes, eBay)
- Category filtering and intelligent result ranking
- Automatic product spec extraction and compatibility checking
- Integration with Google Shopping API for real-time pricing
- Repetition-aware error reporting with timestamps
Comprehensive Configurator: Collapsible sections for utility costs, incentives, solar hardware, battery storage, and soft costs with contextual tooltips
High-Precision Modeling: Decimal.js engine simulates 25-year production, degradation, inflation-adjusted utility spend, net-metering cash flow, ROI, and break-even timing
Interactive Visualizations: Multi-line crossover charts, degradation trends, monthly production vs. consumption bars, and battery/outage simulator
Data Studio: Sortable amortization table with optional monthly expansion (up to 250 rows) for deep financial analysis
AI Chat Assistant: Multi-provider support (Google Gemini, OpenAI GPT, Anthropic Claude, xAI Grok) with up to 5 concurrent conversation threads and Solar API context integration
Modern UX: Dark-mode glassmorphism panels, responsive layout, accessible tooltips, auto-expanding chat input, fullscreen mode

Desktop App Benefits

✅ Runs completely offline after installation
✅ Automatic updates (v1.4.28+) – Get new features without manual downloads
✅ Secure encrypted API key storage
✅ Native OS integration (taskbar, notifications)
✅ Faster performance vs. browser
✅ No tracking or telemetry
✅ Fullscreen mode support

Mobile App Benefits

📱 Full feature parity with desktop
📱 Touch-optimized UI
📱 Works offline after first load
📱 Install directly from APK/IPA (no app store required)
📱 Persistent chat history and API keys

🚀 For Developers

Desktop App Development

# Clone repo
git clone https://github.com/leothefleo49/Solar-Panel-Calculator.git
cd "Solar-Panel-Calculator/App"

# Install dependencies
npm install

# Run desktop app in development mode
npm run tauri:dev

# Build production executable
npm run tauri:build

Requirements: Node.js 20+, Rust toolchain (rustup.rs)

Output locations:

Windows: src-tauri/target/release/Solar Panel Calculator.exe
macOS: src-tauri/target/release/bundle/macos/
Linux: src-tauri/target/release/solar-panel-calculator

Android App Development

# Build web assets and sync to Android
npm run cap:sync

# Open in Android Studio
npm run cap:android

# Or build APK directly (requires Android SDK)
npm run cap:build:android

Requirements: Android Studio, SDK 33+, Java JDK 17+

Output: android/app/build/outputs/apk/release/app-release-unsigned.apk

Web Development (Traditional)

# Start Vite dev server
npm run dev

# Production build
npm run build

# Preview production build
npm run preview

Open http://localhost:5173

🏗️ Tech Stack

Frontend: React 19 + TypeScript (Vite)
State: Zustand for global state management
Styling: Tailwind CSS + @tailwindcss/forms
Math: Decimal.js for financial precision
Charts: Recharts for data visualizations
Desktop: Tauri 2.x (Rust + WebView)
Mobile: Capacitor 6.x (Native Android)
AI: Multi-provider support (Google, OpenAI, Anthropic, xAI)

🔑 AI Chat Assistant Setup

The optional AI assistant supports Google Gemini, OpenAI GPT, Anthropic Claude, and xAI Grok.

Option 1: Runtime API Keys (Recommended)

Launch the app
Navigate to "Solar Chat Assistant" panel
Select provider tab (Google/OpenAI/Claude/Grok)
Enter API key in the input field
Click "Use Key"

Desktop: Keys are encrypted and stored locally
Mobile/Web: Keys are memory-only (cleared on refresh)

Option 2: Environment Variables (Development)

Create .env in the project root:

VITE_GOOGLE_API_KEY=AIza...
VITE_OPENAI_API_KEY=sk-...
VITE_ANTHROPIC_API_KEY=sk-ant-...
VITE_GROK_API_KEY=xai-...

⚠️ Never commit this file to git!

Supported Models

Google: Gemini 2.5 Pro/Flash, 2.0 Ultra/Flash, 1.5 Pro/Flash (with image upload support)
OpenAI: GPT-5, GPT-4.1, GPT-4o, GPT-4-turbo, GPT-3.5-turbo
Anthropic: Claude 3.5 Sonnet/Haiku, Claude 3 Opus
xAI: Grok-2, Grok-2-mini

Features

✅ Up to 5 concurrent conversation threads
✅ Auto-expanding chat input (up to 3× height)
✅ Image upload support (Gemini only)
✅ System-aware context (array size, ROI, savings)
✅ Enter to send, Shift+Enter for new line

📁 Key Files

src/components/Configurator.tsx – Input interface with tooltips and resource links
src/components/Dashboard.tsx – Tabbed visualizations, charts, outage simulator
src/components/ChatAssistant.tsx – Multi-provider AI chat interface
src/state/solarStore.ts – Zustand store for configuration data
src/state/chatStore.ts – Zustand store for conversation threads
src/utils/calculations.ts – High-precision production/savings/ROI math
src/utils/aiProviders.ts – API wrappers for AI providers
src-tauri/ – Rust backend for desktop app
android/ – Native Android project files
capacitor.config.ts – Mobile app configuration

🔒 Security & Privacy

✅ No telemetry or tracking
✅ Calculations run 100% locally
✅ API keys encrypted at rest (desktop)
✅ Open-source—audit the code yourself
✅ Content Security Policy (CSP) enforced
✅ Sandboxed execution (Tauri)

For production deployments, route AI API requests through a secure backend proxy with rate limiting.

📦 Distribution

Automated Releases (CI)

Push a semantic git tag (e.g. v1.4.28) to trigger the CI matrix build:

git tag v1.4.28
git push origin v1.4.28

GitHub Actions produces clearly named artifacts:

SolarPanelCalculator-Setup-x64.msi / SolarPanelCalculator-x64.exe
SolarPanelCalculator-arm64.dmg / SolarPanelCalculator-x64.dmg
SolarPanelCalculator-x86_64.AppImage
solar-panel-calculator_<version>_amd64.deb
solar-panel-calculator-<version>.x86_64.rpm
solar-panel-calculator-release.apk
(Planned) SolarPanelCalculator.ipa (after iOS pipeline added)

Each release also includes a checksum file SHA256SUMS.txt for integrity verification.

Integrity Verification

sha256sum -c SHA256SUMS.txt --ignore-missing

Matches = file is authentic. Mismatch = re-download.

Portable vs Installer (Windows)

Use .msi for start menu shortcuts & automatic uninstall.
Use standalone .exe if running from USB or without admin rights.

Linux AppImage Usage

chmod +x SolarPanelCalculator-x86_64.AppImage
./SolarPanelCalculator-x86_64.AppImage

macOS Gatekeeper

If blocked, right-click → Open (first run) or:

xattr -dr com.apple.quarantine "SolarPanelCalculator-arm64.dmg"

Manual Build

See RELEASE_INSTRUCTIONS.md for detailed build instructions, signing, and troubleshooting.

🐛 Troubleshooting

Desktop App Issues

Windows: Install WebView2
macOS: Allow app in System Preferences → Security & Privacy
Linux: sudo apt install libwebkit2gtk-4.1-dev

Android Issues

Build fails (exit code 1/126): Ensure executable gradlew permissions (chmod +x android/gradlew on Unix CI), verify JDK 17 and Android Gradle Plugin 8.7+, run npm run cap:sync before building.
Dependency resolution errors: Clear Gradle cache rm -rf ~/.gradle/caches (Unix) or use Android Studio Invalidate Caches.
Resource merge failures: Run ./gradlew clean then rebuild.
App crashes on launch: Confirm minSdkVersion (23) device compatibility; run adb logcat to inspect.
APK won't install: Enable "Install from Unknown Sources"; verify architecture (x86 emulator cannot run arm64-only builds).

CORS Errors

iOS (Pending Pipeline)

Use npm run cap:ios to open Xcode after adding iOS platform.
Set signing team: Xcode → Project Settings → Signing & Capabilities.
Increment build number each release.
Export via Archive → Distribute App (TestFlight or Ad Hoc).

Planned CI will produce a signed .ipa once Apple credentials & notarization flow are added. Desktop/Android handle CORS automatically. Web deployment requires backend proxy for AI APIs.

🤝 Contributing

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

📄 License

MIT License - See LICENSE file for details.

🙏 Acknowledgments

Built with Tauri and Capacitor
Charts powered by Recharts
Math precision via Decimal.js
Icons from Heroicons

📞 Support

Issues: GitHub Issues
Discussions: GitHub Discussions
Email: [email protected]
Documentation: RELEASE_INSTRUCTIONS.md

💖 Sponsor

If you find this project useful, consider supporting continued development on GitHub Sponsors:

Sponsor: https://github.com/sponsors/leothefleo49

Donations are not required but are very much appreciated — they help cover maintenance, hosting, and adding new features.

Made with ❤️ by leothefleo49

Name		Name	Last commit message	Last commit date
Latest commit History 193 Commits
.github/workflows		.github/workflows
.vscode		.vscode
App		App
tools		tools
.gitignore		.gitignore
AUTOMATIC_RELEASES.md		AUTOMATIC_RELEASES.md
CI_CD_AUTO_UPDATE.md		CI_CD_AUTO_UPDATE.md
CLIENT_ERROR_REPORTING.md		CLIENT_ERROR_REPORTING.md
DEPLOYMENT_GUIDE.md		DEPLOYMENT_GUIDE.md
EMAIL_NOTIFICATIONS.md		EMAIL_NOTIFICATIONS.md
IMPLEMENTATION_NOTES_v1.4.12.md		IMPLEMENTATION_NOTES_v1.4.12.md
NEXT_STEPS.md		NEXT_STEPS.md
PHONE_QUICK_START.md		PHONE_QUICK_START.md
QUICK_RELEASE.md		QUICK_RELEASE.md
README.md		README.md
RELEASE_GUIDE.md		RELEASE_GUIDE.md
SETUP_COMPLETE.md		SETUP_COMPLETE.md
package-lock.json		package-lock.json
package.json		package.json

leothefleo49/Solar-Panel-Calculator

Folders and files

Latest commit

History

Repository files navigation