Skip to content

CLAUDE.md

Latest commit

 

History

History
226 lines (138 loc) · 4.92 KB

CLAUDE.md

File metadata and controls

226 lines (138 loc) · 4.92 KB
Raw

SkyLuma AI Coding Guidelines

This file contains project guidance for AI assisted development in SkyLuma.

It is not generated by Angular CLI.

SkyLuma is a weather forecast app built with Spring Boot and Angular.

The project is based on an older weather app, but it is not a direct migration. The goal is to build a cleaner and more modern version.

Project structure

The project uses one repository:

SkyLuma/
  backend/   Spring Boot REST API
  frontend/  Angular app

Project direction

Keep the app simple and easy to review.

Prefer small focused PRs instead of large rewrites.

Avoid extra abstractions unless they solve a real problem in the current code.

Use simple names and simple code.

Backend guidelines

The backend uses:

  1. Java 21
  2. Spring Boot
  3. Maven
  4. Lombok
  5. YAML config
  6. Package root com.skyluma.weather

Use Lombok where it improves readability.

Do not commit API keys, secrets, tokens, or local environment files.

Use OPENWEATHER_API_KEY for the OpenWeather API key.

Run backend tests with:

cd backend
./mvnw test

Backend package rules

Keep backend code grouped by feature or provider where it makes sense.

Current main backend areas:

  1. forecast/ for the public weather API, DTOs, controller, service, and provider abstraction
  2. openmeteo/ for Open Meteo integration
  3. openweather/ for OpenWeather integration
  4. config/ for application config
  5. common/ for shared API and error handling code

Provider clients, DTOs, mappers, and provider classes should stay under their provider package.

Shared API response DTOs should stay under the forecast package.

Weather providers

SkyLuma currently supports:

  1. Open Meteo
  2. OpenWeather

Open Meteo is the default provider because it works without an API key for basic forecast data.

OpenWeather is optional and requires an API key.

The backend can choose a default provider from config.

The frontend can also send a provider for a single weather request.

Provider values should stay stable.

Use enums for provider API values instead of copying raw strings across the backend.

Supported provider values:

openmeteo
openweather

Weather alerts

Weather alerts depend on the selected provider.

The current Open Meteo implementation gives forecast data, but it does not give official weather alerts.

OpenWeather can return alerts when the API returns them.

The frontend should not say that there are no alerts when the selected provider does not support alerts. It should show a clear message that alerts are not available from that provider.

Backend strings and errors

Do not add JSON files or global helper classes just to move backend strings out of the code.

Inline backend exception messages are fine when they are used once.

Use private static final only when the same message or value is repeated in the same class.

Do not make frontend behavior depend on backend error message text.

If the frontend needs to react to specific backend errors later, add stable error codes instead of matching message strings.

Keep backend log and exception messages in English.

Frontend guidelines

The frontend uses:

  1. Angular
  2. TypeScript
  3. SCSS
  4. Angular routing
  5. Standalone components

Keep feature code grouped under Angular feature areas.

Prefer:

  1. typed interfaces and models
  2. services for API calls
  3. components focused on UI and user interaction
  4. SCSS files for styling

Run frontend build with:

cd frontend
npm run build

Frontend text and translations

Keep UI text in the frontend.

Do not move frontend labels to the backend.

Do not add translations until we actually need more languages.

If translations are added later, translate frontend labels and client facing error messages in the frontend.

Backend API responses should provide stable data and error codes, not translated UI text.

Local development

Run backend and frontend separately.

Backend:

cd backend
./mvnw spring-boot:run

Frontend:

cd frontend
npm start

Backend runs on:

http://localhost:8080

Frontend runs on:

http://localhost:4200

Angular sends /api requests to the backend during local development.

Testing and validation

Run backend tests after backend changes:

cd backend
./mvnw test

Run frontend build after frontend changes:

cd frontend
npm run build

For changes that touch both backend and frontend, run both.

PR style

Keep pull requests small and focused.

Good examples:

  1. fix: validate coordinate inputs
  2. feat: show weather provider
  3. refactor: centralize provider options
  4. docs: update project documentation

Avoid mixing unrelated backend, frontend, and docs changes unless they are part of the same visible behavior.

When changing the backend API response, update the frontend models and services in the same PR if needed.

Prefer clear names over clever abstractions.

Prefer code that is easy to read and easy to review.