Skip to content

DEVELOPMENT.md

Latest commit

 

History

History
138 lines (103 loc) · 4.49 KB

DEVELOPMENT.md

File metadata and controls

138 lines (103 loc) · 4.49 KB

Grimmory API Development

This document is the canonical development guide for the Grimmory backend. It covers the local command surface, setup expectations, build and test workflows, and backend-specific conventions.

For repository-wide contribution policy, branch strategy, PR requirements, and release semantics, start with ../CONTRIBUTING.md. For repo-level environment setup and Docker workflows, see ../DEVELOPMENT.md.

Project Scope

The backend project is the Spring Boot backend for Grimmory. It owns the HTTP API, database migrations, background processing, authentication, and the packaged runtime jar used by the production container.

Stack

  • Java 25
  • Spring Boot 4
  • Gradle Wrapper
  • Spring Data JPA + Flyway
  • MariaDB in production, H2 for selected tests
  • JUnit 5, Mockito, AssertJ, JaCoCo

Preferred Command Surface

Use Justfile when possible:

just                 # List backend recipes
just run             # Start the backend with the dev profile
just test            # Run backend tests
just coverage        # Generate JaCoCo coverage output
just check           # Run the Gradle check lifecycle
just build           # Build the backend jar
just tasks           # Show available Gradle tasks

From the repository root, the same recipes are available through the api namespace:

just api run
just api test
just api coverage
just api check

Running Locally

The backend expects a MariaDB instance plus environment or local configuration for your database and storage paths. The common backend loop is:

cd backend
just run

If you need a different Spring profile:

just run profile=local

Use the repo-level guide in ../DEVELOPMENT.md for the full Docker stack, MariaDB setup, and cross-project local workflows.

Build and Test

just build
just test
just coverage
just check

The frontend bundle is consumed during packaging when the UI build output exists. For normal backend-only development and test runs, frontend resources are optional.

API Docs (API_DOCS_ENABLED)

  • application.yaml binds app.api-docs.enabled to API_DOCS_ENABLED (default false).
  • application.yaml binds springdoc.api-docs.enabled to app.api-docs.enabled.
  • For runtime or container profiles, set API_DOCS_ENABLED=true to expose:
    • /api/openapi.json
    • /api/docs
  • To export a release-ready spec without running the full container stack, use:
just openapi-export

Packaging Notes

  • The production container image is built from the repository root Dockerfile.
  • That Docker build compiles the UI first and passes the resolved frontend dist path into the backend build.
  • The backend jar remains the packaged application artifact for the current all-in-one runtime model.

Backend Conventions

  • Use Spring Data JPA repository methods or JPQL. Do not introduce native queries unless a maintainer has explicitly approved them.
  • Prefer constructor injection via Lombok @AllArgsConstructor. Do not add @Autowired.
  • Use Lombok @Slf4j for logging. Do not instantiate loggers manually.
  • Throw API-facing errors via ApiError helpers instead of raw RuntimeException.
  • Entities use the *Entity suffix. DTOs and API models do not.
  • Use MapStruct for entity-to-DTO mapping instead of hand-written mapping code.
  • Security checks should use the existing project patterns such as @PreAuthorize("@securityUtil.isAdmin()") or @CheckBookAccess.
  • Use modern Java language features where they clarify the code.
  • Keep imports explicit. Do not inline fully-qualified class names.

Migrations

  • Flyway migrations live in src/main/resources/db/migration/.
  • Name migrations V<number>__<Description>.sql.
  • Never modify a released migration. Add a new migration instead.
  • Prefer idempotent guards such as IF EXISTS and IF NOT EXISTS when the SQL dialect allows them.

Testing

  • Unit tests should normally use JUnit 6 + Mockito + AssertJ.
  • Use @ExtendWith(MockitoExtension.class) for unit tests.
  • Use @SpringBootTest only when you need a real Spring integration context.
  • Keep tests behavior-oriented. Avoid shallow tests that only exercise getters, setters, or mocks without asserting meaningful outcomes.

Validation Before Opening a PR

Run the backend checks locally before sending a PR:

just test
just check

If your change affects migrations, persistence, or API behavior, also run the full stack locally and verify the behavior manually.