pholio/AGENTS.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. I'm a technical architect, java, spring boot and JavaFX expert.

This project is a desktop application for images / pictures management. Like collections of images. performance is key (volume and speed analysis)

Technical overview

• Use java 26 (and javafx), spring-boot, picocli, h2, jackson
• use only maven as build tool.
• For packaging, use spring boot generated jar, and jdeploy to create OS package (jdk/jre included)
• Use lombok when applicable (Constructor and getter / setter)
• Never use Lombok builder. use Jilt builder.

Agent guidelines

• Plans generated with Claude must be saved into directory: ".claude/plans".
• "Do not use the AskUserQuestion tool. If you need more information or need me to make a choice, output your questions as plain text in your final response instead."
• Always answer in French, never switch to another language

Packaging & distribution (jDeploy)

Native installers with a bundled JRE are produced by jDeploy, driven from two files: package.json at the repository root (the descriptor) and .github/workflows/jdeploy.yml (the release pipeline).

• Entry point. jDeploy has no main-class setting — it runs the jar. So the entry point is declared once, as spring-boot-maven-plugin's <mainClass>${main.class}</mainClass>, which lands in the repackaged jar's manifest as Start-Class. jdeploy.jar in package.json points at target/pholio.jar; <finalName> is version-free precisely so that path never needs updating.
• Runtime. jdeploy.javaVersion: "26" with jdeploy.javafx: true provisions an Azul Zulu FX JRE per platform. windows-arm64 is deliberately absent from downloadPage.platforms: Azul publishes no FX build for it at 26, so listing it would produce an installer that cannot start.
• Syncing the descriptor. mvn -Pjdeploy package runs jdeploy-maven-plugin:sync-package-json, which copies version, name, description, title, jar path, Java version and the JavaFX flag from the POM into package.json. It works by shelling out to npm pkg set, which is why it sits behind a profile — a plain mvn package must not require Node. Every other key in package.json is hand-maintained.
• Icon. jDeploy takes the app icon from icon.png next to package.json, one file for every platform (it builds the macOS .icns itself). It is the macOS-grid version — an 832 px rounded square centred on a 1024 px transparent canvas — generated with src/main/resources/images/spo-macos-1024x1024.png and src/main/packaging/macos/pholio.icns by python3 tools/icons/make-macos-icon.py; edit the script, not the images.
• Releasing. ./mvnw -Prelease validate (profile release in pom.xml, steps in tools/release/Release.java): bumps the version to YYYY.M.N (year and month without leading zero; N restarts at 0 each month), runs a fresh ./mvnw verify, writes distrib/release_note/release-note-<version>.md (Conventional Commits since the previous v<version> tag — last 30 commits for the first release — grouped by type then scope, duplicate first lines merged), creates GitHub release v<version> in Imag-In/Pholio described by that note, with pholio-<version>.jar, its .sha256 and the note as assets (via gh), commits pom.xml and tags v<version> locally, then commits and pushes the note from distrib/. Needs a clean working tree (or -Drelease.allowDirty=true) and a logged-in gh. Only Conventional Commit subjects reach the note, so keep commit messages in that format.
• Source never goes to GitHub. Imag-In/Pholio is public and only holds release assets plus the distrib/ worktree: an orphan distrib branch pushed to its main through the github remote. A local pre-push hook (.git/hooks/pre-push, not versioned) refuses any other branch, and any commit sharing history with main, towards GitHub.
• Auto-update. Handled entirely by the native launcher: it reads a package-info.json that the action writes to a jdeploy tag in this repository, and picks up a newer release on next start. This requires the repository to stay public; a private one needs a separate public release repository passed to the action as target_repository.
• Do not add documentTypes, urlSchemes or singleton without changing the launcher first. jDeploy passes opened files and URIs to main, and LaunchOptions reads any unrecognised argument as a subcommand and switches to HEADLESS. File associations would therefore make a double-clicked photo start Pholio with no window.

Code guidelines

• All interfaces classes must starte with a upper 'i'. ex: 'IFactory'.
• All enum classes must start with a upper 'e'. ex: 'ENodeType'.

Javafx guidelines

• When need to add an empty control that grow horizontally or vertically, you can use AtlantaFx spacer: 'atlantafx.base.controls.Spacer'
• For icons use Ikonli and use in priority pack: "MaterialDesign2"
• Reuse existing control from javafx and third-party libraries: AtlantaFx anf GemFx

Preferences vc H2 DB (library)

• Preferences stored as yaml must contain only user preferences for the global application (not related to a library)
• All library information like: folders, metadata, latest importations, media hash, etc must be stores into H2 DB

Spring data jpa jdbc

• use mapstruct for mapping entities to domain and vis versa.

Testing

• for unit test use AssertJ with SoftAssertion

Git & Commit Guidelines

• Use the Conventional Commits v1.0.0 specification for all commit messages.
• Always structure messages as: <type>([optional scope]): <description>
• Use lowercase for the type and scope.
• Write the description in the imperative mood (e.g., "add feature", not "added feature").
• Allowed types:
  • feat: A new feature
  • fix: A bug fix
  • docs: Documentation changes
  • style: Code style changes (formatting, missing semi-colons, etc.)
  • refactor: Code changes that neither fix a bug nor add a feature
  • test: Adding missing tests or correcting existing tests
  • chore: Changes to the build process or auxiliary tools
• Example: feat(auth): add JWT token validation