---
description: StoryTeller project context, architecture, and coding standards (Java/Quarkus, Maven, frontend)
alwaysApply: true
---

# StoryTeller – Project Instructions

## Project context

- **Project**: StoryTeller
- **Java**: 21
- **Build**: Maven
- **Framework**: Quarkus (latest stable)
- **GroupId**: de.neitzel | **ArtifactId**: storyteller
- **Base package**: `de.neitzel.storyteller`
- **Sub-packages**: `business`, `common`, `data`, `fascade`
- Startup code lives in the base package.
- **DB migrations**: Liquibase; scripts in `src/main/resources/db/migration`.

## Architecture and package rules

- **Startup/bootstrap**: `de.neitzel.storyteller`
- **Business logic**: `de.neitzel.storyteller.business`
- **Shared utilities, cross-cutting types**: `de.neitzel.storyteller.common`
- **Persistence / data access**: `de.neitzel.storyteller.data`
- **External-facing facades (REST, API)**: `de.neitzel.storyteller.fascade`
- Keep clear package boundaries; avoid circular dependencies.

## Coding standards (Java)

- Use Lombok to reduce boilerplate where it helps.
- Prefer immutability: `final` fields, constructor injection.
- Use Quarkus idioms; avoid heavyweight frameworks.
- Keep methods small and focused; one responsibility per class.
- Use Java 21 features when they improve clarity.
- Add concise comments only for non-obvious logic.
- All classes, fields, and methods (including private) must have JavaDoc describing purpose and usage.

## Testing

- Add or update unit tests for new or changed logic.
- Use JUnit 5 and Mockito; Arrange–Act–Assert; keep tests deterministic.
- Mock external dependencies; add integration tests only when requested.

## Maven and dependencies

- Target Java 21 in the Maven toolchain.
- Use the latest stable Quarkus platform BOM.
- Keep dependencies minimal; no new libraries without need.
- Keep versions up to date (especially for security).
- Put plugin and dependency versions in the `properties` section of `pom.xml`.
- Use `quarkus-maven-plugin` for build/run; `maven-surefire-plugin` for tests (JUnit 5); `maven-compiler-plugin` with Java 21.

## Frontend (React / Vite)

- Frontend lives under `src/main/web` (React, TypeScript, Vite, MUI).
- OpenAPI TypeScript client is generated into `src/main/web/src/api/generated/` by Maven (`mvn generate-sources`); do not edit by hand.
- Production build output: `target/web-dist`; copied to `META-INF/resources` by `maven-resources-plugin` for the Quarkus SPA.

## Do and don’t

- **Do**: keep code in the correct package; add tests for business logic.
- **Don’t**: put startup code outside the base package; add unnecessary abstraction layers.

## Output expectations

- Provide complete, compilable code with package declarations and imports.
- Prefer Quarkus-friendly APIs and annotations.
- When adding or changing logic, update or add unit tests.