PlotJuggler Marketplace — Requirements

Version: 1.0.0 Last Updated: 2026-05-19 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

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 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

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

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)