FTMahringer/Synapse

Fork 0

Plugin API & Ecosystem Architecture Refactor for Long-Term Extensibility #38

New issue

Open

opened 2026-05-19 00:56:26 +02:00 by FTMahringer · 0 comments

FTMahringer commented

2026-05-19 00:56:26 +02:00

(Migrated from github.com)

Problem / Motivation

The current plugin system foundation in Synapse is already strong and ambitious:

synapse-plugin-api
JPMS isolation
ASM bytecode scanning
Plugin loader/runtime
Registry/store roadmap
Java-first provider ecosystem
Planned Python/Node.js runtimes
Marketplace/store architecture

However, the ecosystem is growing rapidly and future milestones (v2.6.x → v3.x → v4.x) will likely require a more generalized, future-proof plugin architecture.

The current API is still heavily centered around:

Channels
Model Providers
Agent/message flows

But future roadmap goals include:

Full marketplace/store ecosystem
Public plugin publishing
MCP plugins
Skills bundles
External runtimes
Infrastructure integrations
Analytics plugins
Calendar/Mail/File integrations
Worker/runner integrations
Governance systems
Enterprise extensions
UI/dashboard extensions

This issue proposes a long-term architectural review/refactor of the plugin ecosystem to ensure Synapse can evolve into a large extensible platform without repeatedly redesigning the API.

Current Relevant Roadmap Areas

Related roadmap milestones already exist in:

V3 Plugin Ecosystem
V3 Advanced Plugin Ecosystem
External Runtime Foundation
External Language Runtimes
V4 Plugin Store & SDK roadmap

The goal of this issue is NOT replacing those milestones.

Instead:

This issue tracks the architectural evolution needed underneath those milestones.

Proposed Goals

1. Move toward Provider/Capability Architecture

Instead of hardcoding plugin categories in core logic, plugins should expose capabilities.

Possible future provider/capability interfaces:

MailProvider
CalendarProvider
ToolProvider
FileProvider
WebhookProvider
AuthProvider
StorageProvider
SearchProvider
AnalyticsProvider
RunnerProvider
UIExtensionProvider

This allows Synapse to grow beyond only AI/model/chat plugins.

2. Add Plugin Service Registry

Plugins should be able to register and discover services dynamically.

Example:

context.services().register(CalendarProvider.class, this);

And:

CalendarProvider provider = context.services().get(CalendarProvider.class);

This becomes important once plugins begin depending on each other dynamically.

3. Typed Event System

The current event bus is flexible, but future large-scale ecosystems may benefit from typed events.

Example:

subscribe(MailReceivedEvent.class, event -> {
    ...
});

Potential benefits:

Better IDE support
Better API discoverability
Safer plugin interoperability
Easier SDK generation

4. Stable Plugin ABI/API Versioning

As the ecosystem grows, Synapse will need:

API compatibility guarantees
Capability negotiation
Plugin migration tooling
Deprecation lifecycle management
Multi-version compatibility handling

Potential future additions:

apiVersion: 2
minSynapseVersion: 2026.05
maxSynapseVersion: 2027.x
capabilities:
  - calendar-provider
  - mail-provider

5. Marketplace & Governance Architecture

The future marketplace/store system likely needs:

Plugin categories/taxonomy
Verified publishers
Permission scopes
Capability declarations
Security review pipeline
Compatibility metadata
Dependency trust chains
Plugin reputation system
Install-time permission prompts

Potential plugin permission examples:

permissions:
  - network.outbound
  - filesystem.read
  - calendar.read
  - mail.send

6. UI/Dashboard Extension System

Long-term, plugins may need to extend:

Dashboard pages
Settings sections
Widgets
Admin panels
Marketplace cards
CLI commands

Potential future plugin types:

Frontend Extension
Dashboard Module
Admin Module
Widget Plugin
CLI Extension

7. Runtime Abstraction Layer

Future external runtimes (Python/Node.js/MCP/etc.) will likely benefit from a unified runtime abstraction.

Instead of:

Java plugins handled one way
Python another
MCP another

Potentially:

Plugin Runtime Interface
 ├── JVM Runtime
 ├── Python Runtime
 ├── Node.js Runtime
 ├── MCP Runtime
 └── Future runtimes

This could simplify lifecycle handling and governance.

8. Developer Experience & SDK Architecture

The plugin ecosystem will eventually require:

Stable SDK generation
Better scaffolding
Testing harnesses
Local development sandbox
Plugin simulator
CI validation tooling
Version migration tooling
Plugin certification tests

Suggested Future Areas

Potential future architecture modules:

synapse-plugin-api
synapse-plugin-runtime
synapse-plugin-governance
synapse-plugin-registry
synapse-plugin-sdk
synapse-plugin-security
synapse-plugin-frontend

Important Note

This issue is intentionally broad and long-term.

The goal is to track architectural evolution ideas while Synapse is still early enough that large changes are possible without ecosystem breakage.

This should especially be revisited:

before V3.0.0
before public marketplace launch
before external runtimes become stable
before enterprise multi-tenant deployments

Priority

High (Long-Term Architecture)

The plugin system is becoming one of the central pillars of Synapse.
Future extensibility, governance, marketplace stability, and ecosystem growth will depend heavily on how flexible and stable the plugin architecture becomes.

## Problem / Motivation The current plugin system foundation in Synapse is already strong and ambitious: - `synapse-plugin-api` - JPMS isolation - ASM bytecode scanning - Plugin loader/runtime - Registry/store roadmap - Java-first provider ecosystem - Planned Python/Node.js runtimes - Marketplace/store architecture However, the ecosystem is growing rapidly and future milestones (v2.6.x → v3.x → v4.x) will likely require a more generalized, future-proof plugin architecture. The current API is still heavily centered around: - Channels - Model Providers - Agent/message flows But future roadmap goals include: - Full marketplace/store ecosystem - Public plugin publishing - MCP plugins - Skills bundles - External runtimes - Infrastructure integrations - Analytics plugins - Calendar/Mail/File integrations - Worker/runner integrations - Governance systems - Enterprise extensions - UI/dashboard extensions This issue proposes a long-term architectural review/refactor of the plugin ecosystem to ensure Synapse can evolve into a large extensible platform without repeatedly redesigning the API. --- ## Current Relevant Roadmap Areas Related roadmap milestones already exist in: - V3 Plugin Ecosystem - V3 Advanced Plugin Ecosystem - External Runtime Foundation - External Language Runtimes - V4 Plugin Store & SDK roadmap The goal of this issue is NOT replacing those milestones. Instead: This issue tracks the architectural evolution needed underneath those milestones. --- ## Proposed Goals ### 1. Move toward Provider/Capability Architecture Instead of hardcoding plugin categories in core logic, plugins should expose capabilities. Possible future provider/capability interfaces: ```java MailProvider CalendarProvider ToolProvider FileProvider WebhookProvider AuthProvider StorageProvider SearchProvider AnalyticsProvider RunnerProvider UIExtensionProvider ``` This allows Synapse to grow beyond only AI/model/chat plugins. --- ### 2. Add Plugin Service Registry Plugins should be able to register and discover services dynamically. Example: ```java context.services().register(CalendarProvider.class, this); ``` And: ```java CalendarProvider provider = context.services().get(CalendarProvider.class); ``` This becomes important once plugins begin depending on each other dynamically. --- ### 3. Typed Event System The current event bus is flexible, but future large-scale ecosystems may benefit from typed events. Example: ```java subscribe(MailReceivedEvent.class, event -> { ... }); ``` Potential benefits: - Better IDE support - Better API discoverability - Safer plugin interoperability - Easier SDK generation --- ### 4. Stable Plugin ABI/API Versioning As the ecosystem grows, Synapse will need: - API compatibility guarantees - Capability negotiation - Plugin migration tooling - Deprecation lifecycle management - Multi-version compatibility handling Potential future additions: ```yaml apiVersion: 2 minSynapseVersion: 2026.05 maxSynapseVersion: 2027.x capabilities: - calendar-provider - mail-provider ``` --- ### 5. Marketplace & Governance Architecture The future marketplace/store system likely needs: - Plugin categories/taxonomy - Verified publishers - Permission scopes - Capability declarations - Security review pipeline - Compatibility metadata - Dependency trust chains - Plugin reputation system - Install-time permission prompts Potential plugin permission examples: ```yaml permissions: - network.outbound - filesystem.read - calendar.read - mail.send ``` --- ### 6. UI/Dashboard Extension System Long-term, plugins may need to extend: - Dashboard pages - Settings sections - Widgets - Admin panels - Marketplace cards - CLI commands Potential future plugin types: ```text Frontend Extension Dashboard Module Admin Module Widget Plugin CLI Extension ``` --- ### 7. Runtime Abstraction Layer Future external runtimes (Python/Node.js/MCP/etc.) will likely benefit from a unified runtime abstraction. Instead of: ```text Java plugins handled one way Python another MCP another ``` Potentially: ```text Plugin Runtime Interface ├── JVM Runtime ├── Python Runtime ├── Node.js Runtime ├── MCP Runtime └── Future runtimes ``` This could simplify lifecycle handling and governance. --- ### 8. Developer Experience & SDK Architecture The plugin ecosystem will eventually require: - Stable SDK generation - Better scaffolding - Testing harnesses - Local development sandbox - Plugin simulator - CI validation tooling - Version migration tooling - Plugin certification tests --- ## Suggested Future Areas Potential future architecture modules: ```text synapse-plugin-api synapse-plugin-runtime synapse-plugin-governance synapse-plugin-registry synapse-plugin-sdk synapse-plugin-security synapse-plugin-frontend ``` --- ## Important Note This issue is intentionally broad and long-term. The goal is to track architectural evolution ideas while Synapse is still early enough that large changes are possible without ecosystem breakage. This should especially be revisited: - before V3.0.0 - before public marketplace launch - before external runtimes become stable - before enterprise multi-tenant deployments --- ## Priority High (Long-Term Architecture) The plugin system is becoming one of the central pillars of Synapse. Future extensibility, governance, marketplace stability, and ecosystem growth will depend heavily on how flexible and stable the plugin architecture becomes.