Service Bridges
When developing BrainDrive plugins, you don't interact with the core system directly. Instead, you use service bridges.
Service bridges are standardized interfaces that allow plugins to communicate with the BrainDrive backend, frontend, and user environment without creating tight coupling or requiring external dependencies.
Why Service Bridges?
Service bridges provide a stable abstraction layer between your plugin and BrainDrive's core functionality. This architectural approach delivers three critical benefits:
- No plugin dependencies or conflicts – Plugins remain decoupled from core code and each other
- No breaking changes when core updates – As long as service contracts remain stable, internal changes won't break your plugin
- No intimate system knowledge needed – Ready-made helpers for common tasks eliminate boilerplate code
The result? Service bridges are designed to save you 90% of typical development time.
The Six Service Bridges
In React components, bridges are available through this.props.services. Backend lifecycle code can import the same service interfaces.
| Service Bridge | Purpose | Example Usage | Working Demo |
|---|---|---|---|
| 🔗 API Bridge | Call backend REST endpoints—including your own plugin's routes—without setting up an HTTP client manually. | await services.api.get('/my_plugin/endpoint') | ServiceExample_API |
| ⚡ Event Bridge | Send and listen for cross-plugin events to coordinate state or actions. | services.event.emit('eventName', data) | ServiceExample_Events |
| 🎨 Theme Bridge | Access the current theme (light or dark) and subscribe to changes so components adapt their styles. | const theme = services.theme.getCurrentTheme() | ServiceExample_Theme |
| ⚙️ Settings Bridge | Read or update user preferences and plugin settings, with support for system and user-level scopes. | services.settings.getSetting('myKey') | ServiceExample_Settings |
| 📍 PageContext Bridge | Retrieve the current page or route information—page IDs, paths, parameters—for context-aware plugins. | services.pageContext.getContext() | ServiceExample_PageContext |
| 💾 PluginState Bridge | Store and retrieve persistent key-value data scoped to your plugin, perfect for lightweight caching. | await services.pluginState.save(data) | ServiceExample_PluginState |
Learn By Doing
Each service bridge has a working example with visual demonstrations and full documentation. This is the fastest way to master service bridges:
The proven learning path:
- Follow the plugin developer quick start to get up and running
- Install any service bridge example through BrainDrive's Plugin Manager
- Add the demo modules to a page using drag & drop
- Interact with the components to see the service in action
- Review the developer guide and study the code patterns in the repository
- Copy those patterns to your own plugins
What you'll see in each demo:
- API Bridge – Authentication, streaming, error handling
- Event Bridge – Real-time messaging between modules
- Theme Bridge – Automatic light/dark theme switching
- Settings Bridge – Multi-scope configuration management
- PageContext Bridge – Location-aware plugin behavior
- PluginState Bridge – Persistent data storage
Each example includes a comprehensive developer guide with production-ready patterns you can use immediately.
Best Practices
- Lean on Bridges First: Favor bridges over rolling your own networking or storage logic to stay aligned with the ecosystem
- Emit Meaningful Events: Use descriptive event names and document payloads so other plugins can subscribe effectively
- Stay Theme-Aware: Subscribe to theme updates via the Theme Bridge so your UI matches BrainDrive's light and dark modes
- Respect User Preferences: Read and write through the Settings Bridge to honor user expectations across sessions
- Keep Cached Data Small: The Plugin State Bridge is best for small amounts of data. For larger needs, expose backend endpoints via the API Bridge
Next Steps
Start building by exploring the service bridge examples hands-on, or dive into the Plugin Developer Quick Start to scaffold your first plugin.
By leaning on service bridges, you can ship powerful, forward-compatible plugins with minimal overhead.
Questions?
Post in the developer forum at community.braindrive.ai. We're here to help build the future of user-owned AI together.