Refactor models

AGENTS.md

@@ -0,0 +1,36 @@
+# 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/`.
+
+## Build, Test, and Development Commands
+- `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.
+
+## Coding Style & Naming Conventions
+- 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.
+
+## Testing Guidelines
+- 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.
+
+## Commit & Pull Request Guidelines
+- 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.
+
+## Security & Configuration Tips
+- 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.