Files

T

gitrusprusandCursor cafc7335ad Add plugin platform with modular backend and frontend registry.

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>

2026-06-25 09:35:51 +03:00

2.0 KiB

Raw Permalink Blame History

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

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

Create Django app under backend/plugins_<id>/.
Implement Plugin subclass in plugin.py.
Register in backend/plugins/registry.py.
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.

2.0 KiB Raw Permalink Blame History