gitrusprusandCursor
cafc7335ad
Split graph/import/meta into Django apps, add API v1 with OpenAPI and pytest, and introduce plugin registry with the tags reference plugin on both FE and BE. Co-authored-by: Cursor <cursoragent@cursor.com>
64 lines
2.0 KiB
Markdown
64 lines
2.0 KiB
Markdown
# Plugin Author Guide
|
|
|
|
This document describes how to build **internal** plugins for Social Graph.
|
|
|
|
## Architecture overview
|
|
|
|
- **Core** owns contacts, relations, network maps, graph shell, import/export.
|
|
- **Plugins** extend the app via `registerPlugin()` without editing core files.
|
|
- **Backend** plugins are Django apps registered through `plugins.registry` and `ENABLED_PLUGINS`.
|
|
- **Frontend** plugins live under `frontend/src/plugins/<id>/` and are loaded at bootstrap.
|
|
|
|
## Frontend plugin contract
|
|
|
|
```javascript
|
|
import { registerPlugin } from '../../core/pluginRegistry'
|
|
|
|
registerPlugin({
|
|
id: 'my-plugin',
|
|
version: '1.0.0',
|
|
minCoreVersion: '1.0.0',
|
|
permissions: ['read:contacts'],
|
|
routes: [{ path: '/my', name: 'MyPlugin', component: MyView }],
|
|
navItems: [{ to: '/my', label: 'My plugin' }],
|
|
contactFormExtensions: [MyContactFieldset],
|
|
graphToolbarActions: [],
|
|
upgradeDexie(db) { /* db.version(N).stores({...}) */ },
|
|
syncContributor: {
|
|
entityType: 'plugin:my-plugin',
|
|
async pushChanges() {},
|
|
async pullChanges() {},
|
|
},
|
|
graphExtensions: {
|
|
extendNode(node) { return node },
|
|
extendEdge(edge) { return edge },
|
|
},
|
|
})
|
|
```
|
|
|
|
Enable via `VITE_ENABLED_PLUGINS=my-plugin,tags` at build time.
|
|
|
|
## Backend plugin contract
|
|
|
|
1. Create Django app under `backend/plugins_<id>/`.
|
|
2. Implement `Plugin` subclass in `plugin.py`.
|
|
3. Register in `backend/plugins/registry.py`.
|
|
4. Add app to `INSTALLED_APPS` and id to `ENABLED_PLUGINS` env var.
|
|
|
|
API surface: `/api/v1/plugins/<id>/...`
|
|
|
|
## Reference plugin: `tags`
|
|
|
|
- Frontend: `frontend/src/plugins/tags/`
|
|
- Backend: `backend/plugins_tags/`
|
|
- Dexie table: `contactTags`
|
|
- REST: `/api/v1/plugins/tags/contact-tags/`
|
|
|
|
## Local-first backup format
|
|
|
|
Plugin data should be included in backup v2+ under `plugins: { tags: [...] }` (planned extension). Current tags are stored in IndexedDB table `contactTags`.
|
|
|
|
## Permissions (Phase C)
|
|
|
|
Declared permissions are informational until JWT auth is enabled (`USE_JWT_AUTH=true`). Future scopes: `read:contacts`, `write:relations`, etc.
|