Backend Code Rules

Migrations: db-migration skill.

Commands

Run backend verification from the repo root:

CURSOR_DEV=true nix develop -c pnpm backend:verify

When no database migration is involved, this is faster:

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:

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:

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

Prefer:

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

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