# Setup Plugin Architecture

Goal: future modules can register setup behavior without editing the core wizard for every feature.

This is a design proposal only. No plugin runtime is implemented in D.7.1.

## Plugin Contract

```ts
interface SetupPlugin {
  moduleId: string;
  displayName: string;
  dependencies: string[];
  enabledCondition: SetupEnabledCondition;
  setupSteps: SetupStepDefinition[];
  csvTemplates: CsvTemplateDefinition[];
  seedTasks: SeedTaskDefinition[];
  verificationChecks: VerificationCheckDefinition[];
  resetScopes: ResetScopeDefinition[];
}
```

## Fields

| Field | Purpose |
| --- | --- |
| `moduleId` | Stable identifier, for example `crm.quotation`. |
| `displayName` | Human-readable module name in setup UI. |
| `dependencies` | Other module ids or seed package versions required first. |
| `enabledCondition` | Function/config deciding if module applies to this installation. |
| `setupSteps` | Optional wizard steps or sections contributed by the module. |
| `csvTemplates` | CSV templates owned by the module. |
| `seedTasks` | Idempotent seed operations. |
| `verificationChecks` | Checks added to the verification matrix. |
| `resetScopes` | Reset/reseed behavior owned by the module. |

## Example Plugin Manifest

```json
{
  "moduleId": "crm.quotation",
  "displayName": "CRM Quotation",
  "dependencies": ["core.foundation", "crm.foundation", "crm.approval"],
  "setupSteps": ["document-sequences", "approval-workflow", "csv-import"],
  "csvTemplates": ["quotations.csv", "quotation-items.csv", "quotation-parties.csv"],
  "seedTasks": ["quotation-document-sequences", "quotation-template-mappings"],
  "verificationChecks": ["SEQUENCE_QUOTATION", "APPROVAL_WORKFLOW", "PDF_TEMPLATE_ASSET"],
  "resetScopes": ["business_reset", "demo_uat_reset"]
}
```

## Core Modules

| Module | Owns |
| --- | --- |
| `core.foundation` | Readiness, users, organizations, memberships, setup state, seed manifests. |
| `crm.foundation` | Master options, branch/product type scopes, CRM role profiles, CRM assignments. |
| `crm.customer` | Customers, contacts, contact sharing, customer ownership verification. |
| `crm.lead` | Lead import, lead sequence verification, lead master options. |
| `crm.opportunity` | Opportunity import, parties, followups, outcome lifecycle checks. |
| `crm.quotation` | Quotations, items, parties, topics, quotation sequences. |
| `crm.approval` | Workflows, steps, matrices, approval verification. |
| `document` | Templates, template versions, mappings, libraries. |
| `notification` | Notification templates and provider readiness checks. |
| `reporting` | Report definitions and report catalog verification. |
| `future_asset` | Placeholder for asset/warehouse/catalog setup after schema decisions. |
| `future_hr` | Placeholder for teams/departments after schema decisions. |

## Execution Order

1. Load core plugins.
2. Resolve enabled modules.
3. Build dependency graph.
4. Detect cycles.
5. Sort setup steps by dependency and declared order.
6. Merge CSV templates and reject duplicate file ownership.
7. Merge verification checks and reset scopes.
8. Render wizard steps by module and step group.

## Cycle Rules

- A plugin cannot depend on itself.
- Cycles block setup startup with a developer-facing error.
- Optional dependencies must not introduce ordering ambiguity.

## Extension Points

### Setup Step

```ts
interface SetupStepDefinition {
  key: string;
  title: string;
  required: boolean;
  inputsSchema: unknown;
  previewAction?: string;
  commitAction?: string;
  produces: string[];
  invalidates: string[];
}
```

### CSV Template

```ts
interface CsvTemplateDefinition {
  fileName: string;
  requiredColumns: string[];
  optionalColumns: string[];
  importOrder: string;
  targetService: string;
  unsupportedReason?: string;
}
```

### Seed Task

```ts
interface SeedTaskDefinition {
  key: string;
  packageName: string;
  version: string;
  idempotent: boolean;
  dependencies: string[];
  dryRunAction: string;
  commitAction: string;
}
```

### Verification Check

```ts
interface VerificationCheckDefinition {
  checkId: string;
  area: string;
  requiredFor: string[];
  runAction: string;
  suggestedFix: string;
}
```

### Reset Scope

```ts
interface ResetScopeDefinition {
  key: string;
  destructive: boolean;
  allowedEnvironments: string[];
  requiresTypedConfirmation: boolean;
  affectedTables: string[];
  storageCleanup: "none" | "report_only" | "best_effort";
}
```

## Safety Rules

- Plugins can register behavior but cannot bypass setup core authorization.
- Plugin seed tasks must be idempotent or marked unsafe.
- Plugin reset scopes must declare affected tables and storage behavior.
- Plugin CSV templates must declare ownership to avoid two modules writing the same file contract.
- Setup core owns persistence of run state, manifests, audit events, and final reports.