mirror of
https://github.com/imgfloat/server.git
synced 2026-02-05 03:39:26 +00:00
37 lines
2.8 KiB
Markdown
37 lines
2.8 KiB
Markdown
# 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.
|