smartbooking/CLAUDE.md

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

# 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

# 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

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

Testing

# 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

# 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

# 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

# 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

# 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:

# 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