alla-allaos-fullstack/docs/setup/setup-plugin-architecture.md

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

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

{
  "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

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

CSV Template

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

Seed Task

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

Verification Check

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

Reset Scope

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.