System Extension

System Extension — UMES Wizard

Extend any core module without modifying its source code. This skill guides you through the Universal Module Extension System (UMES) — selecting the right mechanism, generating all required files, and wiring everything correctly.

For full type contracts, see references/extension-contracts.md.

Table of Contents

1. Decision Tree
2. Response Enrichers
3. Widget Injection — Fields
4. Widget Injection — Columns
5. Widget Injection — Filters
6. Widget Injection — Row Actions & Bulk Actions
7. Widget Injection — Menu Items
8. API Interceptors
9. Mutation Guards
10. Component Replacement
11. Event Subscribers
12. The Triad Pattern
13. Wiring & Verification

1. Decision Tree

Ask what the developer wants to achieve. Match to the correct mechanism(s).

When multiple mechanisms are needed (e.g., "add a column"), follow the Triad Pattern (§12) which wires enricher → widget → injection-table as a coordinated set.

2. Response Enrichers

Purpose: Add computed fields to another module's API response. Fields are namespaced under _<yourModule> to avoid collisions.

File: src/modules/<your-module>/data/enrichers.ts

Template

import type { ResponseEnricher, EnricherContext } from '@open-mercato/shared/lib/crud/response-enricher'

const enricher: ResponseEnricher = {
  id: '<your-module>.<enricher-name>',
  targetEntity: '<target-module>.<entity>',  // e.g., 'customers.person'
  priority: 50,
  timeout: 2000,
  fallback: { _<your-module>: {} },

  async enrichOne(record, context: EnricherContext) {
    const em = context.em as EntityManager
    // Fetch your data for this single record
    const data = await em.findOne(YourEntity, {
      foreignId: record.id,
      organizationId: context.organizationId,
    })
    return {
      ...record,
      _<your-module>: {
        fieldName: data?.value ?? null,
      },
    }
  },

  // REQUIRED for list endpoints — prevents N+1 queries
  async enrichMany(records, context: EnricherContext) {
    const em = context.em as EntityManager
    const ids = records.map(r => r.id)
    // Single batch query for ALL records
    const items = await em.find(YourEntity, {
      foreignId: { $in: ids },
      organizationId: context.organizationId,
    })
    const byForeignId = new Map(items.map(i => [i.foreignId, i]))
    return records.map(r => ({
      ...r,
      _<your-module>: {
        fieldName: byForeignId.get(r.id)?.value ?? null,
      },
    }))
  },
}

export const enrichers = [enricher]

Rules

• MUST implement enrichMany — without it, list endpoints cause N+1 queries
• MUST namespace all added fields under _<your-module> prefix
• MUST NOT modify existing fields — enrichers are additive-only
• MUST use batch queries ($in) in enrichMany, never per-record lookups
• Set critical: false (default) so enricher failures don't break the target API
• Set timeout to prevent slow external calls from blocking responses
• Set fallback to provide safe defaults when enricher times out

Context Available

interface EnricherContext {
  organizationId: string    // Current tenant org
  tenantId: string          // Current tenant
  userId: string            // Authenticated user
  em: EntityManager         // Read-only database access
  container: AwilixContainer // DI container
  requestedFields?: string[] // Sparse fieldset request
  userFeatures?: string[]   // User's ACL features
}

3. Widget Injection — Fields

Purpose: Add an editable field to another module's CrudForm.

File: src/modules/<your-module>/widgets/injection/<widget-name>/widget.ts

Template

import type { InjectionFieldWidget } from '@open-mercato/shared/modules/widgets'
import { readApiResultOrThrow } from '@open-mercato/ui/backend/utils/apiCall'

const widget: InjectionFieldWidget = {
  metadata: { id: '<your-module>.injection.<field-name>', priority: 50 },
  fields: [
    {
      id: '_<your-module>.<fieldName>',  // Matches enricher namespace
      label: '<your-module>.fields.<fieldName>',  // i18n key
      type: 'select',  // text | textarea | number | select | checkbox | date | custom
      group: 'details',  // Target group in CrudForm
      options: [
        { value: 'option1', label: '<your-module>.options.option1' },
        { value: 'option2', label: '<your-module>.options.option2' },
      ],
    },
  ],
  eventHandlers: {
    onSave: async (data, context) => {
      const resourceId = (context as Record<string, unknown>).resourceId as string
      const value = (data as Record<string, unknown>)['_<your-module>.<fieldName>']

      // Upsert pattern — idempotent save
      const existing = await readApiResultOrThrow<{ items: Array<{ id: string }> }>(
        `/api/<your-module>/resource?foreignId=${resourceId}`,
      )
      if (existing?.items?.[0]?.id) {
        await readApiResultOrThrow(`/api/<your-module>/resource`, {
          method: 'PUT',
          body: JSON.stringify({ id: existing.items[0].id, foreignId: resourceId, value }),
        })
      } else {
        await readApiResultOrThrow(`/api/<your-module>/resource`, {
          method: 'POST',
          body: JSON.stringify({ foreignId: resourceId, value }),
        })
      }
    },
  },
}

export default widget

Rules

• Field id MUST match the enricher namespace path (e.g., _example.priority)
• onSave endpoints MUST be idempotent (use upsert pattern)
• Widget onSave fires BEFORE the core form save — design for partial failure
• Always use i18n keys for label and option labels — never hardcode strings
• The field reads its initial value from the enriched API response automatically

4. Widget Injection — Columns

Purpose: Add a column to another module's DataTable.

File: src/modules/<your-module>/widgets/injection/<widget-name>/widget.ts

Template

import type { InjectionColumnWidget } from '@open-mercato/shared/modules/widgets'

const widget: InjectionColumnWidget = {
  metadata: { id: '<your-module>.injection.<column-name>', priority: 40 },
  columns: [
    {
      id: '<your-module>_<fieldName>',
      header: '<your-module>.columns.<fieldName>',  // i18n key
      accessorKey: '_<your-module>.<fieldName>',     // Path to enriched data
      sortable: false,  // MUST be false for enriched-only fields
      cell: ({ getValue }) => {
        const value = getValue()
        return typeof value === 'string' ? value : '—'
      },
    },
  ],
}

export default widget

Rules

• accessorKey MUST point to enriched field path (e.g., _example.priority)
• sortable MUST be false for enriched-only fields (not in database index)
• Requires a matching Response Enricher that provides the data (Triad Pattern §12)

5. Widget Injection — Filters

Purpose: Add a filter control to another module's DataTable filter bar.

File: src/modules/<your-module>/widgets/injection/<widget-name>/widget.ts

Template

import type { InjectionFilterWidget } from '@open-mercato/shared/modules/widgets'

const widget: InjectionFilterWidget = {
  metadata: { id: '<your-module>.injection.<filter-name>', priority: 35 },
  filters: [
    {
      id: '<your-module><FilterName>',
      label: '<your-module>.filters.<filterName>',  // i18n key
      type: 'select',  // select | text | date | dateRange | boolean
      strategy: 'server',  // 'server' = sent as query param, 'client' = filtered locally
      queryParam: '<your-module><FilterName>',
      options: [
        { value: 'value1', label: '<your-module>.options.value1' },
        { value: 'value2', label: '<your-module>.options.value2' },
      ],
    },
  ],
}

export default widget

Server-Side Filtering

When strategy: 'server', the filter value is sent as a query parameter. You need an API Interceptor to process it:

// api/interceptors.ts
const filterInterceptor: ApiInterceptor = {
  id: '<your-module>.filter-by-<filterName>',
  targetRoute: '<target-module>/<entities>',  // e.g., 'customers/people'
  methods: ['GET'],
  priority: 50,
  async before(request, context) {
    const filterValue = request.query?.['<your-module><FilterName>']
    if (!filterValue) return { ok: true }

    // Query your data to find matching target IDs
    const em = context.em as EntityManager
    const matches = await em.find(YourEntity, {
      fieldName: filterValue,
      organizationId: context.organizationId,
    })
    const matchingIds = matches.map(m => m.foreignId)

    if (matchingIds.length === 0) {
      return { ok: true, query: { ...request.query, ids: 'NONE' } }
    }

    // Narrow results by rewriting the ids query parameter
    const existingIds = request.query?.ids as string | undefined
    const narrowedIds = existingIds
      ? matchingIds.filter(id => existingIds.split(',').includes(id))
      : matchingIds
    return { ok: true, query: { ...request.query, ids: narrowedIds.join(',') } }
  },
}

Rules

• Server filters require a matching API Interceptor to handle the queryParam
• Prefer ids query narrowing over post-filtering response arrays
• Return ids: 'NONE' to return empty results when no matches found

6. Widget Injection — Row Actions & Bulk Actions

Purpose: Add context menu actions or bulk operations to another module's DataTable.

Row Action Template

File: src/modules/<your-module>/widgets/injection/<widget-name>/widget.ts

import type { InjectionRowActionWidget } from '@open-mercato/shared/modules/widgets'
import { InjectionPosition } from '@open-mercato/shared/modules/widgets/injection-position'

const widget: InjectionRowActionWidget = {
  metadata: { id: '<your-module>.injection.<action-name>', priority: 30 },
  rowActions: [
    {
      id: '<your-module>.<entity>.<action>',
      label: '<your-module>.actions.<actionName>',  // i18n key
      icon: 'CheckSquare',  // Lucide icon name
      features: ['<your-module>.<action>'],  // ACL gating
      placement: { position: InjectionPosition.After, relativeTo: 'edit' },
      onSelect: (row, context) => {
        const id = (row as Record<string, unknown>).id as string
        const navigate = (context as { navigate?: (path: string) => void }).navigate
        navigate?.(`/backend/<your-module>/resource/${id}`)
      },
    },
  ],
}

export default widget

Bulk Action Template

import type { InjectionBulkActionWidget } from '@open-mercato/shared/modules/widgets'

const widget: InjectionBulkActionWidget = {
  metadata: { id: '<your-module>.injection.bulk-<action-name>', priority: 30 },
  bulkActions: [
    {
      id: '<your-module>.bulk.<action>',
      label: '<your-module>.actions.bulk<ActionName>',
      features: ['<your-module>.<action>'],
      onExecute: async (selectedRows, context) => {
        const ids = selectedRows.map(r => (r as Record<string, unknown>).id)
        await readApiResultOrThrow(`/api/<your-module>/bulk-action`, {
          method: 'POST',
          body: JSON.stringify({ targetIds: ids }),
        })
        ;(context as { refresh?: () => void }).refresh?.()
      },
    },
  ],
}

export default widget

Tab Widget Template (Detail Pages)

import type { InjectionWidget } from '@open-mercato/shared/modules/widgets'

const widget: InjectionWidget = {
  metadata: { id: '<your-module>.injection.<tab-name>', priority: 40 },
  component: () => import('./widget.client'),
}

export default widget

Then create the client component at widget.client.tsx:

'use client'
import { useT } from '@open-mercato/shared/lib/i18n/context'

export default function MyTabContent({ context }: { context: Record<string, unknown> }) {
  const t = useT()
  const resourceId = context.resourceId as string
  // Fetch and display your data
  return <div>...</div>
}

Rules

• Use InjectionPosition for relative placement — never hardcode positions
• Always set features for ACL-gated actions
• Row action id must be stable for integration testing
• Bulk action onExecute should call refresh() after mutation

7. Widget Injection — Menu Items

Purpose: Add items to sidebar, topbar, or profile dropdown.

File: src/modules/<your-module>/widgets/injection/<widget-name>/widget.ts

Template

import type { InjectionMenuItemWidget } from '@open-mercato/shared/modules/widgets'
import { InjectionPosition } from '@open-mercato/shared/modules/widgets/injection-position'

const widget: InjectionMenuItemWidget = {
  metadata: { id: '<your-module>.injection.menus' },
  menuItems: [
    {
      id: '<your-module>-<page>-link',
      labelKey: '<your-module>.menu.<pageName>',  // i18n key
      label: 'Fallback Label',  // Fallback if i18n missing
      icon: 'LayoutDashboard',  // Lucide icon name
      href: '/backend/<your-module>',
      features: ['<your-module>.view'],  // ACL gating
      groupId: '<your-module>.nav.group',
      groupLabelKey: '<your-module>.nav.group',
      placement: { position: InjectionPosition.Last },
    },
  ],
}

export default widget

Available Spot IDs

Rules

• Use labelKey (i18n) instead of label whenever possible
• Always set features for permission-gated items
• Use groupId + groupLabelKey to group related menu items
• Menu id must be stable for integration tests

8. API Interceptors

Purpose: Hook into API routes to validate, transform, or enrich requests/responses without modifying the route.

File: src/modules/<your-module>/api/interceptors.ts

Template

import type { ApiInterceptor } from '@open-mercato/shared/lib/crud/api-interceptor'

const interceptors: ApiInterceptor[] = [
  {
    id: '<your-module>.validate-<action>',
    targetRoute: '<target-module>/<entities>',  // e.g., 'customers/people'
    methods: ['POST', 'PUT'],
    priority: 50,  // Lower = earlier execution
    timeoutMs: 5000,

    async before(request, context) {
      // Validate request
      const value = request.body?.someField
      if (!value) {
        return { ok: false, statusCode: 422, message: 'someField is required' }
      }
      // Optionally rewrite body or query
      return { ok: true, body: { ...request.body, normalizedField: String(value).trim() } }
    },

    async after(request, response, context) {
      // Optionally enrich response
      return {
        merge: {
          _<your-module>: { processedAt: Date.now() },
        },
      }
    },
  },
]

export { interceptors }

Rules

• before hook: return { ok: false, message } to reject — never throw errors
• after hook: use merge to add fields, replace to swap entire response body
• Prefer exact targetRoute over wildcards (*) — wildcards match too broadly
• For filtering: rewrite query.ids (comma-separated UUIDs) — never post-filter response arrays
• Set features for permission-gated interceptors
• Interceptors run BEFORE sync event subscribers and mutation guards in the pipeline

9. Mutation Guards

Purpose: Block or validate mutations at the entity level before database persistence. Runs after interceptors and before ORM flush.

File: src/modules/<your-module>/data/guards.ts

Template

import type { MutationGuard, MutationGuardInput, MutationGuardResult } from '@open-mercato/shared/lib/crud/mutation-guard-registry'

const guard: MutationGuard = {
  id: '<your-module>.<guard-name>',
  targetEntity: '<target-module>.<entity>',  // or '*' for all entities
  operations: ['create', 'update'],  // create | update | delete
  priority: 50,  // Lower = earlier execution

  async validate(input: MutationGuardInput): Promise<MutationGuardResult> {
    // input.resourceId is null for create operations
    // input.mutationPayload contains the data being saved

    if (someConditionFails) {
      return {
        ok: false,
        status: 422,
        message: 'Validation failed: reason',
      }
    }

    // Optionally transform payload
    return {
      ok: true,
      modifiedPayload: { ...input.mutationPayload, normalizedField: 'value' },
      shouldRunAfterSuccess: true,
      metadata: { originalValue: input.mutationPayload?.field },
    }
  },

  async afterSuccess(input) {
    // Runs after successful mutation — for cleanup, cache invalidation, logging
    // input.metadata contains what you passed from validate()
  },
}

export const guards = [guard]

Rules

• resourceId is null for create operations — handle this case
• Return a new object for modifiedPayload — never mutate input.mutationPayload in place
• Guards with targetEntity: '*' run on EVERY entity mutation — use sparingly
• afterSuccess only runs when shouldRunAfterSuccess: true in the validate result
• Guard errors should return structured { ok: false, message } — never throw

10. Component Replacement

Purpose: Replace, wrap, or transform props of registered UI components without forking source code.

File: src/modules/<your-module>/widgets/components.ts

Template

import React from 'react'
import type { ComponentOverride } from '@open-mercato/shared/modules/widgets/component-registry'
import { ComponentReplacementHandles } from '@open-mercato/shared/modules/widgets/component-registry'

export const componentOverrides: ComponentOverride[] = [
  // Mode 1: Wrapper — decorate existing component (safest)
  {
    target: { componentId: ComponentReplacementHandles.section('ui.detail', 'NotesSection') },
    priority: 50,
    metadata: { module: '<your-module>' },
    wrapper: (Original) => {
      const Wrapped = (props: any) =>
        React.createElement(
          'div',
          { className: 'border border-blue-200 rounded-md p-2' },
          React.createElement(Original, props),
        )
      Wrapped.displayName = '<YourModule>NotesWrapper'
      return Wrapped
    },
  },

  // Mode 2: Props transform — modify incoming props
  {
    target: { componentId: ComponentReplacementHandles.dataTable('customers.people') },
    priority: 40,
    metadata: { module: '<your-module>' },
    propsTransform: (props: any) => ({
      ...props,
      defaultPageSize: 25,
    }),
  },

  // Mode 3: Replace — full component swap (highest risk)
  {
    target: { componentId: ComponentReplacementHandles.section('sales.order', 'ShipmentDialog') },
    priority: 50,
    metadata: { module: '<your-module>' },
    replacement: React.lazy(() => import('./CustomShipmentDialog')),
    propsSchema: ShipmentDialogPropsSchema,  // Zod schema for validation
  },
]

Handle IDs

Rules

• Prefer wrapper mode — it preserves the original component and is least likely to break
• replacement mode REQUIRES a propsSchema (Zod) for dev-mode contract validation
• Always set displayName on wrapper components for React DevTools debugging
• Wrapper composition: lower priority = innermost, higher priority = outermost

11. Event Subscribers

Purpose: React to domain events emitted by other modules (e.g., after entity creation).

File: src/modules/<your-module>/subscribers/<subscriber-name>.ts

Template

export const metadata = {
  event: 'customers.person.created',  // module.entity.action (past tense)
  persistent: true,  // true = survives server restart (uses queue)
  id: '<your-module>:on-customer-created',
}

export default async function handler(payload: Record<string, unknown>, ctx: unknown) {
  const { resourceId, organizationId, tenantId } = payload as {
    resourceId: string
    organizationId: string
    tenantId: string
  }

  // Perform side effects
  // Examples: create related records, send notifications, sync external systems
}

Sync Subscribers (Before-Event)

For subscribers that need to run before a mutation completes and can block it:

export const metadata = {
  event: 'customers.person.creating',  // .creating = before event (present tense)
  persistent: false,
  id: '<your-module>:validate-customer-create',
  sync: true,      // Run synchronously in request pipeline
  priority: 50,    // Lower = earlier
}

export default async function handler(payload: Record<string, unknown>) {
  const data = payload as { mutationPayload?: Record<string, unknown> }

  if (someConditionFails(data.mutationPayload)) {
    return { ok: false, status: 422, message: 'Cannot create: reason' }
  }

  // Optionally modify the mutation data
  return { ok: true, modifiedPayload: { ...data.mutationPayload, enrichedField: 'value' } }
}

Event Naming Convention

Rules

• After-events (.created, .updated, .deleted) cannot block — they are fire-and-forget
• Before-events (.creating, .updating, .deleting) require sync: true to block mutations
• Subscribers MUST be idempotent — events may be delivered more than once
• Use persistent: true for critical side effects that must survive restarts

12. The Triad Pattern

When extending another module's UI with data from your module, you need three coordinated pieces:

┌─────────────────┐     ┌──────────────────┐     ┌───────────────────┐
│  1. ENRICHER    │────▶│  2. WIDGET       │────▶│  3. INJECTION     │
│  (data/         │     │  (widgets/       │     │     TABLE         │
│   enrichers.ts) │     │   injection/     │     │  (widgets/        │
│                 │     │   <name>/        │     │   injection-      │
│  Adds _<module> │     │   widget.ts)     │     │   table.ts)       │
│  fields to API  │     │                  │     │                   │
│  response       │     │  Renders the     │     │  Maps widget to   │
│                 │     │  enriched data   │     │  target spot ID   │
└─────────────────┘     └──────────────────┘     └───────────────────┘

Example: Add "Priority" field to Customers form

Step 1 — Enricher (data/enrichers.ts):

const enricher: ResponseEnricher = {
  id: 'priorities.customer-priority',
  targetEntity: 'customers.person',
  priority: 50,
  async enrichOne(record, context) {
    const priority = await em.findOne(CustomerPriority, { customerId: record.id })
    return { ...record, _priorities: { level: priority?.level ?? 'normal' } }
  },
  async enrichMany(records, context) {
    const items = await em.find(CustomerPriority, { customerId: { $in: records.map(r => r.id) } })
    const byId = new Map(items.map(i => [i.customerId, i.level]))
    return records.map(r => ({ ...r, _priorities: { level: byId.get(r.id) ?? 'normal' } }))
  },
}
export const enrichers = [enricher]

Step 2 — Field Widget (widgets/injection/customer-priority-field/widget.ts):

const widget: InjectionFieldWidget = {
  metadata: { id: 'priorities.injection.customer-priority-field', priority: 50 },
  fields: [{
    id: '_priorities.level',
    label: 'priorities.fields.level',
    type: 'select',
    group: 'details',
    options: [
      { value: 'low', label: 'priorities.options.low' },
      { value: 'normal', label: 'priorities.options.normal' },
      { value: 'high', label: 'priorities.options.high' },
    ],
  }],
  eventHandlers: {
    onSave: async (data, context) => {
      const customerId = (context as any).resourceId
      const level = (data as any)['_priorities.level']
      await readApiResultOrThrow('/api/priorities/customer-priorities', {
        method: 'POST',
        body: JSON.stringify({ customerId, level }),
      })
    },
  },
}
export default widget

Step 3 — Injection Table (widgets/injection-table.ts):

export const widgetInjections = {
  'crud-form:customers.person:fields': {
    widgetId: 'priorities.injection.customer-priority-field',
    priority: 50,
  },
}

Step 4 — Run yarn generate to wire everything up.

Triad for Columns

Same pattern but with Column Widget instead of Field Widget:

13. Wiring & Verification

File Checklist

After implementing an extension, verify all files exist:

Post-Implementation Steps

1. Run yarn generate — registers new enrichers, widgets, interceptors, guards
2. Run yarn dev — verify extension appears in target module UI
3. Check browser console — look for warnings about invalid spot IDs or missing enrichers
4. Test the full flow — create/edit/delete in the target module, verify your extension works

Common Pitfalls

Rules

• MUST run yarn generate after adding any extension file
• MUST use i18n keys for all user-facing strings
• MUST implement enrichMany when creating Response Enrichers
• MUST namespace enriched fields under _<your-module> prefix
• MUST make onSave endpoints idempotent
• MUST use { ok: false, message } pattern instead of throwing errors in interceptors/guards
• MUST set sortable: false on columns backed by enriched data only
• MUST NOT modify existing fields in enrichers — additive only
• MUST NOT directly import entities from other modules — use EntityManager queries
• MUST NOT use wildcard interceptor routes unless absolutely necessary
• Prefer Response Enrichers over API Interceptor after hooks for adding data to responses
• Prefer Mutation Guards over sync before-event subscribers for blocking mutations
• When extending UI and data together, always follow the Triad Pattern (enricher → widget → injection-table)