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

### 1. Template Seeding
**Seeder:** `InitialApplicationFormTemplateSeeder`
**File:** `src/main/resources/seed/initial_application_form_template.yaml`
**Condition:** Seeds if no templates exist (`isTemplate = true`)
**Purpose:** Comprehensive IT system approval workflow template

**IMPORTANT:** Keep this file updated when form structure or validation rules change.

### 2. Application Form Seeding
**Seeder:** `InitialApplicationFormSeeder`
**File:** `src/main/resources/seed/initial_application_form.yaml`
**Condition:** Seeds if no forms exist for empty organizationId (`isTemplate = false`)
**Purpose:** Realistic SAP S/4HANA application form for development and UI testing
**organizationId:** Empty string (global form visible to all organizations)
**Content:** Pre-filled IT system introduction form based on the template structure with realistic SAP S/4HANA values

**IMPORTANT:** Keep this file synchronized with template changes. When template structure changes, update the demo form accordingly.

**Note:**
- Forms with empty/null organizationId act as "global" forms and are visible to all organizations
- This allows the demo form to appear regardless of the current organization context
- The demo form is derived from the template structure with values filled for realistic testing
- 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/initial_application_form_template.yaml` | Initial form template (isTemplate=true) |
| `src/main/resources/seed/initial_application_form.yaml` | SAP S/4HANA demo application form (global, filled with realistic values) |
| `src/main/resources/db/changelog/` | Liquibase migrations |
| `src/main/kotlin/com/legalconsenthub/service/ApplicationFormFormatService.kt` | HTML/PDF export logic |

---

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

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

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