Admin: Add Navbox contributing (via update-page on MediaWiki MCP Server)

2026-07-06T04:22:25Z

Add Navbox contributing (via update-page on MediaWiki MCP Server)

← Older revision		Revision as of 09:52, 6 July 2026
Line 119:		Line 119:

	[<nowiki/>https://github.com/ohcnetwork/care_scribe Care Scribe] is a published plugin that provides autofill functionality for the Care consultation forms. It is a useful reference for how a real plugin is structured across the backend and frontend.		[<nowiki/>https://github.com/ohcnetwork/care_scribe Care Scribe] is a published plugin that provides autofill functionality for the Care consultation forms. It is a useful reference for how a real plugin is structured across the backend and frontend.

			{{Navbox contributing}}

	{{Related}}		{{Related}}

Admin: OHC identity seed

2026-07-04T23:07:32Z

OHC identity seed

New page

{{Doc header
|type=guide
|domain=contributing
|title=Plugin system
|order=3
}}

Care is designed to be extended without forking the core. Functionality you do not want to maintain in the main codebase — a transcription service, a custom integration, a bespoke UI — ships as a '''plugin'''. There are two halves to the system:

* '''Backend plugs''' — Django apps loaded into the [<nowiki/>https://github.com/ohcnetwork/care <code>care</code>] server through <code>plug_config.py</code>.
* '''Frontend Care Apps''' — federated React bundles loaded into the [<nowiki/>https://github.com/ohcnetwork/care_fe <code>care_fe</code>] host at runtime.

A plugin can be backend-only, frontend-only, or both, depending on what it needs to do.

== Backend plugs ==

A backend plugin is a regular Django app. What makes it a Care plugin is that it is declared in <code>plug_config.py</code> using the <code>Plug</code> and <code>PlugManager</code> classes from the <code>plugs</code> package. The default Care image ships with '''no''' plugins enabled — <code>plug_config.py</code> declares an empty list — and you opt in by overriding that file with your own.

<syntaxhighlight lang="python">from plugs.manager import PlugManager
from plugs.plug import Plug

my_plugin = Plug(
name="my_plugin",
package_name="git+https://github.com/octo/my_plugin.git",
version="@v1.0.0",
configs={
"SERVICE_API_KEY": "my_api_key",
"SERVICE_SECRET_KEY": "my_secret_key",
"VALUE_1_MAX": 10,
},
)

plugs = [my_plugin]

manager = PlugManager(plugs)</syntaxhighlight>
Each <code>Plug</code> points at a <code>package_name</code> (here a Git source) and a <code>version</code>, and carries a <code>configs</code> dictionary that is passed to the plugin.

=== Load timing: build vs runtime ===

Plugins can be installed either while the Docker image is being '''built''' or at '''runtime'''. Build-time loading is recommended — it bakes the plugin and its dependencies into the image so containers start with a known, reproducible set of plugins rather than resolving packages on boot.

=== Config precedence ===

Every plugin defines its own configuration variables, usually with sensible defaults, and may read values from the environment. When the same value is set in more than one place, Care resolves it in this order (highest priority first):

# Values defined in <code>plug_config.py</code> (the <code>configs</code> dictionary on the <code>Plug</code>).
# Environment variables.
# Default values defined inside the plugin.

So <code>plug_config.py</code> always wins, environment variables fill the gaps, and the plugin's own defaults are the fallback.

=== URL mounting ===

The <code>PlugManager</code> automatically wires up each plugin's configuration and mounts its URLs under <code>/api/<plugin-name>/</code>. A plugin named <code>my_plugin</code> therefore exposes its routes under <code>/api/my_plugin/</code>.

=== Scaffolding a new plug ===

A backend plugin follows the structure of a typical Django app — you define your models, views, and URLs inside the plugin folder. To start from a working skeleton, use the [<nowiki/>https://github.com/ohcnetwork/care-plugin-cookiecutter care-plugin-cookiecutter] template rather than wiring everything up by hand.

=== Local development ===

For local work, install the plugin in editable mode so your source edits are picked up without reinstalling:

<syntaxhighlight lang="bash">pip install -e /path/to/plugin</syntaxhighlight>
If the plugin needs to inherit components from the core app, install Care itself in editable mode from inside the plugin:

<syntaxhighlight lang="bash">pip install -e /path/to/care</syntaxhighlight>
{{Tip|1=Set up the Care backend first — see [[Contributing/Local development/Backend setup|Backend local setup]] for getting the server running before you attach a plugin to it.}}

== Frontend Care Apps ==

On the frontend, a plugin is called a '''Care App''': a separately built React bundle that the <code>care_fe</code> host loads at runtime via Vite module federation. The host app is the federation <code>core</code> and shares key dependencies — <code>react</code>, <code>react-dom</code>, <code>react-i18next</code>, <code>@tanstack/react-query</code>, <code>raviger</code>, <code>sonner</code>, <code>decimal.js</code> — so a plugin reuses the host's single copy of each rather than bundling its own. Each Care App exposes a <code>./manifest</code> (from <code>src/manifest.tsx</code>) that declares the routes, components, tabs, and overrides it contributes; <code>src/pluginTypes.ts</code> in <code>care_fe</code> is the source of truth for that manifest contract.

=== How Care Apps are discovered ===

The host resolves its effective plugin set from two sources and merges them:

{| class="wikitable"
|-
! Source
! Where it comes from
! Behavior
|-
| Build-time
| <code>REACT_ENABLED_APPS</code> env var, parsed into <code>careConfig.careApps</code>
| Always enabled, read-only in the admin UI
|-
| API
| <code>GET /api/v1/plug_config/</code>
| Editable in the admin UI
|}

Build-time entries act as the base set, so they load even if the backend returns no matching <code>plug_config</code> row. When both sources define the same plugin, the build-time entry wins for overlapping metadata and non-conflicting API metadata is preserved. Each <code>REACT_ENABLED_APPS</code> entry takes the form <code>org/repo</code> or <code>org/repo@host/path/to/remoteEntry.js</code>; when the host/path is omitted, Care defaults to GitHub Pages at <code>https://{org}.github.io/{repo}</code>.

For each resolved plugin, the host validates the remote URL, registers the remote with Vite federation under the plugin's slug, loads its <code>./manifest</code>, and exposes the loaded manifests through <code>CareAppsContext</code>. If a remote is missing or fails to load, that plugin is logged and skipped — the rest of the app and other plugins keep working.

=== Local development ===

The recommended way to develop a Care App is '''in-tree''': drop or symlink your plugin checkout into the host's <code>apps/</code> directory so its manifest lives at <code>apps/<slug>/src/manifest.tsx</code>, then run the host dev server:

<syntaxhighlight lang="bash">npm run dev</syntaxhighlight>
The host's <code>localPluginDevSupport()</code> (in <code>vite.config.mts</code>) auto-discovers every <code>apps/*/src/manifest.tsx</code>, wires each plugin directly into the host's own Vite module graph, and serves its static assets — no separate build, no <code>vite preview</code>, and no <code>REACT_ENABLED_APPS</code> entry needed. Editing plugin source hot-reloads through the host; adding or removing a manifest triggers a full reload. Because dependencies are shared and deduplicated, you avoid duplicate React copies and the hook-order errors they cause.

When you need to exercise the real federated <code>remoteEntry.js</code> loading path (for example, to test the production flow), run the plugin standalone as a remote and point the host at it via <code>REACT_ENABLED_APPS</code>. In this mode there is no automatic HMR back to the host — the host only reloads after a plugin rebuild produces a fresh <code>remoteEntry.js</code>.

{{Tip|1=To reuse a host component inside a plugin, <code>care_fe</code> ships a <code>clone-component</code> CLI (<code>scripts/clone-component.ts</code>, <code>npm run clone-component</code>) that copies a component and every local file it transitively imports into your plugin's <code>src/</code> tree, rewriting host path aliases as it goes. Cloned files are independent copies and do not stay in sync with the host.}}

=== Override architecture ===

Care Apps can change host UI without the host code knowing about them, through an '''override''' system. The mental model: instead of a component rendering itself, it asks the system what it should be and renders that.

* Components opt in by wrapping their export with <code>register("ComponentName", Component)</code>. Usage does not change — call sites still render the component normally.
* The host computes a '''resolution map''' once and serves most lookups from it, keeping per-component resolution close to O(1). Overrides can be context-aware (page, role, position in the render tree), with a slower stack-aware path reserved for the rare cases that need it.
* A plugin registers its overrides through its manifest, letting it inject or replace behavior without breaking existing call sites.

{{Note|1=The override design note in <code>care_fe</code> (<code>docs/care-apps-override-architecture.md</code>) is a design-intent document. The authoritative, shipped implementation lives in <code>care_fe/src/lib/override/</code> (<code>register.ts</code>, <code>registry.ts</code>, <code>bridge.ts</code>, <code>types.ts</code>); where the note and the code disagree, the code wins.}}

== Example plugin ==

[<nowiki/>https://github.com/ohcnetwork/care_scribe Care Scribe] is a published plugin that provides autofill functionality for the Care consultation forms. It is a useful reference for how a real plugin is structured across the backend and frontend.

{{Related}}

Contributing/Plugin system - Revision history

Admin: Add Navbox contributing (via update-page on MediaWiki MCP Server)

Admin: OHC identity seed