Remsly/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Boxit (also called "Remsly" in CI) is a box/inventory management app:

• backend/ — Spring Boot 2.6 (Kotlin, Java 17, Jersey + Spring MVC), PostgreSQL via jOOQ, Elasticsearch for search, Keycloak for auth. Runs on port 5050.
• frontend/ — Angular 13 app (port 4200), proxies /api to the backend via proxy-conf.json.
• JooqHelper/ — small Gradle module providing BoxitNamingStrategy used by jOOQ code generation.
• deploy/localDev/boxit/ — docker-compose for local infrastructure (Postgres on 6543, Keycloak on 8081, Apache OIDC proxy, Elasticsearch, Prometheus).
• deploy/prod/ — production docker-compose + Let's Encrypt scripts.
• clients/ — IntelliJ HTTP client files for the REST API, Keycloak, and Elasticsearch (env in http-client.private.env.json, template provided).

Commands

Backend (Gradle, from repo root)

./gradlew build                  # build + tests (requires running Postgres, see below)
./gradlew test                   # tests only (JUnit 5; integration tests use Testcontainers)
./gradlew generateJooq           # run Flyway migrations, then regenerate jOOQ classes
./gradlew lintKotlin             # kotlinter lint
./gradlew formatKotlin           # kotlinter autoformat
./gradlew bootRun                # run the backend

Run a single test class: ./gradlew test --tests "ch.boxi.boxit.SomeTestClass"

DB connection for Flyway/jOOQ codegen is parameterized via Gradle properties -PDB_HOST_PORT -PDB_USER -PDB_PASSWD -PDB_NAME (defaults: localhost:6543, gradle/gradlepw/gradle — matches the localDev docker-compose Postgres).

Frontend (from frontend/)

npm start                        # dev server on :4200 with /api proxy to :5050
npm run build                    # dev build
npm run buildProd                # production build (also copies index.html -> 404.html)
npm test                         # Karma/Jasmine tests
npm run lint                     # ng lint

Local infrastructure

cd deploy/localDev/boxit && docker compose up -d

Provides Postgres (port 6543, multiple DBs: boxit, keycloak, gradle, test), Keycloak (8081), Apache OIDC proxy, and Elasticsearch. backend/src/main/resources/application.properties is not committed — create it from application.properties-Template.

Architecture

Backend data flow: Flyway → jOOQ codegen

The DB schema is the source of truth. Migrations live in backend/src/main/resources/db/migration (Flyway, V*.sql). generateJooq depends on flywayMigrate and generates records/POJOs/DAOs into backend/src/gen/java (package ch.boxi.boxit.gen, deleted on clean, regenerated on compilation). Naming is customized by JooqHelper's BoxitNamingStrategy. After changing a migration, re-run ./gradlew generateJooq against a running Postgres.

Backend layers (ch.boxi.boxit)

• restapi/ — REST controllers, DTOs, mappers, pagination (Paged, PaginationDto, infinite scroll support). Organized by feature (folder, note, task, user, search).
• domain/ — business logic per feature (attachment, folder, location, note, task, user). Uses a Visitor pattern (Visitable/Visitor) and Augmentor abstractions.
• db/ — jOOQ-based repositories built on SimpleCrudRepository / AbstractSimpleCrudRepositoryImpl plus composable JooqFilter classes (CombinedAndFilter, CombinedOrFilter, ...).
• searchindex/ — Elasticsearch index per feature (folder, note, task) with its own migration support; db/elasticsearchSync + domain/elasticSearchSync implement DB→ES synchronization.
• clientapi/ — outbound HTTP clients (e.g. OpenStreetMap geocoding).
• security/ — Keycloak/OIDC config and SSL client config (SSLClientConfig pins outbound HTTPS to TLS 1.2; trust uses the JVM default cacerts — no custom truststore).

Frontend layers (frontend/src/app)

• api/ — boxit.api.ts + DTOs + HTTP error interceptor (mirror of the backend REST API).
• business/ — services/models per feature (item, attachment, location, user), notification and global error handling.
• gui/ — components (header, page, search, filters, item, location, responsive helpers).
• auth/ — auth.service.ts (Keycloak-based login).

Testing

Backend integration tests (BoxitIntegrationTest) use Testcontainers. For container reuse, add testcontainers.reuse.enabled=true to ~/.testcontainers.properties.

CI

Gitea Actions (.gitea/workflows/) builds on push to main: Gradle build with a Postgres service container, then builds/pushes Docker images (*-backend, *-frontend) to gitea.tail276105.ts.net and triggers a prod compose redeploy. bitbucket-pipelines.yml and .space.kts are legacy.