backend-code git:20260928.32163aeA

Immutable. This exact content never changes and is served at /api/v1/blob/73521e36adf6dd55.

---
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
```

## HTTP Sessions

- HTTP sessions are stored in MySQL (Spring Session JDBC) and must stay serializable: they hold only the signed-in security context (and, in production, the OAuth2 authorization request). Do not add `@SessionScope` beans or session attributes; controllers are singletons, and per-request state uses `@RequestScope`.
- Non-prod Basic sign-in keeps its user in the session, like production's GitHub login; there is no remember-me cookie.

## 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 = ...;
```