gremiumhub/CLAUDE.md at 9dc690715b4c6cd980b060b48f8d7b9dde280027

Files

Denis Lugowski 9dc690715b feat(#13 ): Show form elements depending on other form element values

2025-11-30 18:13:14 +01:00

23 KiB

Raw Blame History

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:

Frontend (legalconsenthub/): Nuxt 4 SSR application
Backend (legalconsenthub-backend/): Spring Boot 3 REST API with Kotlin
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:

User-specific: Directed to a single user by recipientId
Role-based: Sent to all users with specific roles (targetRoles[])
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

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:

{
  "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:

pnpm run api:generate
# Generates TypeScript fetch clients to .api-client/

Backend:

./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

User clicks login → Redirects to Keycloak
Keycloak authenticates → Returns to /callback
Backend exchanges code for JWT
JWT stored in secure cookie (nuxt-auth-utils)
Frontend middleware (auth.global.ts) checks auth on every route
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:

cd legalconsenthub
pnpm install
pnpm run dev  # Runs on port 3001

Backend:

cd legalconsenthub-backend
./gradlew bootRun  # Runs on port 8080

Docker Deployment

Development:

docker-compose -f deployment/docker-compose-dev.yaml up

Production:

docker-compose -f deployment/docker-compose-prod.yaml up

CI/CD with Act

Workflows are executed locally using nektos/act:

# 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

Never auto-generate SQL migrations - Always prompt the developer to create them manually
Use mapper classes for all DTO/Entity conversions in backend
Prefer existing types - Don't create duplicate type definitions
No redundant comments - Don't add comments about what changed or redundant explanations
Organization context - Always consider organizationId for data isolation
Form structure is three-level - Section → SubSection → Element (not two-level)
API generation is automatic - After modifying OpenAPI spec, run generation commands
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

23 KiB Raw Blame History

Legal Consent Hub - Project Documentation

Project Overview

Key Features

Architecture

System Components

Technology Stack

Frontend

Backend

Infrastructure

Core Domain Concepts

1. Organizations & Multi-tenancy

2. Application Forms

3. Dynamic Form Structure

4. Version History & Snapshots

5. PDF & HTML Generation

6. Comments System

7. Notifications

8. GDPR Compliance Features

9. Role-Based Access Control

10. Conditional Form Element Visibility

Project Structure

Frontend Directory Layout

Backend Directory Layout

API Specification

Development Patterns & Conventions

1. API-First Development with OpenAPI

2. Mapper Pattern (Backend)

3. Composables Pattern (Frontend)

4. Manual Database Migrations

5. Code Quality & Linting

6. Authentication Flow

7. Error Handling

API Endpoints Overview

Application Forms

Application Form Templates

Version History

Comments

Notifications

Users

Roles

Configuration

Frontend Environment Variables

Backend Configuration

Running the Application

Development Setup

Docker Deployment

CI/CD with Act

Testing

Frontend

Backend

Important Notes for AI Assistants

Additional Resources

23 KiB

Raw Blame History