Architecture and Components

This page discusses JabRef’s main architecture and components. Note that components are seen as “logical” components and summarize features and “real” code-components.

High-level architecture

JabRef’s code is structured into these packages:

  • The model package encompasses the most important data structures (BibDatases, BibEntries, Events, and related aspects) and has minimal logic attached.
  • The logic package is responsible for business logic such as reading/writing/importing/exporting and manipulating the model, and it is structured often as an API the gui can call and use.
  • Only the gui knows the user and their preferences and can interact with them to help them solving tasks.
  • For each layer, we form packages according to their responsibility, i.e., vertical structuring.
  • The model classes should have no dependencies to other classes of JabRef and the logic classes should only depend on model classes.
  • The cli package bundles classes that are responsible for JabRef’s command line interface.
  • The preferences package represents all information customizable by a user for their personal needs.

We use an event bus to publish events from the model to the other layers. This allows us to keep the architecture but still react upon changes within the core in the outer layers. Note that we are currently switching to JavaFX’s observables, as we aim for a stronger coupling to the data producers.

Package Structure

Permitted dependencies in our architecture are:

gui --> logic --> model
gui ------------> model
gui ------------> preferences
gui ------------> cli
gui ------------> global classes

logic ------------> model

global classes ------------> everywhere

cli ------------> model
cli ------------> logic
cli ------------> global classes
cli ------------> preferences

All packages and classes which are currently not part of these packages (we are still in the process of structuring) are considered as gui classes from a dependency standpoint.

Most Important Classes and their Relation

Both GUI and CLI are started via the JabRefMain which, in turn, calls JabRef which then decides whether the GUI (JabRefFrame) or the CLI (JabRefCLI and a lot of code in JabRef) will be started. The JabRefFrame represents the Window which contains a SidePane on the left used for the fetchers/groups. Each tab is a BasePanel which has a SearchBar at the top, a MainTable at the center and a PreviewPanel or an EntryEditor at the bottom. Any right click on the MainTable is handled by the RightClickMenu. Each BasePanel holds a BibDatabaseContext consisting of a BibDatabase and the MetaData (which is relevant data of the currently focussed database). A BibDatabase has a list of BibEntries. Each BibEntry has an ID, a citation key and a key/value store for the fields with their values. Interpreted data (such as the type or the file field) is stored in the TypedBibentry type. The user can change the JabRefPreferences through the PreferencesDialog.

Architectural Decision Records

JabRef collects core architecture decisions using “Architectural Decision Records”. They are available at https://devdocs.jabref.org/decisions/.

For new ADRs, please use adr-template.md as basis. More information on MADR is available at https://adr.github.io/madr/. General information about architectural decision records is available at https://adr.github.io/.

Components

We regard each “larger” feature as component. Each such component gets a label “component: {component-name}” to enable ease issue searching of it.

AI

This component covers AI-assisted features in JabRef, such as “chatting” with PDF files.

Autocompletion

This component handles the automatic suggestion of previously used field values (e.g., authors, journals) while editing entries to improve data consistency and entry speed.

Automatic Field Editor

This component refers to the automatic editing or updating of entry fields based on predefined rules or heuristics, such as generating citation keys or filling missing metadata.

Backup

This component manages the creation and recovery of automatic backups and autosave files to prevent data loss during unexpected shutdowns or crashes.

Bib(La)TeX

This component deals with BibTeX and BibLaTeX support, including parsing, validation, formatting, and compatibility with LaTeX-based workflows.

Browser Plugin

This component refers to the JabRef browser extension, which allows direct import of bibliographic metadata from supported websites into the JabRef library.

Citation Key Generator

This component manages the generation of citation keys based on customizable patterns, ensuring consistent and meaningful citation identifiers for BibTeX/BibLaTeX entries.

Citation Relations

This component focuses on features that analyze and visualize relationships between cited and citing works, helping users understand bibliographic networks and dependencies.

Cite-As-You-Write

This component covers integration with TeX processors to allow inserting citations and bibliographies directly while writing documents similar to Better BibTeX for Zotero’s cite as you write.

Cleanup Operations

This component manages automatic and manual cleanup actions such as formatting fields, unifying entry data, removing unwanted characters, and applying field-specific transformations.

Duplicate Finder

This component detects and helps resolve duplicate bibliographic entries.

Entry Editor

This component is responsible for the editing interface of bibliographic entries, including field input, validation, source tab, and customization of visible fields.

Entry Preview

This component controls the preview pane that renders formatted citations or abstracts of the selected entry, using configurable citation styles such as APA, IEEE, or custom layouts.

Event Bus

This component manages JabRef’s internal event bus system, which enables communication between decoupled components through event publishing and subscription.

Export or Save

This component deals with saving and exporting bibliographic data to various formats and destinations, including file exports, custom layouts, and compatibility with external tools.

External Changes

This component monitors and responds to modifications of library files made outside JabRef, allowing users to review and merge external changes into the current library.

External Files

This component manages the linking, detection, renaming, moving, and organization of external files (such as PDFs) associated with bibliographic entries.

Fetcher

This component handles the retrieval of bibliographic data from online sources such as CrossRef, PubMed, arXiv, and other academic databases using fetchers integrated into JabRef.

GitHub Action

This component refers to the GitHub Action offered by JabRef.

Groups

This component manages the grouping functionality in JabRef, allowing users to organize and categorize entries using static or dynamic groups.

Import/Load

This component handles loading of existing bibliographic files and importing data from external sources, such as databases, file formats (BibTeX, RIS, etc.), or PDFs.

Installation

This component includes issues related to installing JabRef on supported platforms (Windows, macOS, Linux), including packaging, platform-specific bugs, and setup instructions.

Integrity Checker

This component validates entries against predefined rules to detect inconsistencies, missing fields, or incorrect formatting, helping maintain a high-quality bibliographic library.

JabKit [CLI]

This component covers the command-line interface for JabRef, known as JabKit, enabling batch operations such as conversion, validation, or citation key generation without the GUI.

Journal Abbreviations

This component deals with the management and application of journal abbreviation lists, supporting consistent formatting for citations in different publication styles.

Keybinding

This component manages keyboard shortcuts within JabRef, allowing users to configure and use key combinations for quicker navigation and action execution.

Keywords

This component handles the management of keywords in bibliographic entries, including editing, merging, filtering, and automatic keyword generation or cleaning.

LaTeX Citations

This component manages support for LaTeX citation formats, including parsing and interpreting \cite commands in .tex files and linking them to corresponding BibTeX entries.

Logging

This component handles JabRef’s internal logging infrastructure, including debug output, error reporting, log file generation, and diagnostics to aid development and support.

Main Table

This component refers to the central entry table in JabRef, including its layout, column configuration, sorting, grouping, and customization of displayed fields.

Microsoft Word Integration

PDF Viewer

This component relates to the built-in PDF viewer functionality in JabRef, including rendering PDFs and annotations.

Preferences

Covers all aspects of configuration settings for features, appearance, and behavior.

This component covers the search functionality within JabRef, including simple and advanced search modes, live filtering, and field-specific queries.

SLR

This component provides support for conducting Systematic Literature Reviews, including study tracking, classification, and advanced filtering of bibliographic entries.

Theming

This component manages the visual appearance of JabRef, including support for light/dark themes, font settings, and overall UI styling customization.

UI

This component encompasses the graphical user interface elements of JabRef, including layout, styling, usability, and interaction design across all views and dialogs.

Unicode

This component ensures correct handling, display, and conversion of Unicode characters in bibliographic entries, metadata, and file contents.

Welcome Tab

This component covers the welcome/startup screen shown when JabRef launches, providing quick access to recent libraries, documentation, and getting-started resources.