Architecture and SDK

Brokerr uses an internal plugin architecture. A production provider is a direct subfolder of either:

backend/app/sync_v2/sources/<source_type>/
backend/app/sync_v2/targets/<target_type>/

The folder exports one create_plugin() factory from plugin.py. Discovery imports direct subfolders, validates their contracts, rejects duplicates, and sorts plugins by stable provider type. There is no core provider registry to edit.

The current SDK version is 5. Providers live in the Brokerr repository; pip packages and Python entry-point discovery are not implemented.

Dependency boundary

A provider may import:

• its own package;
• app.sync_v2.sdk and its public submodules;
• ordinary third-party libraries already available to Brokerr.

A provider must not import the database, FastAPI routes, engine services, another concrete provider, or internal storage models. Context objects provide HTTP, logging, credentials, cancellation, progress, identity, auth gateway, and mapping services without exposing their implementation.

This boundary has two consequences:

1. Adding a source or target does not add provider branches to the engine or UI.
2. A future source such as Jellyfin can feed an existing target without changing that target, provided it emits the canonical observations and capabilities the target features require.

Data flow

source runtime
  -> SourceItem observations
  -> source filters and enrichments
  -> target map_items()
  -> target read_items()
  -> deterministic feature planners
  -> persisted TargetOperation values
  -> target write_items() / revert_items()

Source items are provider-neutral and JSON-safe. Standard observations use fields such as watchlist, rating, playback_status, progress, total, and in_continue_watching. Provider-only data belongs under a namespaced extension key such as example.metadata.

Targets own mapping, remote snapshots, request construction, reconciliation, and safe revert behavior. Features plan operations without network access. The engine owns paging, conflicts, dry-run, persistence, cancellation, lifecycle, and confirmed state.

Provider development path

1. Define the manifest, capabilities, media, auth modes, resources, and instance schema.
2. Implement the required runtime methods.
3. Add deterministic source filters or target features only where needed.
4. Export create_plugin().
5. Add unit tests for manifest/schema validation and runtime behavior.
6. Add discovery and architecture tests proving the folder is found without core edits.
7. Add profile-resolution, dry-run/live, partial failure, Apply, and Revert tests.
8. Document provider defaults, pacing, mapping, safety, and reversibility.

Continue with Manifests and contracts, Add a source, or Add a target.