# Plugin System Map

This page maps the plugin system: loading pipeline, providers/adapters, widget pipeline, and key files.

## 1. Core Responsibilities

- Plugin discovery and install (local/remote)
- Manifest → Prelude → Surface lifecycle
- Permission checks and SDK version gate
- Isolated IPC and UI view mounting

## 2. Main Entry Points

- PluginModule: `apps/core-app/src/main/modules/plugin/plugin-module.ts`
- Plugin runtime: `apps/core-app/src/main/modules/plugin/plugin.ts`
- Plugin index: `apps/core-app/src/main/modules/plugin/index.ts`
- SDK version gate: `packages/utils/plugin/sdk-version.ts`

## 3. Providers (Sources)

| Provider | Description | File |
| --- | --- | --- |
| Local Provider | local plugins | `apps/core-app/src/main/modules/plugin/providers/local-provider.ts` |
| File Provider | file path plugins | `apps/core-app/src/main/modules/plugin/providers/file-provider.ts` |
| GitHub Provider | GitHub source | `apps/core-app/src/main/modules/plugin/providers/github-provider.ts` |
| NPM Provider | NPM install | `apps/core-app/src/main/modules/plugin/providers/npm-provider.ts` |
| TPEX Provider | internal/store source | `apps/core-app/src/main/modules/plugin/providers/tpex-provider.ts` |
| Registry | provider registry | `apps/core-app/src/main/modules/plugin/providers/registry.ts` |

## 4. Adapters

| Adapter | Description | File |
| --- | --- | --- |
| Plugin Features Adapter | bridge plugin features into CoreBox | `apps/core-app/src/main/modules/plugin/adapters/plugin-features-adapter.ts` |
| Feature Search Tokens | tokenization for search | `apps/core-app/src/main/modules/plugin/adapters/feature-search-tokens.ts` |

## 5. Runtime and Views

- Runtime loader: `apps/core-app/src/main/modules/plugin/runtime/plugin-require.ts`
- Prelude compiler: `apps/core-app/src/main/modules/plugin/runtime/plugin-prelude-compiler.ts`
- Runtime tracker: `apps/core-app/src/main/modules/plugin/runtime/plugin-runtime-tracker.ts`
- View loader: `apps/core-app/src/main/modules/plugin/view/plugin-view-loader.ts`

## 6. Widget Pipeline

| Module | Description | File |
| --- | --- | --- |
| Widget Manager | widget lifecycle | `apps/core-app/src/main/modules/plugin/widget/widget-manager.ts` |
| Widget Compiler | build/compile | `apps/core-app/src/main/modules/plugin/widget/widget-compiler.ts` |
| Widget Loader | loader | `apps/core-app/src/main/modules/plugin/widget/widget-loader.ts` |
| Widget Processor | processor entry | `apps/core-app/src/main/modules/plugin/widget/widget-processor.ts` |
| Processors | concrete processors | `apps/core-app/src/main/modules/plugin/widget/processors/` |

## 7. Main Flow (Mermaid)

:::TuffCodeBlock{lang="mermaid"}
---
code: |
  flowchart TB
    discover["Providers (Local/NPM/GitHub/TPEX)"] --> install["Installer/Resolver"]
    install --> runtime["Plugin Runtime"]
    runtime --> manifest["Manifest.json"]
    manifest --> prelude["Prelude (index.js)"]
    prelude --> surface["Surface UI (attachUIView)"]
    prelude --> adapter["Feature Adapter"]
    adapter --> corebox["CoreBox Search Items"]
---
:::

## 8. Related Docs

- CoreBox behavior: `apps/nexus/content/docs/dev/architecture/corebox-and-views.en.mdc`
- IPC event map: `apps/nexus/content/docs/dev/architecture/transport-events.en.mdc`