# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

This is a JHipster 9.0.0-beta.0 monolithic application named "smartbooking" - a booking management system for public facilities (Comune di Artegna). The application combines:

- Backend: Spring Boot with Java 17, Gradle, PostgreSQL, Spring Security (session-based authentication)
- Frontend: Vue 3, Vite, TypeScript, Bootstrap Vue Next, Pinia for state management
- Entities: AuditLog, Disponibilita, Notifica, Prenotazione, Conferma, Struttura, UtenteApp, Liberatoria, ModelloLiberatoria, Messaggio

## Development Commands

### Backend Development

```bash
# Start backend only (without frontend compilation)
./gradlew -x webapp -x webapp_test

# Shorthand backend start
./npmw backend:start

# Run backend tests
./gradlew test integrationTest

# Unit tests only
./npmw backend:unit:test
```

### Frontend Development

```bash
# Install dependencies (run when package.json changes)
./npmw install

# Start frontend dev server with hot reload
./npmw start

# Build frontend for production
./npmw build
```

### Full Development Workflow

```bash
# Run both backend and frontend concurrently
./npmw watch
# OR in two separate terminals:
./npmw backend:start
./npmw start
```

### Testing

```bash
# Frontend unit tests (Vitest)
./npmw test

# Watch mode for tests
./npmw test:watch

# E2E tests (Cypress)
./npmw e2e

# Run E2E in headless mode
./npmw e2e:headless

# Lighthouse audits
./npmw run e2e:cypress:audits
```

### Code Quality

```bash
# Lint JavaScript/TypeScript
./npmw lint

# Lint with auto-fix
./npmw lint:fix

# Format code with Prettier
./npmw prettier:format

# Check formatting
./npmw prettier:check
```

### Production Build

```bash
# Build production JAR
./gradlew -Pprod clean bootJar

# Build production WAR
./gradlew -Pprod -Pwar clean bootWar

# Run production JAR
java -jar build/libs/*.jar
```

### Docker Operations

```bash
# Start required services (PostgreSQL)
docker compose -f src/main/docker/services.yml up -d

# Stop services
docker compose -f src/main/docker/services.yml down

# Build Docker image
npm run java:docker

# Build for ARM64 (Apple Silicon)
npm run java:docker:arm64

# Start entire application in Docker
docker compose -f src/main/docker/app.yml up -d
```

### Database Management

```bash
# Start PostgreSQL for development
./npmw docker:db:up

# Stop PostgreSQL
./npmw docker:db:down
```

## Architecture Overview

### Backend Structure (Java/Spring Boot)

**Package: `it.sw.pa.comune.artegna`**

- **`domain/`**: JPA entities with Hibernate mappings
  - Entities use `AbstractAuditingEntity` for audit fields (createdBy, createdDate, lastModifiedBy, lastModifiedDate)
  - `User` and `Authority` for authentication/authorization
  - Business entities: Struttura, Prenotazione, Disponibilita, etc.

- **`repository/`**: Spring Data JPA repositories
  - Extend `JpaRepository` for CRUD operations
  - Custom queries using Spring Data query methods

- **`service/`**: Business logic layer
  - Service interfaces and implementations (annotated with `@Service`)
  - `UserService` for user management
  - `MailService` for email notifications

- **`service/dto/`**: Data Transfer Objects
  - DTOs for API communication
  - `AdminUserDTO`, `UserDTO`, `PasswordChangeDTO`, etc.

- **`service/mapper/`**: MapStruct mappers
  - Entity to DTO conversions
  - Uses MapStruct annotation processor

- **`web/rest/`**: REST API controllers
  - `@RestController` with `/api` prefix
  - `AccountResource`, `UserResource`, entity resources
  - Security enforcement via Spring Security

- **`security/`**: Security configuration
  - `SecurityConfiguration`: Main security setup with session authentication
  - `SecurityUtils`: Helper methods for accessing security context
  - `AuthoritiesConstants`: Role definitions (ADMIN, USER)
  - Custom CSRF handler for SPA: `SpaCsrfTokenRequestHandler`

- **`config/`**: Application configuration
  - `ApplicationProperties`: Custom application properties
  - `SecurityConfiguration`: Spring Security setup
  - `LiquibaseConfiguration`: Database migration
  - `WebConfigurer`: Web layer configuration

### Frontend Structure (Vue 3 + TypeScript)

**Path: `src/main/webapp/app/`**

- **`router/`**: Vue Router configuration
  - `index.ts`: Main router setup with history mode
  - Routes split into: `account`, `admin`, `entities`, `pages`
  - Route guards for authentication/authorization

- **`core/`**: Core application components
  - `home/`: Landing page
  - `jhi-navbar/`: Navigation bar
  - `jhi-footer/`: Footer
  - `error/`: Error page component

- **`shared/`**: Reusable components and utilities
  - `config/store/`: Pinia stores for global state
  - `composables/`: Vue composables for shared logic
  - `sort/`: Sorting utilities and components
  - `alert/`: Alert/notification service

- **`account/`**: User account management
  - `login-form/`: Login component
  - `register/`: Registration
  - `settings/`: User settings
  - `change-password/`: Password change
  - `activate/`, `reset-password/`: Account activation and password reset

- **`admin/`**: Admin panel components
  - `user-management/`: User administration
  - `health/`, `metrics/`, `configuration/`: Monitoring
  - `docs/`: API documentation (Swagger UI)
  - `logs/`: Log level management

- **`entities/`**: CRUD interfaces for business entities
  - Each entity has: list view, details, create/update, delete
  - Uses Vue Router for navigation
  - Components: `{entity}.vue`, `{entity}-details.vue`, `{entity}-update.vue`

### State Management

- **Pinia stores** in `src/main/webapp/app/shared/config/store/`
- **Translation store** (`translation-store.ts`): i18n management
- Entity-specific stores typically in entity directories

### Authentication Flow

1. Session-based authentication via Spring Security
2. Login endpoint: `POST /api/authentication` (form login)
3. Logout endpoint: `POST /api/logout`
4. Account info: `GET /api/account`
5. CSRF protection using cookie-based tokens for SPA
6. Remember-me functionality with persistent tokens in database

### API Security

- Most `/api/**` endpoints require authentication
- Admin endpoints (`/api/admin/**`) require `ADMIN` role
- Public endpoints: `/api/authenticate`, `/api/register`, `/api/activate`, password reset
- CSRF protection enabled with cookie repository

### Database Schema

- Managed by Liquibase
- Changelog files: `src/main/resources/config/liquibase/`
- Entity definitions in `.jhipster/*.json`
- JPA/Hibernate for ORM with PostgreSQL

### Entity Relationships (Key Examples)

**Struttura** (Facility):

- One-to-many with Disponibilita (availability slots)
- One-to-many with ModelloLiberatoria (waiver templates)

**Prenotazione** (Booking):

- Many-to-one with UtenteApp (user)
- Many-to-one with Struttura (facility)
- One-to-one with Conferma (confirmation)
- Enum: StatoPrenotazione (RICHIESTA, CONFERMATA, RIFIUTATA, ANNULLATA)

### Important Files

- **`.yo-rc.json`**: JHipster configuration (application type, auth, database, etc.)
- **`.jhipster/*.json`**: Entity definitions for JHipster generator
- **`build.gradle`**: Gradle build configuration with Spring Boot plugin
- **`package.json`**: Node.js dependencies and npm scripts
- **`src/main/resources/config/application.yml`**: Spring Boot configuration
- **`vite.config.mts`**: Vite build configuration

### Code Generation

This is a JHipster-generated application. To add/modify entities:

```bash
# Generate a new entity
jhipster entity <EntityName>

# Regenerate existing entities
jhipster
```

Entity modifications should be done via JHipster generators to maintain consistency between backend and frontend.

### Testing Strategy

- **Backend**: JUnit 5, Spring Boot Test, Testcontainers for integration tests
  - Unit tests: `*Test.java`
  - Integration tests: `*IT.java`
  - Test containers for PostgreSQL in `@IntegrationTest` annotated classes

- **Frontend**: Vitest for unit tests, Cypress for E2E
  - Component tests: `*.spec.ts` next to components
  - E2E tests: `src/test/javascript/cypress/`

### Internationalization

- Backend: Spring MessageSource, properties files in `src/main/resources/i18n/`
- Frontend: Vue I18n, JSON files in `src/main/webapp/i18n/it/`
- Native language: Italian (`it`)

## Development Notes

- Use `./npmw` wrapper instead of `npm` for Node.js version consistency
- Gradle automatically installs Node.js and npm locally
- Frontend runs on port 9000 (dev server)
- Backend runs on port 8080
- API endpoints are proxied from frontend to backend during development
- Spring Docker Compose integration auto-starts required services in dev mode