Enhance developer documentation

[Eng-YasminKotb]

Summary

This PR adds a new diagram showing the dependencies between JabRef's components (gui, logic, model, cli), and fixes some typos in the docs.

Steps to test

To test this change, open the developer documentation file where the package structure is explained. You will see a new diagram showing how the components (gui, logic, model, cli) depend on each other. Also check the text some small typos were fixed there too.

Related issues and pull requests

Closes _____

AI usage

Claude (Claude Sonnet 5)

---

Checklist

• I own the copyright of the code submitted and I license it under the MIT license
• If AI tools were used, I disclosed them in the "AI usage" section and reviewed, understood, and take full ownership of all AI-generated code
• I manually tested my changes in running JabRef (always required)
• [/] I added JUnit tests for changes (if applicable)
• I added screenshots in the PR description (if change is visible to the user)
• [/] I added one sentence (max 20 words) to CHANGELOG.md describing the change from the user's point of view (if the change is visible to the user)
• [/] I checked the user documentation for up to dateness and submitted a pull request to our user documentation repository

[qodo-free-for-open-source-projects]

PR Summary by Qodo

Support copy and move modes for cross-library entry drag-and-drop

🐞 Bug fix ✨ Enhancement 📝 Documentation 🕐 20-40 Minutes

AI Description

• Supports copy or move semantics when dragging entries between open libraries.
• Removes source entries only after every moved entry imports successfully.
• Replaces textual architecture dependencies with a diagram and corrects documentation wording.

Diagram

graph TD
  D["Entry drag"] --> F["Frame DnD"] --> L["Library tab"] --> I["Import handler"] --> T[("Target library")]
  F --> X["Transfer info"] --> I
  I -->|"successful move"| S[("Source library")]

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Dedicated cross-library transfer service

• ➕ Centralizes copy, move, duplicate handling, and source-removal semantics.
• ➕ Provides a clearer boundary for transactional behavior, tests, and future undo support.
• ➖ Requires a broader refactor across GUI and import workflows.
• ➖ Must coordinate asynchronous duplicate resolution and linked-file processing.

Recommendation: The current approach is appropriate for a scoped fix because it reuses the existing duplicate-aware import pipeline and delays destructive source removal until all entries succeed. If cross-library transfer behavior grows or undo is implemented, extract this coordination into a dedicated transfer service.

Files changed (7) +58 / -28

Enhancement (3) +42 / -8

LibraryTab.javaPropagate transfer mode and source entries during drops +14/-4

Propagate transfer mode and source entries during drops

• Extends entry-drop handling to receive original entries and the selected transfer mode. It passes complete transfer metadata into the import pipeline and reports copied or moved outcomes accurately.

jabgui/src/main/java/org/jabref/gui/LibraryTab.java

FrameDndHandler.javaHonor copy and move modes between library tabs +20/-3

Honor copy and move modes between library tabs

• Allows entry drops to negotiate both copy and move modes, preserves original entries alongside copies, and maps JavaFX transfer modes to model modes. Group transfers remain explicitly copy-only.

jabgui/src/main/java/org/jabref/gui/frame/FrameDndHandler.java

TransferInformation.javaCarry original source entries in transfer metadata +8/-1

Carry original source entries in transfer metadata

• Adds source entries to transfer metadata so move completion can delete the correct originals. Retains a two-argument constructor for existing clipboard and import callers.

jablib/src/main/java/org/jabref/model/TransferInformation.java

Bug fix (1) +8 / -0

ImportHandler.javaRemove source entries only after successful moves +8/-0

Remove source entries only after successful moves

• Tracks completed imports for move operations and removes the original source entries only when every source entry has imported successfully. Documents the remaining need for undo support.

jabgui/src/main/java/org/jabref/gui/externalfiles/ImportHandler.java

Refactor (1) +1 / -0

TransferMode.javaNormalize transfer mode file formatting +1/-0

Normalize transfer mode file formatting

• Adds a trailing newline without changing transfer mode behavior.

jablib/src/main/java/org/jabref/model/TransferMode.java

Documentation (1) +5 / -20

architecture-and-components.mdVisualize component dependencies and clarify architecture text +5/-20

Visualize component dependencies and clarify architecture text

• Replaces the monospaced dependency listing with a linked component diagram. Corrects package terminology and improves wording around GUI responsibilities and component labels.

docs/architecture-and-components.md

Other (1) +2 / -0

JabRef_en.propertiesAdd copy-result localization messages +2/-0

Add copy-result localization messages

• Adds success and partial-success messages for entries copied between libraries, allowing feedback to distinguish copy operations from moves.

jablib/src/main/resources/l10n/JabRef_en.properties

[qodo-free-for-open-source-projects]

Code Review by Qodo

🐞 Bugs (2) 📘 Rule violations (7) 📜 Skill insights (0)

1. Diagram link targets nonexistent asset 📘 Rule violation ≡ Correctness

Description

The new clickable diagram targets components-dependancy.svg, but the repository asset and local
image source use components-dependencies.svg. The diagram renders locally, but clicking it
navigates to a nonexistent raw-GitHub resource, leaving documentation link checks non-green.

Code

docs/architecture-and-components.md[29]

+[![components dependency](images/components-dependencies.svg)](https://raw.githubusercontent.com/JabRef/jabref/main/docs/images/components-dependancy.svg)

Evidence

Rule 26 requires documentation checks to remain green, but the changed Markdown line uses
images/components-dependencies.svg as the image source while its click target references
docs/images/components-dependancy.svg. The PR branch contains
docs/images/components-dependencies.svg and no asset with the misspelled filename, proving that
the hyperlink is broken even though the embedded diagram renders.

AGENTS.md: Keep the Project Build, Tests, Lint, Formatting, and Documentation Checks Green
docs/architecture-and-components.md[29-29]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The new dependency diagram wraps a valid local image in a raw-GitHub link targeting the nonexistent, misspelled `components-dependancy.svg` asset, causing broken navigation when readers click the image.

## Issue Context
The repository asset and local Markdown image source use the correct filename, `components-dependencies.svg`. Update the clickable hyperlink target to use that exact filename and path so it matches the embedded image and documentation link checks remain green.

## Fix Focus Areas
- docs/architecture-and-components.md[29-29]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

2. Unrelated drag-and-drop feature added 📘 Rule violation ⚙ Maintainability

Description

A PR described as developer-documentation enhancement also changes entry drag-and-drop from
copy-only to copy-or-move and adds source deletion behavior. This substantial, unrequested behavior
change is outside the stated documentation scope and prevents focused review.

Code

jabgui/src/main/java/org/jabref/gui/frame/FrameDndHandler.java[168]

+            tabDragEvent.acceptTransferModes(TransferMode.COPY_OR_MOVE);

Evidence

Rule 1 requires narrowly scoped changes without unrelated behavior. The changed transfer-mode
acceptance activates MOVE in a PR whose title, summary, and testing instructions cover only
developer documentation.

AGENTS.md: Preserve Architecture, Compatibility, and Change Scope
jabgui/src/main/java/org/jabref/gui/frame/FrameDndHandler.java[168-168]
jabgui/src/main/java/org/jabref/gui/externalfiles/ImportHandler.java[388-394]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The PR mixes an undocumented cross-library move feature with developer-documentation edits.

## Issue Context
Keep this PR limited to its stated documentation work, or move the functional Java and localization changes into a separately described PR.

## Fix Focus Areas
- jabgui/src/main/java/org/jabref/gui/frame/FrameDndHandler.java[168-168]
- jabgui/src/main/java/org/jabref/gui/externalfiles/ImportHandler.java[388-394]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

3. Move behavior lacks tests 📘 Rule violation ☼ Reliability

Description

The PR adds asynchronous cross-library MOVE behavior that deletes source entries after imports, but
adds or updates no tests for copying, moving, partial skips, duplicate handling, or failures.
Regressions could cause unexpected duplication or deletion of library entries.

Code

jabgui/src/main/java/org/jabref/gui/externalfiles/ImportHandler.java[R390-393]

+                          if (transferInformation != null && transferInformation.transferMode() == org.jabref.model.TransferMode.MOVE && tracker.getImportedCount() == transferInformation.sourceEntries().size()) {
+                              BibDatabase sourceDatabase = transferInformation.bibDatabaseContext().getDatabase();
+                              List<BibEntry> sourceEntries = transferInformation.sourceEntries();
+                              sourceDatabase.removeEntries(sourceEntries);

Evidence

Rule 24 requires tests for behavior changes. The cited code introduces source deletion for MOVE,
while the PR diff contains no test-file changes and repository searches found no tests for
FrameDndHandler, LibraryTab.dropEntry, or entry MOVE handling.

AGENTS.md: Add Robust Tests for Behavior and Core Logic Changes
jabgui/src/main/java/org/jabref/gui/externalfiles/ImportHandler.java[388-394]
jabgui/src/main/java/org/jabref/gui/frame/FrameDndHandler.java[111-117]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The new cross-library MOVE and source-deletion behavior has no corresponding automated coverage.

## Issue Context
Cover successful moves and ensure source entries remain when imports are skipped or fail; also cover COPY behavior and transfer-mode mapping.

## Fix Focus Areas
- jabgui/src/main/java/org/jabref/gui/externalfiles/ImportHandler.java[388-394]
- jabgui/src/main/java/org/jabref/gui/frame/FrameDndHandler.java[111-117]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

View action required (4)

4. Copied keys missing locale bundles 📘 Rule violation ≡ Correctness

Description

The two new Copied localization keys are added only to the English bundle, while most locale
bundles do not contain them. Those locales will fall back instead of remaining synchronized with the
new code call sites.

Code

jablib/src/main/resources/l10n/JabRef_en.properties[R3088-3089]

+Copied\ %0\ entry(s)\ to\ %1=Copied %0 entry(s) to %1
+Copied\ %0\ entry(s)\ to\ %1.\ %2\ were\ skipped=Copied %0 entry(s) to %1. %2 were skipped

Evidence

Rule 34 requires every code-used localization key in English and all translated bundles with
identical placeholders. Searches across the 26 JabRef_*.properties bundles found these keys in
only English and six translated bundles, leaving the other locale catalogs unsynchronized.

jablib/src/main/resources/l10n/JabRef_en.properties[3088-3089]
jabgui/src/main/java/org/jabref/gui/LibraryTab.java[935-936]
Best Practice: Learned patterns

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The new `Copied` keys are absent from most locale bundles.

## Issue Context
Coordinate the key synchronization through the repository's approved localization/Crowdin workflow so every bundle has identical key punctuation and placeholders.

## Fix Focus Areas
- jablib/src/main/resources/l10n/JabRef_en.properties[3088-3089]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

5. Move feature lacks requirement 📘 Rule violation ⚙ Maintainability

Description

Enabling users to move entries between libraries is a new data-mutating feature, but this PR adds no
OpenFastTrace requirement under docs/requirements. The intended move, skip, duplicate, and failure
semantics are therefore not traceable.

Code

jabgui/src/main/java/org/jabref/gui/frame/FrameDndHandler.java[R115-117]

+                TransferMode mode = tabDragEvent.getTransferMode();
+                org.jabref.model.TransferMode modelTransferMode = from(mode);
+                destinationLibraryTab.dropEntry(sourceBibDatabaseContext, originalEntries, entryCopies, modelTransferMode);

Evidence

Rule 27 requires a requirement for new features and significant behavior changes. The cited lines
activate model MOVE behavior, while the PR diff contains no docs/requirements change and
repository search found no requirement for moving entries between libraries.

AGENTS.md: Trace New Features and Significant Bug Fixes to Requirements
jabgui/src/main/java/org/jabref/gui/frame/FrameDndHandler.java[115-117]
jabgui/src/main/java/org/jabref/gui/externalfiles/ImportHandler.java[390-393]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The new cross-library entry MOVE feature has no OpenFastTrace-compatible requirement.

## Issue Context
Document intended transfer-mode behavior and source-retention semantics in the appropriate requirements area, following the required identifier and markdownlint format.

## Fix Focus Areas
- jabgui/src/main/java/org/jabref/gui/frame/FrameDndHandler.java[115-117]
- docs/requirements/import.md[1-1]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

6. Move feature lacks changelog 📘 Rule violation ⚙ Maintainability

Description

The new ability to move entries between libraries is user-visible, but the PR does not add the
required one-sentence entry under Unreleased. Users therefore receive no release-note record of
the feature.

Code

jabgui/src/main/java/org/jabref/gui/frame/FrameDndHandler.java[168]

+            tabDragEvent.acceptTransferModes(TransferMode.COPY_OR_MOVE);

Evidence

Rule 29 requires every user-visible addition to have a correctly formed Unreleased entry. The
changed line exposes MOVE to users, but CHANGELOG.md is absent from the PR diff and its current
Unreleased section has no corresponding entry.

AGENTS.md: Maintain User-Facing CHANGELOG Entries in the Required Form
jabgui/src/main/java/org/jabref/gui/frame/FrameDndHandler.java[168-168]
CHANGELOG.md[10-14]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The user-visible cross-library MOVE capability has no `Unreleased` changelog entry.

## Issue Context
Add one sentence of at most 20 words under `Added`, beginning with `We added`, and use the documented TODO fallback because no issue is identified.

## Fix Focus Areas
- jabgui/src/main/java/org/jabref/gui/frame/FrameDndHandler.java[168-168]
- CHANGELOG.md[12-14]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

7. Drag-and-drop docs remain incomplete 📘 Rule violation ⚙ Maintainability

Description

The existing developer drag-and-drop documentation describes only main-table/group-panel transfer
and is not updated for the new cross-library COPY/MOVE flow. Maintainers cannot learn the new
transfer-mode mapping and deferred source-deletion behavior from the relevant documentation.

Code

jabgui/src/main/java/org/jabref/gui/frame/FrameDndHandler.java[R115-117]

+                TransferMode mode = tabDragEvent.getTransferMode();
+                org.jabref.model.TransferMode modelTransferMode = from(mode);
+                destinationLibraryTab.dropEntry(sourceBibDatabaseContext, originalEntries, entryCopies, modelTransferMode);

Evidence

Rule 30 requires developer documentation to stay synchronized with feature and behavior changes. The
cited code adds cross-library MOVE behavior, while the relevant drag-and-drop documentation still
only discusses transfers between the main table and groups panel.

AGENTS.md: Update Developer Documentation for Features and Behavior Changes
jabgui/src/main/java/org/jabref/gui/frame/FrameDndHandler.java[115-117]
docs/code-howtos/index.md[82-86]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
Relevant developer documentation does not describe the new cross-library COPY/MOVE flow.

## Issue Context
Update the existing drag-and-drop section with transfer-mode mapping, duplicate handling, and when source entries are removed.

## Fix Focus Areas
- jabgui/src/main/java/org/jabref/gui/frame/FrameDndHandler.java[115-117]
- docs/code-howtos/index.md[82-86]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

8. Failed adjustment prevents move 🐞 Bug ≡ Correctness

Description

When linked-file adjustment fails, continueImportAfterDuplicateHandling still imports and counts
the entry, but the new source-removal check runs only in onSuccess. A MOVE can therefore report
success while leaving every original entry in the source library, creating duplicates across
libraries.

Code

jabgui/src/main/java/org/jabref/gui/externalfiles/ImportHandler.java[390]

+                          if (transferInformation != null && transferInformation.transferMode() == org.jabref.model.TransferMode.MOVE && tracker.getImportedCount() == transferInformation.sourceEntries().size()) {

Evidence

The adjustment failure callback imports the unadjusted entry and increments the imported count at
lines 379-383. Source removal is newly implemented only inside the separate success callback at
lines 385-394, while InsertUtil uses the same imported count to produce the successful completion
message, proving this path can complete and report success without deleting the originals.

jabgui/src/main/java/org/jabref/gui/externalfiles/ImportHandler.java[377-395]
jabgui/src/main/java/org/jabref/gui/util/InsertUtil.java[41-59]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
Cross-library MOVE cleanup is only evaluated after successful linked-file adjustment. The failure callback still imports and marks the entry as imported, so a completed MOVE can leave all source entries behind.

## Issue Context
Preserve the current fallback import behavior when linked-file adjustment fails, but evaluate batch-complete source removal after every successful database import path. Ensure cleanup occurs only once and only when the whole MOVE batch was imported.

## Fix Focus Areas
- jabgui/src/main/java/org/jabref/gui/externalfiles/ImportHandler.java[377-395]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

9. GUI description is malformed 🐞 Bug ⚙ Maintainability

Description

The edited bullet says “The gui package the only one knows,” omitting the verb and producing an
ungrammatical architecture statement. This makes the developer documentation harder to understand
instead of correcting the original wording.

Code

docs/architecture-and-components.md[15]

+- The `gui` package the only one knows the user and their preferences and can interact with them to help them solving tasks.

Evidence

The changed line directly contains the incomplete construction “package the only one knows,” which
lacks the linking verb required by the statement.

docs/architecture-and-components.md[15-15]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The revised GUI-package description omits `is` and leaves the sentence grammatically malformed.

## Issue Context
Rewrite the bullet as a complete sentence while retaining the intended claim, for example: “The `gui` package is the only one that knows the user and their preferences and can interact with them to help solve tasks.”

## Fix Focus Areas
- docs/architecture-and-components.md[15-15]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

Tip of the day

💡 Did you know, you can type 'qodo, fix this' on a finding and the fix lands right on your PR

More tips ↗ | Customize Qodo ↗ | Qodo docs ↗

[koppor]

@Eng-YasminKotb Please always start on upstream/main. This time, you are allowed to force-push to get a clean list of commits.

[koppor]

How can the image be produced? Did you edit the SVG directly? Otherwise, the source of the image is helpful

No img.png - SVG is enough.

Rebase on oupstream/main - and remove unrelated changes

[Siedlerchr]

Thanks for the interest and the work It would be great to do this diagram in mermaid syntax so we can easily update this in future

[InAnYan]

I would also vote for the Mermaid diagram

[Eng-YasminKotb]

@Eng-YasminKotb Please always start on upstream/main. This time, you are allowed to force-push to get a clean list of commits.

I confirm I will start on upstream/main next times .
I used force-push , now 1 clean commit and 2 related files.

[Eng-YasminKotb]

How can the image be produced? Did you edit the SVG directly? Otherwise, the source of the image is helpful

No img.png - SVG is enough.

Rebase on oupstream/main - and remove unrelated changes

I produced this image using excalidraw then exported it as SVG, and it's allowed to share the source file .excalidraw (which is editable) , but I will switch to mermaid as proposed above.

[Eng-YasminKotb]

Thanks for the interest and the work It would be great to do this diagram in mermaid syntax so we can easily update this in future

Thanks! I'll do it in mermaid.

[Eng-YasminKotb]

I also noted that only one component has no description which is Microsoft Word Integration, is that intended? or we can add this simple description :
"This component manages exporting JabRef entries as MS Office 2007 XML so they can be used as citation sources in Microsoft Word's built-in bibliography tools."
https://docs.jabref.org/cite/export-to-microsoft-word

[Siedlerchr]

That's a good idea to add this. We probably just forgot it. Freel free to check other pages for inconsistenceis as well

[Eng-YasminKotb]

After making the diagram on mermaid there is no need for SVG image, right? @koppor, @InAnYan

[InAnYan]

Just added some personal nitpicks

addrssed

[Eng-YasminKotb]

while checking the Architecture and Components webpage after merge, I found an error related to mermaid version: "9.4.3" used in jabref.
So should we change the syntax to be compatible with version: "9.4.3" or upgrade the version itself ?

[subhramit]

while checking the[ Architecture and Components](https://devdocs.jabref.org/architecture-and-components.html) webpage after merge, I found an error related to mermaid `version: "9.4.3"` used in jabref. So should we change the syntax to be compatible with `version: "9.4.3"` or upgrade the version itself ?

If upgrading mermaid version causes you to make more changes to other mermaid diagrams, just make the syntax compatible. Else upgrade.