misc: Add documentation, clean up manage-db.sh
This commit is contained in:
538
CLAUDE.md
Normal file
538
CLAUDE.md
Normal file
@@ -0,0 +1,538 @@
|
||||
# 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**: Gitea workflows (`.gitea/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)
|
||||
├── type (SELECT, CHECKBOX, RADIOBUTTON, TEXTFIELD, SWITCH, TITLE_BODY_TEXTFIELDS)
|
||||
├── title, description
|
||||
└── options (FormOption[])
|
||||
├── value, label
|
||||
├── processingPurpose
|
||||
└── employeeDataCategory
|
||||
```
|
||||
|
||||
**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.
|
||||
|
||||
---
|
||||
|
||||
## 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
|
||||
│ │ ├── 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)
|
||||
|
||||
**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
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 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: `.gitea/workflows/pipeline.yaml`
|
||||
- Database Management Script: `manage-db.sh`
|
||||
- Test Data: `testdata.json`
|
||||
- IT System Config: `it-system.json`
|
||||
Reference in New Issue
Block a user