# 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

```bash
# 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:
```yaml
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