# CLAUDE.md

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

## Build Commands

### Backend (Maven)
```bash
# Full build and deploy
mvn deploy -U -f pom.xml

# Run integration tests with Docker
mvn deploy -P docker -f hartmann-foto-documentation-docker/pom.xml
```

### Frontend (Flutter)
```bash
cd hartmann-foto-documentation-frontend

# Install dependencies
flutter pub get

# Build for web
flutter build web --no-tree-shake-icons

# Run tests with coverage
flutter test --coverage --reporter=json

# Run a single test file
flutter test test/path/to/test_file.dart

# Static analysis
flutter analyze

# Generate localization files
flutter gen-l10n
```

## Architecture

### Multi-Module Maven Project
- **hartmann-foto-documentation-app** - Backend REST API (jar)
- **hartmann-foto-documentation-web** - WAR deployment package
- **hartmann-foto-documentation-docker** - Docker/integration tests
- **hartmann-foto-documentation-frontend** - Flutter mobile/web app

### Technology Stack
- **Backend:** Java 21, WildFly 26.1.3, Jakarta EE 10, Hibernate 6.2, PostgreSQL 11, JWT auth
- **Frontend:** Flutter 3.3.0+, Provider for state management, go_router for navigation
- **API Docs:** Swagger/OpenAPI v3

### Backend Layered Architecture
```
REST Resources → Services (@Stateless EJBs) → QueryService → JPA Entities
```

Key packages in `hartmann-foto-documentation-app/src/main/java/marketing/heyday/hartmann/fotodocumentation/`:
- `core/model/` - JPA entities (User, Right, Customer, Picture, JwtRefreshToken)
- `core/service/` - Business logic with AbstractService base class
- `core/query/` - QueryService for database operations
- `rest/` - JAX-RS resources and value objects

### Frontend Structure
```
lib/
├── main.dart          # Entry point (MaterialApp.router)
├── controller/        # Business logic controllers
├── pages/             # Feature-based UI (login/, customer/)
├── dto/               # Data Transfer Objects
├── utils/             # DI container, theme, routing
└── l10n/              # Localization (German supported)
```

### Authentication
- JWT token-based authentication with refresh tokens
- WildFly Elytron security realm
- Bearer token auth for REST endpoints
- User passwords stored with salt-based hashing

### Database Entities
- User ↔ Right (many-to-many via user_to_right)
- Customer → Picture (one-to-many)
- JwtRefreshToken (device/IP tracking)

Named queries pattern: `@NamedQuery` on entities (e.g., `User.BY_USERNAME`)

## Local Development

Docker Compose provides PostgreSQL and WildFly:
```bash
cd hartmann-foto-documentation-docker
docker-compose up
```

Port mappings: WildFly HTTP (8180), Management (9990), SMTP (8280)

## CI/CD

Jenkins pipeline with SonarQube integration. Build runs on macOS agent with JDK 21.