gremiumhub/legalconsenthub-backend/CLAUDE.md

Backend - AI Context

Tech Stack

• Framework: Spring Boot 3.4.2
• Language: Kotlin 1.9.25, Java 21
• Database: PostgreSQL
• Migrations: Liquibase (manual)
• PDF Generation: LaTeX (lualatex) via Thymeleaf templates
• API: Auto-generated server stubs from OpenAPI spec

---

Development

# Run backend (port 8080)
./gradlew bootRun

# Build
./gradlew build

# Generate server stubs (after OpenAPI spec changes)
./gradlew generate_legalconsenthub_server

# Database migrations
# Never create Liquibase changesets in src/main/resources/db/changelog/

---

Seed Data Maintenance

The application automatically seeds initial data on first startup. Seed files are split into smaller section files for easier maintenance.

File Structure

src/main/resources/seed/
├── template/                    # Form template (isTemplate=true)
│   ├── _main.yaml              # Main file with metadata and !include directives
│   ├── section_01_*.yaml       # Individual section files
│   └── ...
├── demo/                        # Demo form (isTemplate=false)
│   ├── _main.yaml
│   ├── section_01_*.yaml
│   └── ...

!include Directive

The _main.yaml files use !include directives to reference section files:

formElementSections:
  - !include section_01_angaben_zum_itsystem.yaml
  - !include section_02_modulbeschreibung.yaml

SplitYamlLoader merges these files before deserialization.

1. Template Seeding

Seeder: InitialApplicationFormTemplateSeeder Directory: src/main/resources/seed/template/ Condition: Seeds if no templates exist (isTemplate = true) Purpose: Comprehensive IT system approval workflow template (16 sections)

IMPORTANT: Keep section files updated when form structure or validation rules change. After any change, also update the flow diagram at docs/form-flow-diagram.md.

2. Application Form Seeding

Seeder: InitialApplicationFormSeeder Directory: src/main/resources/seed/demo/ Condition: Seeds if no forms exist for empty organizationId (isTemplate = false) Purpose: Realistic SAP S/4HANA application form for development and UI testing (11 sections) organizationId: Empty string (global form visible to all organizations)

IMPORTANT: Keep demo form synchronized with template changes. When modifying a template section, update the corresponding demo section.

Note:

• Forms with empty/null organizationId act as "global" forms and are visible to all organizations
• The demo form demonstrates visibility conditions, section spawning, clonable elements, and GDPR compliance features

---

Key Files

File	Purpose
src/main/resources/templates/application_form_latex_template.tex	PDF template
src/main/resources/seed/template/	Form template sections (16 files)
src/main/resources/seed/demo/	Demo form sections (11 files)
src/main/kotlin/.../seed/SplitYamlLoader.kt	YAML merger for !include directives
src/main/resources/db/changelog/	Liquibase migrations
src/main/kotlin/com/legalconsenthub/service/ApplicationFormFormatService.kt	HTML/PDF export logic
docs/form-flow-diagram.md	Visual form flow diagram (update after template changes)

---

Rules for AI

1. Never add SQL migrations - They will be handled by the user
2. Use mapper classes - All DTO ↔ Entity conversions must happen in dedicated mapper classes (never in services/controllers)
3. PDF Export Validation - After changes to form elements, visibility, or spawning:
   • Test both HTML and PDF export for real form instances
   • Verify all element types render correctly
   • Ensure template sections excluded, spawned sections included
   • Hotspots: ApplicationFormFormatService.kt, application_form_latex_template.tex
4. Stateless - Any implementation must support statelessness for horizontal scaling (multiple instances behind load balancer)

Architecture Guidelines

• Service layer - Business logic lives here
• Repository layer - JPA repositories for data access
• Controller layer - Thin controllers that delegate to services
• Mapper layer - Separate mapper classes for DTO/Entity conversions
• Entity layer - JPA entities with relationships

Code Quality Rules

• Never use @Suppress annotations - Fix the underlying issue instead of suppressing warnings
• Controller methods must override generated interfaces - All public endpoints must be in OpenAPI spec

PDF Generation

• LaTeX templates in src/main/resources/templates/
• Thymeleaf for dynamic content
• Use lualatex for compilation
• Escape special LaTeX characters in user input
• Test PDF generation after form structure changes