Plugin API & Ecosystem Architecture Refactor for Long-Term Extensibility

[FTMahringer]

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.