# Legal Consent Hub - Project Documentation

## Project Overview

**Legal Consent Hub** is a comprehensive platform for digital applications, approvals, and discussions, designed specifically for organizational workflows involving employee data processing and consent management. The platform enables organizations to create, manage, and track application forms with built-in compliance features for GDPR requirements.

### Key Features

- **Dynamic Form Management**: Create and modify application forms with flexible, runtime-editable structures
- **Template System**: Reusable form templates for common use cases
- **Version Control**: Complete version history with snapshots for audit trails
- **PDF/HTML Export**: Generate professional PDF and HTML documents from forms
- **Collaborative Comments**: Attach comments to specific form elements for discussions
- **Smart Notifications**: User-specific, role-based, or organization-wide notifications
- **Multi-tenancy**: Organization-based data isolation
- **GDPR Compliance**: Built-in processing purposes and employee data categorization

---

## Architecture

### System Components

The application follows a **three-tier architecture**:

1. **Frontend** (`legalconsenthub/`): Nuxt 4 SSR application
2. **Backend** (`legalconsenthub-backend/`): Spring Boot 3 REST API with Kotlin
3. **Middleware** (`legalconsenthub-middleware/`): Client middleware layer (referenced but minimal presence in codebase)

### Technology Stack

#### Frontend
- **Framework**: Nuxt 4.2.0 with Vue 3 (latest)
- **UI Library**: Nuxt UI 4.1.0 (Tailwind-based component library)
- **State Management**: Pinia 3.0.3
- **Internationalization**: @nuxtjs/i18n 10.0.3 (default: German, supports English)
- **Authentication**: nuxt-auth-utils 0.5.25 with OAuth2/Keycloak
- **Type Safety**: TypeScript 5.7.3
- **API Client**: Auto-generated from OpenAPI spec using openapi-generator-cli

#### Backend
- **Framework**: Spring Boot 3.4.2
- **Language**: Kotlin 1.9.25 with Java 21
- **ORM**: Spring Data JPA with Hibernate
- **Database**: PostgreSQL (with H2 for testing)
- **Database Migrations**: Liquibase
- **Authentication**: Spring Security with OAuth2 Resource Server (JWT)
- **API Documentation**: SpringDoc OpenAPI (Swagger UI)
- **PDF Generation**: OpenHTMLToPDF 1.0.10 with Thymeleaf templates
- **Testing**: Spring Boot Testcontainers
- **Code Quality**: ktlint 1.5.0
- **Build Tool**: Gradle

#### Infrastructure
- **Containerization**: Docker
- **Orchestration**: Docker Compose (dev and prod configurations)
- **CI/CD**: Local act execution with GitHub Actions format (`.github/workflows/pipeline.yaml`)

---

## Core Domain Concepts

### 1. Organizations & Multi-tenancy

Users are assigned to **organizations**, which serve as the primary tenant boundary. Each organization:
- Has its own isolated set of application forms
- Has independent notification streams
- Has organization-specific roles and permissions
- Is identified by `organizationId` (string)

### 2. Application Forms

The central entity of the system. Application forms can be:
- **Templates** (`isTemplate: true`): Reusable form blueprints
- **Instances** (`isTemplate: false`): Actual forms being worked on

**Form Status Lifecycle**:
```
DRAFT → SUBMITTED → APPROVED/REJECTED → SIGNED
```

Each form has:
- Name and description
- Status tracking
- Audit fields (createdBy, lastModifiedBy, createdAt, modifiedAt)
- Organization association
- Hierarchical structure of form elements

### 3. Dynamic Form Structure

Forms follow a **three-level hierarchy**:

```
Application Form
  └── Section (FormElementSection)
       ├── title, shortTitle, description
       └── SubSection (FormElementSubSection)
            ├── title, subtitle
            └── Form Elements (FormElement)
                 ├── id (UUID - generated by backend)
                 ├── reference (string - custom key like "art_der_massnahme")
                 ├── type (SELECT, CHECKBOX, RADIOBUTTON, TEXTFIELD, SWITCH, TITLE_BODY_TEXTFIELDS)
                 ├── title, description
                 ├── options (FormOption[])
                 │    ├── value, label
                 │    ├── processingPurpose
                 │    └── employeeDataCategory
                 └── visibilityCondition (FormElementVisibilityCondition)
                      ├── conditionType (SHOW, HIDE)
                      ├── sourceFormElementReference (string - reference key of source element)
                      ├── expectedValue (string - value to compare against)
                      └── operator (EQUALS, NOT_EQUALS, IS_EMPTY, IS_NOT_EMPTY)
```

**Dynamic Addition**: Users can add new form elements to any subsection at runtime via the API endpoint:
```
POST /application-forms/{applicationFormId}/subsections/{subsectionId}/form-elements?position={position}
```

### 4. Version History & Snapshots

Every update to an application form creates a new version:
- Automatic versioning on form updates
- Complete snapshots of form state (JSON-based)
- Ability to restore previous versions
- Audit trail with creator and timestamp
- Versions are immutable once created

### 5. PDF & HTML Generation

Forms can be exported as:
- **HTML**: Rendered using Thymeleaf templates (`templates/application_form_template.html`)
- **PDF**: Generated from HTML using OpenHTMLToPDF library

Endpoints:
- `GET /application-forms/{id}/html` - Returns HTML representation
- `GET /application-forms/{id}/pdf` - Returns PDF (inline display)

### 6. Comments System

Comments enable collaborative discussions:
- Attached to specific **form elements** (not sections/subsections)
- Associated with an application form
- Full CRUD operations
- Tracked with creator and timestamps
- Paginated retrieval per form

### 7. Notifications

Three types of notifications:
1. **User-specific**: Directed to a single user by `recipientId`
2. **Role-based**: Sent to all users with specific roles (`targetRoles[]`)
3. **Organization-wide**: Sent to all members (when both recipientId and targetRoles are null)

Notification types:
- `INFO`, `WARNING`, `ERROR`

Features:
- Mark individual/all as read
- Clear all notifications
- Get unread count (public endpoint for polling)
- Pagination support

### 8. GDPR Compliance Features

Each form option includes:

**Processing Purpose**:
- `SYSTEM_OPERATION`
- `BUSINESS_PROCESS`
- `DATA_ANALYSIS`
- `NONE`

**Employee Data Category**:
- `NON_CRITICAL`
- `REVIEW_REQUIRED`
- `SENSITIVE`
- `NONE`

These enable compliance tracking and risk assessment.

### 9. Role-Based Access Control

User roles in the system:
- `CHIEF_EXECUTIVE_OFFICER`
- `BUSINESS_DEPARTMENT`
- `IT_DEPARTMENT`
- `HUMAN_RESOURCES`
- `HEAD_OF_WORKS_COUNCIL`
- `WORKS_COUNCIL`
- `EMPLOYEE`

Roles are managed via Keycloak and enforced using Spring Security's `@PreAuthorize` annotations.

### 10. Conditional Form Element Visibility

Form elements can be conditionally shown or hidden based on the values of other form elements. This enables dynamic forms that adapt to user input.

**Key Concepts**:

- **Visibility Conditions**: Rules attached to form elements that determine when they should be visible
- **Source Element**: The form element whose value is being evaluated
- **Target Element**: The form element with visibility conditions (the one being shown/hidden)
- **Condition Types**:
  - `SHOW`: Element is visible only if the condition is met
  - `HIDE`: Element is hidden if the condition is met
- **Operators**:
  - `EQUALS`: Source value exactly matches expected value (case-insensitive)
  - `NOT_EQUALS`: Source value does not match expected value
  - `IS_EMPTY`: Source value is empty string
  - `IS_NOT_EMPTY`: Source value is not empty

**Implementation Details**:

- Visibility conditions reference other form elements by their **reference key** (custom string identifier)
- Reference keys are stable and meaningful (e.g., "art_der_massnahme", "testphase_findet_statt")
- Each form element can have one visibility condition (single object, not array)
- Hidden fields are automatically excluded from validation
- PDF/HTML exports only include currently visible fields based on form state
- Versioning system captures visibility conditions in snapshots
- Conditions check the **value** property of form options, not labels

**Example Configuration**:

```json
{
  "reference": "testphase_zeitraum",
  "title": "Testphase Zeitraum",
  "description": "Zeitraum der Testphase",
  "type": "TEXTFIELD",
  "options": [
    {
      "value": "",
      "label": "Testphase Zeitraum",
      "processingPurpose": "SYSTEM_OPERATION",
      "employeeDataCategory": "NON_CRITICAL"
    }
  ],
  "visibilityCondition": {
    "conditionType": "SHOW",
    "sourceFormElementReference": "testphase_findet_statt",
    "expectedValue": "Ja",
    "operator": "EQUALS"
  }
}
```

In this example, the "Testphase Zeitraum" field is only visible when the form element with reference `testphase_findet_statt` has the value "Ja" selected.

**Frontend Behavior**:

- Visibility is evaluated client-side using the `useFormElementVisibility` composable
- Form elements smoothly appear/disappear as conditions change
- Hidden elements are excluded from the form submission

**Backend Behavior**:

- Visibility is evaluated server-side when generating PDF/HTML exports
- Backend filters form elements before rendering to Thymeleaf templates
- Hidden elements are not included in exported documents

**Best Practices**:

- Avoid circular dependencies (A depends on B, B depends on A)
- Use meaningful reference keys (snake_case recommended, e.g., "art_der_massnahme", "testphase_findet_statt")
- Reference keys should be unique within a form
- Keep visibility logic simple for better user experience
- For radio buttons and selects, use the actual label text as the value
- For checkboxes, checked = "true", unchecked = "false"
- Test visibility conditions thoroughly before deployment

---

## Project Structure

### Frontend Directory Layout

```
legalconsenthub/
├── app/
│   ├── app.config.ts                    # App-level configuration
│   ├── app.vue                          # Root component
│   ├── assets/css/                      # Global styles
│   ├── components/                      # Vue components
│   │   ├── formelements/               # Form input components
│   │   ├── DeleteModal.vue
│   │   ├── FormEngine.vue              # Core form rendering engine
│   │   ├── FormStepperWithNavigation.vue
│   │   ├── FormValidationIndicator.vue
│   │   ├── NotificationsSlideover.vue
│   │   ├── RestoreVersionModal.vue
│   │   ├── ServerConnectionOverlay.vue
│   │   ├── TheComment.vue
│   │   ├── UserMenu.vue
│   │   ├── VersionComparisonModal.vue
│   │   └── VersionHistory.vue
│   ├── composables/                    # Business logic composables
│   │   ├── applicationForm/
│   │   ├── applicationFormTemplate/
│   │   ├── applicationFormVersion/
│   │   ├── comment/
│   │   ├── notification/
│   │   ├── complianceMap.ts
│   │   ├── useApplicationFormNavigation.ts
│   │   ├── useApplicationFormValidator.ts
│   │   ├── useFormElementManagement.ts
│   │   ├── useFormStepper.ts
│   │   ├── usePermissions.ts
│   │   └── useServerHealth.ts
│   ├── layouts/                        # Layout components
│   │   ├── auth.vue
│   │   └── default.vue
│   ├── middleware/                     # Route middleware
│   │   ├── auth.global.ts             # Authentication check
│   │   ├── permissions.global.ts       # Authorization check
│   │   └── refreshToken.global.ts      # Token refresh logic
│   ├── pages/                          # Route pages
│   │   ├── settings.vue               # User settings page (language, theme, appearance)
│   │   ├── administration.vue         # Admin template editor
│   │   ├── application-forms/
│   │   ├── callback.vue               # OAuth callback
│   │   ├── create.vue
│   │   ├── index.vue
│   │   └── login.vue
│   ├── plugins/                        # Nuxt plugins
│   │   ├── error-handler.ts
│   │   └── server-health.client.ts
│   ├── stores/                         # Pinia stores
│   │   ├── useCommentStore.ts
│   │   └── useUserStore.ts
│   └── utils/                          # Utility functions
│       ├── date.ts
│       ├── formDiff.ts
│       └── wrappedFetch.ts
├── server/                             # Nuxt server endpoints
│   ├── api/[...].ts                    # Proxy to backend API
│   └── routes/auth/                    # OAuth routes
├── i18n/locales/                       # Translation files
│   ├── de.json
│   └── en.json
├── nuxt.config.ts                      # Nuxt configuration
├── package.json
└── tsconfig.json
```

### Backend Directory Layout

```
legalconsenthub-backend/
├── src/main/
│   ├── kotlin/com/betriebsratkanzlei/legalconsenthub/
│   │   ├── application_form/
│   │   │   ├── ApplicationForm.kt               # Entity
│   │   │   ├── ApplicationFormController.kt     # REST controller
│   │   │   ├── ApplicationFormFormatService.kt  # PDF/HTML generation
│   │   │   ├── ApplicationFormMapper.kt         # DTO ↔ Entity mapper
│   │   │   ├── ApplicationFormRepository.kt     # JPA repository
│   │   │   ├── ApplicationFormService.kt        # Business logic
│   │   │   └── PagedApplicationFormMapper.kt
│   │   ├── application_form_template/          # Template-specific logic
│   │   ├── application_form_version/           # Version management
│   │   ├── comment/                            # Comment domain
│   │   ├── config/                             # Security, TestContainers
│   │   ├── error/                              # Custom exceptions & handler
│   │   ├── form_element/                       # Form structure entities
│   │   │   ├── FormElement.kt
│   │   │   ├── FormElementSection.kt
│   │   │   ├── FormElementSubSection.kt
│   │   │   ├── FormOption.kt
│   │   │   └── [Mappers for each]
│   │   ├── notification/                       # Notification domain
│   │   ├── security/                           # JWT authentication
│   │   │   ├── CustomJwtAuthentication.kt
│   │   │   ├── CustomJwtAuthenticationConverter.kt
│   │   │   ├── CustomJwtTokenPrincipal.kt
│   │   │   └── JwtUserSyncFilter.kt
│   │   ├── user/                               # User domain
│   │   └── LegalconsenthubApplication.kt       # Spring Boot main
│   ├── resources/
│   │   ├── application.yaml                    # Main config
│   │   ├── application-h2.yaml                 # H2 profile
│   │   ├── application-testcontainers.yaml     # Testcontainers profile
│   │   ├── db/changelog/                       # Liquibase migrations
│   │   └── templates/
│   │       └── application_form_template.html  # Thymeleaf template for PDF/HTML
│   └── test/
├── build.gradle                                # Gradle build config
├── Dockerfile
└── settings.gradle
```

### API Specification

```
api/
├── legalconsenthub.yml                 # Main OpenAPI 3.0.3 spec
└── legalconsenthub-middleware.yml      # Middleware API spec (if exists)
```

---

## Development Patterns & Conventions

### 1. API-First Development with OpenAPI

The project uses **OpenAPI 3.0.3** as the single source of truth:

**Frontend**:
```bash
pnpm run api:generate
# Generates TypeScript fetch clients to .api-client/
```

**Backend**:
```gradle
./gradlew generate_legalconsenthub_server
# Generates Kotlin Spring interfaces to build/generated/server/
```

Controllers implement the generated API interfaces.

### 2. Mapper Pattern (Backend)

All DTO ↔ Entity conversions happen in separate **Mapper classes**:
- `ApplicationFormMapper`
- `FormElementMapper`
- `CommentMapper`
- etc.

**Rule**: Never perform mapping logic inside services or controllers.

### 3. Composables Pattern (Frontend)

Business logic is encapsulated in Vue composables:
- Grouped by domain (e.g., `composables/applicationForm/`)
- Exported through `composables/index.ts`
- Reusable across components

Examples:
- `useApplicationFormNavigation()` - Form navigation logic
- `useApplicationFormValidator()` - Validation rules
- `useFormElementManagement()` - Dynamic form element operations

### 4. Manual Database Migrations

**Important**: Do NOT auto-generate SQL migrations.

Migrations are managed manually using **Liquibase** in `src/main/resources/db/changelog/`.

### 5. Code Quality & Linting

**Frontend**:
- ESLint with @nuxt/eslint
- Prettier for formatting
- TypeScript strict mode

**Backend**:
- ktlint for Kotlin formatting
- Gradle task: `./gradlew ktlintCheck`

### 6. Authentication Flow

1. User clicks login → Redirects to Keycloak
2. Keycloak authenticates → Returns to `/callback`
3. Backend exchanges code for JWT
4. JWT stored in secure cookie (`nuxt-auth-utils`)
5. Frontend middleware (`auth.global.ts`) checks auth on every route
6. Backend validates JWT on every API request

### 7. Error Handling

**Backend**: Custom exception classes with `@RestControllerAdvice` handler
**Frontend**: Global error handler plugin + local try/catch blocks

---

## API Endpoints Overview

### Application Forms
- `GET /application-forms` - List all forms (filtered by organizationId)
- `POST /application-forms` - Create new form
- `GET /application-forms/{id}` - Get form by ID
- `PUT /application-forms/{id}` - Update form
- `DELETE /application-forms/{id}` - Delete form
- `GET /application-forms/{id}/pdf` - Export as PDF
- `GET /application-forms/{id}/html` - Export as HTML
- `POST /application-forms/{id}/submit` - Submit form
- `POST /application-forms/{applicationFormId}/subsections/{subsectionId}/form-elements?position={n}` - Add form element dynamically

### Application Form Templates
- `GET /application-form-templates` - List templates
- `POST /application-form-templates` - Create template
- `GET /application-form-templates/{id}` - Get template
- `PUT /application-form-templates/{id}` - Update template
- `DELETE /application-form-templates/{id}` - Delete template

### Version History
- `GET /application-forms/{id}/versions` - List all versions
- `GET /application-forms/{id}/versions/{versionNumber}` - Get specific version
- `POST /application-forms/{id}/versions/{versionNumber}/restore` - Restore version

### Comments
- `GET /application-forms/{applicationFormId}/comments` - Get comments for form
- `POST /application-forms/{applicationFormId}/form-elements/{formElementId}/comments` - Create comment
- `PUT /comments/{id}` - Update comment
- `DELETE /comments/{id}` - Delete comment

### Notifications
- `GET /notifications?organizationId={id}` - Get notifications (paginated)
- `GET /notifications/unread?organizationId={id}` - Get unread notifications
- `GET /notifications/unread/count?userId={id}&organizationId={id}` - Get unread count (public)
- `POST /notifications` - Create notification
- `PUT /notifications/{id}/mark-read?organizationId={id}` - Mark as read
- `PUT /notifications/mark-all-read?organizationId={id}` - Mark all as read
- `DELETE /notifications/clear-all?organizationId={id}` - Clear all notifications

### Users
- `GET /users/{id}` - Get user by ID
- `DELETE /users/{id}` - Delete user

### Roles
- `GET /roles` - List all roles
- `POST /roles` - Create role
- `GET /roles/{id}` - Get role
- `DELETE /roles/{id}` - Delete role

---

## Configuration

### Frontend Environment Variables

Set in `nuxt.config.ts` → `runtimeConfig.public`:

- `clientProxyBasePath` - Frontend proxy path to backend
- `serverApiBaseUrl` - Direct backend URL (server-side)
- `serverApiBasePath` - Backend API base path
- `keycloakTokenUrl` - Keycloak token endpoint

OAuth configuration (`runtimeConfig.oauth.keycloak`):
- `clientId`, `clientSecret`, `realm`, `serverUrl`, `redirectURL`
- Scopes: `openid`, `organization`

### Backend Configuration

Main config in `src/main/resources/application.yaml`:

- Spring profiles: `h2`, `testcontainers`
- Database connection (PostgreSQL)
- Keycloak JWT validation
- Server port (default: 8080)

---

## Running the Application

### Development Setup

**Prerequisites**:
- Node.js 22.16.0 (managed via Volta)
- pnpm 10.11.0+
- Java 21
- PostgreSQL (or use Docker)
- act (for running CI/CD workflows locally)

**Frontend**:
```bash
cd legalconsenthub
pnpm install
pnpm run dev  # Runs on port 3001
```

**Backend**:
```bash
cd legalconsenthub-backend
./gradlew bootRun  # Runs on port 8080
```

### Docker Deployment

**Development**:
```bash
docker-compose -f deployment/docker-compose-dev.yaml up
```

**Production**:
```bash
docker-compose -f deployment/docker-compose-prod.yaml up
```

### CI/CD with Act

Workflows are executed locally using nektos/act:

```bash
# List workflows
act -l

# Run specific jobs
act -j frontend
act -j backend

# Run all jobs
act push

# Run with secrets (for Docker push/deploy)
act push --secret-file .secrets

# Dry run
act -n
```

---

## Testing

### Frontend
- Type checking: `pnpm run type-check`
- Linting: `pnpm run lint`

### Backend
- Run tests: `./gradlew test`
- Uses Testcontainers for integration tests

---

## Important Notes for AI Assistants

1. **Never auto-generate SQL migrations** - Always prompt the developer to create them manually
2. **Use mapper classes** for all DTO/Entity conversions in backend
3. **Prefer existing types** - Don't create duplicate type definitions
4. **No redundant comments** - Don't add comments about what changed or redundant explanations
5. **Organization context** - Always consider organizationId for data isolation
6. **Form structure is three-level** - Section → SubSection → Element (not two-level)
7. **API generation is automatic** - After modifying OpenAPI spec, run generation commands
8. **Roles are managed in Keycloak** - Not in the application database

---

## Additional Resources

- OpenAPI Specification: `api/legalconsenthub.yml`
- Thymeleaf Template: `legalconsenthub-backend/src/main/resources/templates/application_form_template.html`
- CI/CD Pipeline: `.github/workflows/pipeline.yaml`
- Act Configuration: `.actrc` and `.secrets.example`
- Database Management Script: `manage-db.sh`
- Test Data: `testdata.json`
- IT System Config: `it-system.json`