Proposal: staged Grimmory plugin system

[dawidgora]

What would you like Grimmory to do?

I would like to propose a staged plugin system for Grimmory.

The goal is to give Grimmory core features and future external plugins the same
small extension API. External plugin loading would follow only after the core
contracts and operational constraints are agreed.

Phase 0: PoC complete

I built and manually tested a narrow proof of concept:

dawidgora#2

It validates:

• Spring-managed extensions can contribute book actions.
• Extensions can receive a post-commit BookImported event.
• The backend exposes actions through generic endpoints.
• Angular renders available actions generically in Book details > Actions.
• Execution routes back to the contributing extension.

The demo FormatConverterExtension contributes "Generate missing formats" and
logs import/action execution. It intentionally does not modify files or perform
real conversion.

Phase 1: internal extension API

If the direction is accepted, I propose stabilizing the internal API first:

• Clear action and event contracts.
• Generic action IDs, availability, ordering, results, and error behavior.
• Authorization rules.
• Test coverage.
• Adoption by one or two real Grimmory core features.

Extensions would still be normal built-in Spring beans at this stage.

Phase 2: full plugin system

Only after Phase 1 is validated in core, design and implement support for
administrator-installed external plugins. This phase would need explicit
agreement on:

• Plugin descriptors, IDs, versions, and API compatibility.
• Classloading and dependency isolation.
• Startup, lifecycle, and failure behavior.
• Enablement and diagnostics.
• Security and trust model.
• Upgrade and uninstall policy.

Dynamic frontend bundles, plugin marketplaces, and hot reload are not assumed
requirements for the first external-plugin release.

I am open to discussing the scope and implementation details, and I am willing
to help implement the agreed stages.
Potential capabilities such as format conversion, import automation, metadata
integrations, and device-specific workflows otherwise need one-off changes
across Grimmory's backend, API, and UI.

A shared extension API would provide reusable integration seams and let core
features and future plugins follow the same model. The staged approach reduces
risk. It proves the architecture internally before committing to classloaders,
plugin lifecycle, or third-party compatibility.
Manual PoC verification succeeded:

• The action appeared generically in Book details > Actions.
• Clicking it reached the extension and displayed its returned result.
• A post-import event hook is also included.

I will attach a screenshot of the successful action result.

I would appreciate feedback on:

1. Whether a staged plugin-system direction fits Grimmory.
2. Which real core feature would be the best first adopter of the internal API.
3. Existing architecture or roadmap constraints this should align with.
4. The preferred future trust and lifecycle model for administrator-installed
   plugins.

What problem does this solve for you?

I want Grimmory to support integrations and workflows that do not belong in the
core application by default, such as format conversion, import automation,
metadata integrations, and device-specific features.

Without extension points, each feature needs one-off backend, API, and UI
changes. A plugin system would give core features and future plugins a shared,
consistent integration model.

Anything else?

PoC PR:

dawidgora#2

Manual verification succeeded:

• The action appeared in Book details > Actions.
• Clicking it reached the demo extension and displayed its result.
• The action does not modify files.
• The PoC also includes a post-import event hook.

Want to help out?

Yes! I'd love to help implement this

Before submitting

• I've searched existing discussions and this hasn't been suggested yet
• I've reviewed this report and have completed it as fully as I can

[imnotjames]

The gist of your actual proposal here is "we should emit events on book import (which we already do) and have listeners for that event.

• Instead of building our own new listener adapter, why not use the listener tooling directly in this case?
• What happens when you have a "plugin" that runs for 45 minutes in this case?

I really think that the other parts should be described more concretely as this phase 0 is basically "I want this feature" which is a duplicate elsewhere.

[imnotjames]

Whether a staged plugin-system direction fits Grimmory.

Could you define a staged plugin system? How does it differentiate from a regular plugin system

Which real core feature would be the best first adopter of the internal API.

Which do you think?

Existing architecture or roadmap constraints this should align with.

We are reworking many of the internals to support better performance. Aside from that, not really much.

The preferred future trust and lifecycle model for administrator-installed

I don't really understand this question. Could you elaborate what you mean?

[dawidgora]

My submission here was "polished" by AI (English isn’t my native language), and I might not have fully reviewed the final version lol, so some AI slop may have slipped through :) I’ll get back to you ASAP - I just need to wrap up a few other things first.

Thank you for joining the discussion @imnotjames!