# Plugin loading mechanism documented

- **Pattern:** `ab-002095` (`plugin-extension-architecture.discovery-docs.loading-mechanism`)
- **Severity:** high
- **Lifecycle:** active
- **Last modified:** 2026-04-18
- **Canonical URL:** https://auditbuffet.com/patterns/ab-002095
- **License:** CC-BY-4.0 — attribute to AuditBuffet Pattern Catalog (https://auditbuffet.com/patterns/ab-002095)

## Why it matters

When the plugin loading mechanism is undocumented, a developer who has built a working plugin cannot install it. They do not know whether to place files in a `plugins/` directory, add an entry to a config file, or call a registration function. ISO 25010 maintainability.modularity requires that the extension point be clearly defined; an undocumented loading mechanism makes the extension point inaccessible despite technically existing. The barrier affects plugin users as much as plugin authors — a correctly built plugin that cannot be installed provides no value.

## Severity rationale

High because an undocumented plugin loading mechanism makes the plugin system functionally inaccessible: correctly built plugins cannot be installed by developers who cannot find the loading path.

## Remediation

Document the full loading flow in `src/plugins/README.md` or `docs/plugins.md`, covering file placement, naming conventions, configuration entries, and activation sequence. Include a working import pattern.

```ts
// src/plugins/loader.ts — dynamic plugin loading
const plugins = await import(`./plugins/${name}/index.ts`);
```

Also document whether plugins can be hot-loaded after startup or require a restart.

## Detection

- **ID:** `loading-mechanism`
- **Severity:** `high`
- **What to look for:** Check that the mechanism for discovering, loading, and activating plugins is clearly defined and documented. Plugin authors and users need to know: where do plugins live, how does the host find them, and how are they activated? Look for documentation or clear code covering:
  1. **File system discovery** — "Place plugins in the `plugins/` directory" or "Plugins are npm packages matching `my-app-plugin-*`"
  2. **Configuration-based** — "Add plugin names to the `plugins` array in `config.json`" or "Add to `plugins` field in `package.json`"
  3. **Registry-based** — "Install from the plugin marketplace at..."
  4. **Programmatic** — "Call `app.register(plugin)` in your setup file"
  Also check that the loading sequence is documented: when do plugins load relative to the host's startup? Can plugins be loaded after startup (hot-loading)?
- **Pass criteria:** Count all plugin loading strategies. The plugin loading mechanism is documented. A new user can understand: where to put a plugin, how the host discovers it, and when it gets activated. The mechanism is consistent (not three different undocumented ways to load plugins). At least 1 dynamic loading mechanism must exist (lazy import, worker, iframe).
- **Fail criteria:** No documentation on how plugins are discovered or loaded. A new user cannot determine: where to put a plugin file, how the host finds it, what triggers loading. OR multiple loading mechanisms exist and none is documented as the primary approach.
- **Skip (N/A) when:** Never — every plugin system has a loading mechanism. If it's undocumented, this check should fail.
- **Detail on fail:** `"No documentation explains how plugins are loaded. The source code shows plugins are loaded from a plugins/ directory via dynamic import, but this is not documented anywhere. A user looking to install a third-party plugin would not know where to place it or what file naming convention to follow."`
- **Remediation:** Document the loading flow in `src/plugins/README.md` or `docs/plugins.md`:

  ```ts
  // src/plugins/loader.ts — dynamic plugin loading
  const plugins = await import(`./plugins/${name}/index.ts`)
  ```

## External references

- iso-25010 maintainability.modularity

Taxons: code-quality

HTML version: https://auditbuffet.com/patterns/ab-002095