Plugins Overview
Polyphony can be extended with plugins. A plugin is a self-contained ZIP archive that adds new backend API endpoints, database tables, and frontend pages to the application without modifying core code.
What a Plugin Can Do
- Backend routes — register new FastAPI endpoints under
/api/v1/plugins/{plugin-id}/ - Database tables — define SQLAlchemy models that are migrated automatically on install
- Frontend pages — ship a pre-compiled React bundle that is loaded at runtime
- Navigation links — inject menu items into the top navigation for any combination of roles
Plugin Lifecycle
A plugin moves through four distinct states:
| State | Tables exist | API mounted | Frontend active |
|---|---|---|---|
| Not installed | |||
| Active | ✓ | ✓ | ✓ |
| Deactivated | ✓ | ||
| Uninstalled |
Transitions
- Install → Active: ZIP is validated, files are extracted, DB migrations run, router is mounted, frontend routes become available. The plugin is active immediately.
- Active → Deactivated: The backend router is unloaded and menu items disappear. All data in plugin tables is preserved.
- Deactivated → Active: The router is re-mounted. No migrations are run again (schema has not changed).
- Active / Deactivated → Uninstalled: All plugin tables (prefixed
plugin_{id}_) are dropped and their data is permanently deleted. The source folder is removed. This action is irreversible.
Where Plugins Are Stored
After installation, plugin files live at:
backend/src/plugins/{plugin-id}/
├── plugin.json
├── backend/
│ ├── main.py
│ └── ...
└── frontend/
└── index.js
Frontend bundles are served as static files by the backend. There is no separate build or deploy step after installing a plugin.
Security
Warning: Plugin code runs with full backend and frontend privileges. This includes unrestricted database access, access to all environment variables, and the ability to call any internal service. Polyphony does not sandbox or verify plugin code.
Only install plugins from authors you trust completely.
Who Can Manage Plugins
Only admin users can install, configure, deactivate, and uninstall plugins. The plugin management panel is at Admin → Plugins.