backend-code git:20260916.b334104A

Immutable. This exact content is served forever at /api/v1/blob/805fbd5672165151.

---
name: backend-code
description: Backend Java production code, Spring Boot controllers/services/repositories, controller return values, imports, schema ERD pointer. Use when editing backend production Java.
paths:
  - "backend/src/main/**/*.java"
---
# Backend Code Rules

Migrations: `db-migration` skill.

## Commands

Run backend verification from the repo root:

```bash
CURSOR_DEV=true nix develop -c pnpm backend:verify
```

When no database migration is involved, this is faster:

```bash
CURSOR_DEV=true nix develop -c pnpm backend:test_only
```

## Relational Schema

The `docs/database-erd.md` Mermaid diagram documents tables, foreign keys, and key columns. After Flyway migrations change the schema, regenerate it with the `database-erd` skill:

```bash
CURSOR_DEV=true nix develop -c pnpm export:database-erd
```

## Controller Return Values

- Prefer returning entities, or other types already used as API bodies, from controllers when the JSON shape fits.
- Narrow the serialized surface with `@JsonIgnore`, `@JsonView`, and similar mechanisms already used in the codebase.
- Introduce a response DTO only when necessary, such as a different wire shape, aggregating multiple sources, or decoupling from persistence without overloading the entity.

## Import Style

- Always use import statements at the top of files.
- Do not use inline fully qualified class names in code.
- Use fully qualified names only when there is a naming conflict between classes with the same simple name from different packages.

Avoid:

```java
ObjectMapper mapper = new com.odde.donut.configs.ObjectMapperConfig().objectMapper();
List<com.theokanning.openai.completion.chat.ChatMessage> messages = ...;
```

Prefer:

```java
import com.odde.donut.configs.ObjectMapperConfig;
import com.theokanning.openai.completion.chat.ChatMessage;

ObjectMapper mapper = new ObjectMapperConfig().objectMapper();
List<ChatMessage> messages = ...;
```