SolarWatch

SolarWatch is a full-stack Java + React demo that shows authentication, external API integrations (weather, maps, sunrise/sunset) and an AI chat microservice on a single dashboard.


· View Demo ·

Table of Contents

1. About The Project
   • Built With
2. Getting started with Docker
   • Prerequisites
   • Quick start
   • Managing the stack
3. Getting Started
   • Prerequisites
   • Installation
4. Usage
5. Contact

About The Project

A full‑stack demo showing authentication and multiple integrations on a single dashboard:

• Sunrise and sunset times for a selected city
• Weather summary cards (temperature, pressure, humidity, wind)
• Google Maps city embed (Google Cloud Maps Embed API)
• AI chat assistant (separate Spring Boot microservice) to ask city‑related questions

The backend (Spring Boot) serves the core API. The AI capability is split into a dedicated microservice so secrets (AI keys) never reach the browser. The frontend (React + Vite + Tailwind) provides an accordion chat panel, loading states, and a dark, glassy UI.

External APIs used:
· Sunset and sunrise times API ·
· Geocoding API (OpenWeather) ·
· Google Maps Embed API (Google Cloud) ·

(back to top)

Built With

• 
• 
• 
• 

(back to top)

Architecture at a glance

• solarwatch-backend (Spring Boot, :8080): authentication and solar endpoints
• solarwatch-ai-service (Spring Boot, :8082): AI chat microservice with multi-provider support (Gemini default, OpenAI optional)
• solarwatch-frontend (Vite React, :5173): UI with Vite proxy to backend and AI service

Dev proxy (Vite):

• /api → http://localhost:8080 (backend)
• /api/ai → http://localhost:8082 (AI microservice)

(back to top)

Getting started with Docker

Run the full stack (frontend + backend + AI microservice + database + dev Nginx reverse proxy) using Docker.

Prerequisites using Docker

• Docker Desktop (Windows/macOS) or Docker Engine (Linux)
• Docker Compose v2 (bundled with Docker Desktop)

Quick start (single command)

1. Open a terminal and navigate to the project root (the folder containing docker-compose.yml).
2. Create a .env file with at least:

   DATABASE_USERNAME=postgres
   DATABASE_PASSWORD=postgres
   OPENWEATHER_API_KEY=your_openweather_key
   
   # AI provider (default: gemini)
   AI_PROVIDER=gemini
   GOOGLE_API_KEY=your_gemini_api_key
   AI_GEMINI_MODEL=gemini-2.5-flash
   
   # If you prefer OpenAI instead:
   # AI_PROVIDER=openai
   # AI_OPENAI_API_KEY=sk-...
   # AI_OPENAI_MODEL=gpt-4o-mini
   
   # Optional for the map widget
   VITE_GOOGLE_MAPS_EMBED_KEY=your_google_maps_embed_key

3. Build and start the stack in the background:

   docker compose up -d --build

4. (Optional) Tail logs during the first run:

   docker compose logs -f

5. Open the app via the dev reverse proxy (Nginx):
   • App (proxied): http://localhost/
     • Nginx forwards / → Vite dev server, /api → backend, /api/ai → AI microservice
   • Direct services (useful for debugging):
     • Frontend Vite: http://localhost:5173/
     • Backend API: http://localhost:8080/
     • AI health: http://localhost:8082/actuator/health

Managing the stack

• See running services:

  docker compose ps

• Stop and remove containers (keep data volumes):

  docker compose down

• Stop only (keep containers for quick restart):

  docker compose stop

• Rebuild images without cache:

  docker compose build --no-cache

• Reset everything (containers and volumes, e.g., wipe the DB):

  docker compose down -v

(back to top)

Getting Started

This section explains how to run the project locally. Follow the steps below:

Prerequisites

• Node.js and npm (frontend)
• Java 21+ (Spring Boot services)
• IntelliJ IDEA or another IDE

Installation & Local development

Frontend (React + TypeScript)

1. Navigate to solarwatch-frontend/
2. Install packages:

   npm install

3. Start the development server:

   npm run dev

4. Open http://localhost:5173/

Backend (Spring Boot)

1. Open the backend/ folder in IntelliJ IDEA.

2. Run the project using the green arrow (from the Spring Boot main class, e.g. Application.java).

   • Alternatively, you can start the backend from the terminal with:

   mvn spring-boot:run

3. The backend will be available at http://localhost:8080/ by default.

(back to top)

Usage

1. Register and log in.
2. Open the SolarWatch dashboard.
3. Enter a city to see:
   • Sunrise and sunset times
   • Weather summary cards (temperature, pressure, humidity, wind)
   • Google Maps city embed (if VITE_GOOGLE_MAPS_EMBED_KEY is set)
   • AI Assistant accordion → ask questions about the selected city

Notes

• The AI service uses a separate API key on the server. If the provider returns 429 (insufficient quota), you’ll see a friendly message in the UI.
• In development, Vite proxies /api to :8080 and /api/ai to :8082.

Environment variables

AI microservice (server):

• AI_PROVIDER – gemini (default) or openai
• For Gemini:
  • GOOGLE_API_KEY – required
  • AI_GEMINI_MODEL – optional (default: gemini-2.5-flash)
• For OpenAI:
  • AI_OPENAI_API_KEY – required
  • AI_OPENAI_MODEL – optional (default: gpt-4o-mini)

Frontend:

• VITE_GOOGLE_MAPS_EMBED_KEY – Google Maps Embed API key (Google Cloud) to show the map

• VITE_AI_BASE_URL – optional for production if the AI service is on a different origin; in dev the proxy is used

  (back to top)

Contact

Délczeg Balázs - dbalazsworkemail@gmail.com

Project Link - GitHub repository

(back to top)