German Text for Support & Care Landingpage

.claude/conventions/backend.md

@@ -0,0 +1,54 @@
+# Backend Conventions for Claude Code
+
+## Overview
+
+Our backends are written in Java. This document covers conventions specific to backend applications. For general Java conventions, see [java.md](java.md).
+
+## Frameworks
+
+We use two frameworks for building backend applications:
+
+- **[Spring Boot](https://spring.io/projects/spring-boot)** — The full-featured option. Use Spring Boot when the application needs a broad ecosystem (security, data access, messaging, etc.) and development speed matters more than minimal footprint.
+- **[Helidon SE](https://helidon.io/)** — The lightweight option. Use Helidon SE for performant, lean backends where a small footprint and low startup time are important.
+
+Both are valid choices depending on the project requirements. We aim to provide Open Elements base libraries (as dependencies) for both frameworks in the future.
+
+### Libraries for Backend Frameworks
+
+When building libraries that target backend applications, provide support for Spring Boot and Helidon SE as primary targets. Additionally, offer support for [Eclipse MicroProfile](https://microprofile.io/) and [Eclipse Jakarta EE](https://jakarta.ee/) where feasible, to broaden compatibility. For concrete backend applications, we typically do not use MicroProfile or Jakarta EE directly.
+
+## REST APIs and OpenAPI
+
+- Every backend that exposes REST endpoints must include a Swagger UI for interactive API exploration.
+- Use [SpringDoc OpenAPI](https://springdoc.org/) (for Spring Boot) or an equivalent library to generate the OpenAPI specification automatically from code.
+- Document every endpoint completely with OpenAPI annotations: summary, description, request/response schemas, status codes, and error responses.
+- Use meaningful operation IDs and group endpoints with tags.
+- Configure authentication information in the OpenAPI specification so that users can authorize directly in the Swagger UI to test protected endpoints. Include the supported security schemes (e.g., Bearer token, OAuth2) and their configuration.
+- Ensure the OpenAPI spec stays in sync with the actual implementation — generate it from code rather than maintaining a separate spec file.
+- **IMPORTANT**: Never expose JPA entities directly in REST endpoints (neither as request nor as response objects). Always use dedicated **DTOs** (Data Transfer Objects) for the API layer. Map between entities and DTOs explicitly in the service or controller layer. This avoids leaking internal data model details, prevents lazy-loading and serialization issues, and decouples the API contract from the database schema.
+
+## Data Access and Database
+
+- **IMPORTANT**: Use **JPA** (Jakarta Persistence API) for data access. Do not use implementation-specific APIs (e.g., Hibernate session or criteria API directly) — always program against the JPA interfaces.
+- Use **[Flyway](https://flywaydb.org/)** for database schema management and migrations in all projects with a database.
+- **PostgreSQL** is the preferred database for test environments and production.
+- **H2** (in-memory) is the preferred database for fast, automated unit/integration tests. In the future, we plan to replace H2 with [Testcontainers](https://www.testcontainers.org/)-based PostgreSQL to test against the same database in all environments.
+- **IMPORTANT**: Database connection URLs, credentials, and other settings must be configurable via environment variables (see [fullstack-architecture.md](fullstack-architecture.md#configuration)).
+
+## Data Privacy and GDPR
+
+- **IMPORTANT**: All backend applications must be designed with GDPR (DSGVO) compliance in mind.
+- Collect only personal data that is strictly necessary for the application's purpose (data minimization).
+- Every piece of personal data must have a clear, documented legal basis for processing (e.g., consent, contract fulfillment, legitimate interest).
+- Provide API endpoints for data subject rights: access (Art. 15), rectification (Art. 16), erasure (Art. 17), and data portability (Art. 20) where applicable.
+- Personal data must be deletable — design database schemas so that user data can be fully removed without breaking referential integrity.
+- Log access to personal data for audit purposes, but do not log the personal data itself.
+- Do not store personal data in log files, error messages, or stack traces.
+- Use encryption at rest and in transit for personal data.
+- When integrating third-party services, verify that they are GDPR-compliant and document data processing agreements.
+
+## Observability
+
+- Every backend should expose **metrics** in Prometheus format for monitoring and alerting.
+- Every backend should stream **logs** to Loki for centralized log aggregation and querying.
+- Concrete implementation details for Spring Boot and Helidon SE are still being defined.

.claude/conventions/documentation.md

@@ -0,0 +1,75 @@
+# Project Documentation Conventions for Claude Code
+
+## Overview
+
+We use [MkDocs](https://www.mkdocs.org/) with the [Material for MkDocs](https://squidfunnel.github.io/mkdocs-material/) theme to create and host technical documentation for projects. Documentation is stored in the repository alongside the code and published as GitHub Pages.
+
+A reference implementation is the [maven-initializer docs](https://github.com/support-and-care/maven-initializer/tree/main/docs).
+
+## Repository Structure
+
+```
+project-root/
+├── docs/
+│   ├── index.md              # Landing page
+│   ├── architecture.md       # Architecture overview
+│   ├── contributing.md       # How to contribute to the docs
+│   └── stylesheets/          # Custom CSS (optional)
+└── mkdocs.yml                # MkDocs configuration at repository root
+```
+
+## MkDocs Configuration
+
+The `mkdocs.yml` lives at the repository root and configures:
+
+- **Theme**: Material for MkDocs with light/dark mode toggle.
+- **Navigation**: Explicit `nav` section defining the page hierarchy.
+- **Extensions**: Markdown extensions for features like Mermaid diagrams (`pymdownx.superfences`).
+- **Plugins**: At minimum the `search` plugin.
+
+## Markdown
+
+- Use GitHub Flavored Markdown (GFM) as the default syntax for all documentation — `README.md`, docs, ADRs, and any other prose in the repository.
+
+## Content Guidelines
+
+- Write documentation in plain Markdown inside the `docs/` folder.
+- The `index.md` serves as the landing page with links to the main sections.
+- Keep documentation close to the code — update docs when the related code changes.
+- Use Mermaid diagrams for architecture and flow visualizations instead of external image files where possible.
+
+## Local Development
+
+To preview documentation locally:
+
+```bash
+pip install mkdocs-material "pymdown-extensions"
+mkdocs serve
+```
+
+The site is then available at `http://127.0.0.1:8000`.
+
+## GitHub Pages Deployment
+
+Documentation is deployed automatically via a GitHub Actions workflow (`.github/workflows/docs.yml`):
+
+- **Pushes to main**: Deploy to the production site root using `mkdocs gh-deploy --force`.
+- **Pull requests**: Build a preview and deploy it to a `/pr/<number>/` subdirectory. The workflow comments on the PR with a link to the preview.
+
+### Requirements
+
+- GitHub Pages must be enabled on the repository with the source set to the `gh-pages` branch.
+- The workflow needs `contents: write` and `pull-requests: write` permissions.
+
+## What to Document
+
+- Architecture overview (components, their responsibilities, how they interact).
+- Architecture Decision Records for significant technical choices.
+- Setup and contribution instructions.
+- API documentation if the project exposes a public API.
+
+## What NOT to Document in MkDocs
+
+- User-facing README content — that stays in `README.md` at the repository root.
+- Auto-generated API docs (Javadoc, TypeDoc) — those have their own tooling.
+- Temporary notes or work-in-progress — use issues or discussions instead.

.claude/conventions/editorconfig.md

@@ -0,0 +1,67 @@
+# EditorConfig Conventions for Claude Code
+
+## Overview
+
+Every repository should include a `.editorconfig` file at the root to enforce consistent formatting across all editors and IDEs. EditorConfig is supported natively by IntelliJ IDEA, VS Code, and most other editors.
+
+See [editorconfig.org](https://editorconfig.org/) for the specification.
+
+## Standard `.editorconfig`
+
+The following configuration is the Open Elements standard. It is based on conventions from Google, JetBrains, Angular, and the broader Java/TypeScript community.
+
+```ini
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+indent_style = space
+indent_size = 4
+trim_trailing_whitespace = true
+insert_final_newline = true
+
+[*.java]
+max_line_length = 120
+ij_java_class_count_to_use_import_on_demand = 9999
+ij_java_names_count_to_use_import_on_demand = 9999
+ij_java_use_single_class_imports = true
+ij_java_layout_static_imports_separately = true
+ij_java_block_brace_style = end_of_line
+ij_java_class_brace_style = end_of_line
+ij_java_method_brace_style = end_of_line
+ij_java_lambda_brace_style = end_of_line
+ij_java_if_brace_force = always
+ij_java_for_brace_force = always
+ij_java_while_brace_force = always
+ij_java_do_while_brace_force = always
+
+[*.{ts,tsx,js,jsx,json,css,scss,html}]
+indent_size = 2
+
+[*.{yml,yaml}]
+indent_size = 2
+
+[*.md]
+trim_trailing_whitespace = false
+
+[*.xml]
+indent_size = 4
+
+[{Dockerfile,Dockerfile.*}]
+indent_style = space
+indent_size = 4
+```
+
+## Key Decisions
+
+- **4 spaces for Java and XML** — industry standard for Maven-based projects.
+- **2 spaces for TypeScript/JavaScript, YAML, and JSON** — matches the React/Next.js/Angular ecosystem.
+- **LF line endings** — consistent across macOS, Linux, and CI environments.
+- **No wildcard imports in Java** — enforced via IntelliJ `ij_java_` properties (threshold set to 9999).
+- **Braces always required** for `if`, `for`, `while`, `do-while` in Java — prevents single-line body bugs.
+- **Markdown exempt from trailing whitespace trimming** — trailing spaces are significant in Markdown (line breaks).
+
+## Usage
+
+Copy the `.editorconfig` content above into the root of your repository. It will be picked up automatically by supported editors.