Repository Guidelines

Project Structure & Module Organization

Java Spring Boot service under src/main/java (controllers, services, repositories, models); configuration in src/main/resources.
Frontend overlays and admin UI assets live in src/main/resources/static/js and src/main/resources/templates (Thymeleaf).
Tests are in src/test/java; sample assets and previews are stored under assets/ and previews/ when running locally.
Marketplace seed content (if used) sits at the path pointed to IMGFLOAT_MARKETPLACE_SCRIPTS_PATH, each with metadata.json, source.js, optional logo.png, and attachments/.

make build / mvn compile: compile the application.
make run: load .env (if present) and start the Spring Boot app on port 8080 with required env vars.
make watch: recompile on source changes (needs entr); restart browser manually.
make test / mvn test: run the full test suite.
make package: clean build a runnable JAR.

Java 17, Spring Boot 3.x. Follow standard Java conventions: 4-space indentation, UpperCamelCase for types, lowerCamelCase for methods/fields, constants in UPPER_SNAKE_CASE.
Keep controllers thin, delegate logic to services, and favor immutable DTOs/records where possible.
Place web assets next to related features (static/js modules, matching templates). Use descriptive filenames (e.g., broadcast/renderer.js).
Prefer constructor injection for Spring components; avoid field injection.

Use JUnit 5 with Mockito for unit tests; keep tests under src/test/java mirroring package paths.
Name tests descriptively (ClassNameTest, method names expressing behavior).
For changes touching overlays or asset handling, add tests for repository/service logic and handle edge cases (missing files, bad metadata).
Run make test before opening a PR; add targeted integration tests when altering controllers or WebSocket flows.

Commits: concise, present-tense summaries (Fix script import domain validation). Group related changes; avoid noisy churn.
PRs: include a clear summary, linked issue (if any), test results, and screenshots/GIFs when UI changes affect admin or broadcast overlays.
Call out any config/env changes (new required vars such as IMGFLOAT_*) and migration steps.

Store secrets via environment variables (.env only for local dev). Required paths: IMGFLOAT_ASSETS_PATH, IMGFLOAT_PREVIEWS_PATH, IMGFLOAT_DB_PATH, IMGFLOAT_AUDIT_DB_PATH.
When seeding marketplace scripts, ensure metadata.json is well-formed; attachment filenames must be unique per script.
Keep OAuth keys and token encryption keys (IMGFLOAT_TOKEN_ENCRYPTION_KEY) in a secret manager for non-local environments.