# 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.