PlotJuggler Marketplace — Requirements

Version: 1.0.0 Last Updated: 2026-07-17 Purpose: Define WHAT the application should do, not HOW

1. Problem Statement

PlotJuggler has grown significantly, evolving from an internal tool to a de facto standard for data visualization in robotics. With this growth comes a problem: how do we allow the community to contribute plugins without requiring a full PlotJuggler recompilation for each update?

Current Pain Points

1. Users must recompile plugins when PlotJuggler updates
2. Qt version mismatches break plugins silently
3. High barrier to entry for plugin developers (CMake, Conan, CI setup)
4. No central discovery mechanism for available plugins
5. Manual installation process is error-prone

2. Feature Overview

2.1 Client Features (Marketplace UI)

2.2 CI System Features (For Developers)

2.3 Registry Features

3. Terminology

3a. Out of scope

These concerns are intentionally not part of pj_marketplace and belong elsewhere in the host application:

• Enable/disable installed plugins. Toggling a plugin on or off without uninstalling it is a host-application concern (e.g. a per-user config knob in pj_app that filters which discovered DSOs the loader instantiates), not a marketplace concern. The marketplace's job ends at "installed on disk"; whether the host chooses to load that DSO at startup is decided by the host's plugin loader and config.
• Runtime hot-reload of plugin instances. Out of scope per PJ4_PLAN non-goals.

4. Functional Requirements

4.1 P0 — Minimum Viable Product

4.2 P1 — Robustness

4.3 P2 — Polish

4.4 Bundled (core) extensions and plugin folders

The host application (via pj_runtime's ExtensionCatalogService) syncs bundled plugins into the extensions dir and decides which folders are scanned; the marketplace enforces the core-extension policy on top. Requirements on the combined behavior:

5. Non-Functional Requirements

6. Use Cases

UC-01: User Discovers and Installs Extension

Actor: PlotJuggler User Preconditions: PlotJuggler is running, internet available Flow:

1. User opens Marketplace (Plugins → Marketplace)
2. User searches for "ROS 2"
3. System shows matching extensions
4. User clicks on "ROS 2 Streaming"
5. User sees extension details (description, version, author)
6. User clicks "Install"
7. System downloads ZIP, verifies checksum, extracts
8. System shows "Installation complete"
9. User closes Marketplace
10. Plugin is available in PlotJuggler

Postconditions: Extension installed and registered

UC-02: User Updates Extension

Actor: PlotJuggler User Preconditions: Extension installed, newer version available Flow:

1. User opens Marketplace
2. User sees "Update available" badge on installed extension
3. User clicks "Update"
4. System backs up current version
5. System downloads and installs new version
6. System shows "Update complete"

Postconditions: New version installed, old version backed up

UC-03: User Uninstalls Extension

Actor: PlotJuggler User Preconditions: Extension installed; not a core (bundled) extension (those are uninstall-locked, see UC-08) Flow:

1. User opens Marketplace
2. User navigates to installed extensions
3. User clicks "Uninstall" on extension
4. System shows confirmation dialog
5. User confirms
6. System removes extension files
7. System refreshes installed cache

Postconditions: Extension removed, installed cache refreshed

UC-04: Plugin Fails to Load (Rollback Deferred)

Actor: System Preconditions: Extension recently updated, backup exists Flow:

1. PlotJuggler starts
2. System attempts to load plugin
3. Plugin crashes/fails
4. System reports the plugin load failure
5. Automatic backup restore is deferred

Postconditions: User is notified; any backup remains available for manual recovery

UC-05: Developer Publishes Extension

Actor: Plugin Developer Preconditions: Developer has GitHub account, uses template Flow:

1. Developer creates tag (v1.0.0)
2. CI compiles for all platforms
3. CI packages ZIPs with plugin binaries and resources
4. CI creates GitHub Release
5. CI submits PR to registry repository
6. Registry validates schema and URLs
7. PR is merged
8. Extension appears in marketplace

Postconditions: Extension available to all users

UC-06: First Launch of an Install with Bundled Plugins

Actor: System Preconditions: Installed build or AppImage shipping plugins in the bundled dir; fresh user profile Flow:

1. PlotJuggler starts
2. System seeds each bundled plugin into the extensions dir (one subfolder per id)
3. System scans the extensions dir and loads the seeded plugins
4. Marketplace shows them as installed core extensions (no Uninstall action)

Postconditions: Bundled plugins behave like normal installed extensions, managed from the extensions dir

UC-07: Application Upgrade Ships Newer Core Plugins

Actor: System Preconditions: Extensions dir holds core extensions seeded by an older application version; the new application bundles newer versions Flow:

1. User launches the upgraded application
2. Seed compares each bundled version against the installed copy
3. Installed copies older than the bundled version are replaced (staged copy, then swap); an info diagnostic records old → new
4. Installed copies equal or newer are left untouched

Postconditions: Core extensions are at least at the shipped version; user installs ahead of it survive

UC-08: User Updates a Core Extension Above the Bundled Version

Actor: PlotJuggler User Preconditions: Core extension installed; registry offers a newer version Flow:

1. User opens Marketplace and updates the core extension (normal update flow)
2. On later launches the seed leaves the newer copy untouched
3. Marketplace offers "Downgrade to bundled" instead of Uninstall
4. If the user downgrades, the shipped version is restored (staged, applied on restart)

Postconditions: User controls the version within [bundled, latest]; the id can never disappear

UC-09: Developer Overrides Plugins with --plugin-dir

Actor: Plugin Developer Preconditions: Freshly built plugin DSOs in a local folder Flow:

1. Developer launches plotjuggler4 --plugin-dir <build-output>
2. Seed still syncs bundled plugins into the extensions dir (never into the override folder)
3. Scan loads the override folder as the top, version-blind tier; the developer's build wins every id conflict — even against a newer marketplace or custom-folder copy
4. Marketplace manages the override folder; nothing is treated as core there

Postconditions: Developer builds shadow same-id plugins for the session; the user profile keeps its core extensions

7. Extension Categories

8. Corner Cases and Edge Cases

8.1 Network Issues

8.2 File System Issues

8.3 Version Conflicts

8.4 Update Staging & Restart

8.5 Plugin Loading

8.6 Bundled (core) extensions and folder precedence

9. Constraints

9.1 Must NOT Do

• No backend server — All hosting via GitHub (serverless)
• No Qt dependency in plugins — Plugins use abstract SDK only
• No database — Registry data is JSON; installed state is discovered from embedded DSO manifests, not a local state database
• No user accounts — Anonymous usage
• No telemetry — No data collection without consent

9.2 Assumptions

• Users have internet access for initial install
• GitHub raw URLs remain accessible
• Extensions are < 50MB compressed
• Registry has < 100 extensions in foreseeable future
• Plugin ABI surface stays narrow. Plugins do not link Qt — they consume the C ABI declared in plotjuggler_sdk/pj_plugins and expose only a small embedded manifest plus their vtable. This keeps cross-platform CI simple and decouples plugin builds from Qt version churn.

9.3 Out of Scope (v1.0)

• Paid extensions / license management
• Dependency resolution between extensions
• Automatic updates (always user-initiated)
• Plugin sandboxing / security isolation
• Extension ratings / reviews (metrics only)

10. Acceptance Criteria (MVP)

The minimum viable product is successful if:

1. Opens as standalone Qt Widgets app
2. Loads registry JSON from URL (GitHub raw)
3. Shows extension list with cards
4. Allows searching and filtering by category
5. Shows selected extension detail
6. Downloads ZIP with checksum verification
7. Extracts to local directory and registers as installed
8. Detects new available versions
9. Allows extension uninstallation
10. Works on Linux (Windows/macOS as stretch goal for MVP)

11. Data Formats

11.1 Registry JSON Schema

{
  "registry_version": "1.0",
  "last_updated": "ISO8601 timestamp",
  "extensions": [
    {
      "id": "unique-extension-id",
      "name": "Display Name",
      "description": "Short description",
      "author": "Author Name",
      "publisher": "Publisher Name",
      "website": "https://...",
      "repository": "https://github.com/...",
      "license": "SPDX identifier",
      "icon_url": "https://... (optional)",
      "category": "data_loader|data_streamer|parser|toolbox|bundle",
      "tags": ["tag1", "tag2"],
      "version": "semver",
      "min_plotjuggler_version": "semver",
      "plugins": [
        {
          "name": "PluginClassName",
          "type": "plugin_type",
          "library": "library_name_without_extension"
        }
      ],
      "platforms": {
        "linux-x86_64": {
          "url": "https://...",
          "checksum": "sha256:..."
        }
      },
      "changelog": {
        "1.0.0": "Initial release"
      }
    }
  ]
}

11.2 Installed State

There is no separate local state file. Installed extensions are discovered at runtime by scanning extensions_dir, loading candidate plugin DSOs, and reading each DSO's embedded plugin manifest. The marketplace never writes installed-state or plugin-manifest sidecars. Staged updates use a transient .pj_pending_install intent file so restart-time promotion can revalidate the staged DSO against the registry id/version that created it.

Fields read from the embedded plugin manifest:

11.3 Registry Extension Schema

{
  "id": "extension-id",
  "version": "semver",
  "min_plotjuggler_version": "semver",
  "plugins": [
    {
      "name": "PluginClassName",
      "type": "plugin_type",
      "library": "library_name",
      "ui_file": "optional_ui_file.ui"
    }
  ]
}

12. Open Follow-Ups

Remaining implementation follow-ups are tracked in TODO.md.

Document Maintenance

This file should be updated when:

• New requirements are identified
• Requirements are clarified or changed
• Use cases are added or modified
• Constraints change

Do NOT add:

• Implementation details
• Code examples
• Architecture decisions (→ ARCHITECTURE.md)
• How-to guides (→ USER_MANUAL.md)