Plugin Anatomy

📋Learning Objectives

• Understand the complete plugin directory structure and purpose of each file
• Master the plugins.yaml manifest schema (the source of truth)
• Learn about entry points, exports, and how the platform loads your code
• Understand routes, widgets, and component organization patterns
• Configure security settings: permissions, integrity, and PDP scoping
• Set up the build process with esbuild

📁Plugin Directory Structure

File Locations

Complete Plugin Structure

📄Plugin Manifest Schema

Complete Schema Reference

tenants:
  # Use "*" for all tenants, or specific host for tenant isolation
  experience.self.empowernow.ai:
    - id: my-plugin                      # Unique identifier (required)
      title: "My Plugin"                 # Display name in navigation
      version: "1.0.0"                   # Semantic version
      enabled: true                      # Toggle without removing
      
      # 🎯 Host compatibility
      engine:
        experience: ">=1.0.0"            # Required platform version
      
      # 🔐 Security configuration (CRITICAL)
      authorization:
        pdp_application: "my-plugin"     # Policy namespace isolation
        context:
          service_tier: "standard"       # free/standard/premium/enterprise
          compliance_level: "medium"     # low/medium/high/critical
          data_classification: "general" # public/general/internal/pii/secret
      
      # 📦 Bundle configuration
      bundle:
        file: "/app/plugins/my-plugin/1.0.0/index.esm.js"
        integrity: "sha256:abc123..."   # Optional: hash verification
      
      # 🔒 API permissions (allowlist)
      permissions:
        api:
          - method: GET
            path: /api/crud/tasks
          - method: POST
            path: /api/crud/execute
          - method: POST
            path: /access/v1/evaluation
        sse:                             # Server-Sent Events endpoints
          - /api/events/tasks/summary
      
      # 🗺️ Routes and widgets
      contributions:
        routes:
          - path: /my-plugin
            component: Dashboard
            title: "My Plugin"
            resource: plugin.route       # PDP resource hint
            action: view                 # PDP action hint
          - path: /my-plugin/settings
            component: SettingsPage
            title: "Settings"
        widgets:
          - slot: dashboard.main
            component: SummaryWidget
            resource: plugin.widget
            action: view

Key Fields Explained

🚪Entry Point (index.tsx)

Minimal Entry Point

// src/index.tsx - The simplest valid plugin
const React = (globalThis as any).React;

export function Dashboard() {
  return React.createElement('div', {
    style: { 
      padding: '24px',
      background: 'var(--card-bg)',
      color: 'var(--main-text)'
    }
  }, 'Hello from My Plugin!');
}

// Required export: routes object
export const routes = { Dashboard };

// Optional: widgets for dashboard slots
export const widgets = {};

// Default export for compatibility
export default { routes, widgets };

Production Entry Point

// src/index.tsx - Full-featured plugin
import { Protected, IfCan } from '@experience/plugin-auth';
import { CrudGrid } from '@empowernow/crud-ui';

const React = (globalThis as any).React;
const { usePlugin } = (globalThis as any).PluginSDK || {};

// Main page component
export function Dashboard() {
  const { sdk } = usePlugin();
  
  return React.createElement('div', { style: styles.container },
    React.createElement('h1', { style: styles.title }, 'My Plugin'),
    
    // Authorization-gated content
    React.createElement(IfCan, { resource: 'data', action: 'view' },
      React.createElement(CrudGrid, {
        sdk,
        from: 'system.object.get_all',
        columns: ['Name', 'Status', 'Created'],
        serverSidePagination: true,
        pageSize: 50
      })
    )
  );
}

// Detail page for individual items
export function DetailPage() {
  return React.createElement('div', null, 'Detail View');
}

// Dashboard widget (rendered in slots)
export function SummaryWidget() {
  return React.createElement('div', {
    style: {
      padding: '16px',
      background: 'var(--card-bg)',
      borderRadius: '8px'
    }
  }, 'Quick Summary Widget');
}

// Export mappings (component names must match plugins.yaml)
export const routes = { Dashboard, DetailPage };
export const widgets = { SummaryWidget };

export default { routes, widgets };

🔧Build Configuration (esbuild)

build.mjs

// build.mjs
import esbuild from 'esbuild';

await esbuild.build({
  entryPoints: ['src/index.tsx'],
  bundle: true,
  format: 'esm',                  // ESM required
  platform: 'browser',
  target: 'es2020',
  outfile: 'dist/index.esm.js',
  
  // Critical: these are provided by the platform
  external: [
    'react',
    'react-dom',
    '@empowernow/ui',
    '@empowernow/crud-ui',
    '@experience/plugin-auth'
  ],
  
  // Production settings
  minify: true,
  sourcemap: true,
  
  // Tree-shaking for smaller bundles
  treeShaking: true
});

console.log('✅ Build complete: dist/index.esm.js');

package.json

{
  "name": "my-plugin",
  "version": "1.0.0",
  "type": "module",
  "scripts": {
    "build": "node build.mjs",
    "watch": "node build.mjs --watch",
    "integrity": "powershell -Command \"(Get-FileHash dist/index.esm.js -Algorithm SHA256).Hash.ToLower()\""
  },
  "devDependencies": {
    "esbuild": "^0.21.0",
    "typescript": "^5.5.0"
  }
}

# PowerShell
$hash = (Get-FileHash dist/index.esm.js -Algorithm SHA256).Hash.ToLower()
Write-Host "sha256:$hash"

# Then add to plugins.yaml
bundle:
  integrity: "sha256:$hash"

🧩Component Organization Patterns

Pattern: Feature-Based Organization

# Group by feature, not file type
src/
├── features/
│   ├── users/
│   │   ├── UserList.tsx
│   │   ├── UserDetail.tsx
│   │   ├── userService.ts
│   │   └── useUsers.ts
│   │
│   └── tasks/
│       ├── TaskList.tsx
│       ├── taskService.ts
│       └── useTasks.ts
│
├── shared/
│   ├── components/        # Cross-feature UI
│   └── hooks/             # Cross-feature logic
│
└── index.tsx              # Re-exports everything

Pattern: Lazy Loading for Large Plugins

// Only load DetailPage when navigated to
const DetailPage = React.lazy(() => import('./pages/DetailPage'));

export function Dashboard() {
  return React.createElement(React.Suspense, {
    fallback: React.createElement('div', null, 'Loading...')
  },
    React.createElement(DetailPage)
  );
}

⚙️Plugin SDK Reference

SDK Namespaces

The SDK exposes five namespaces plus metadata:

interface PluginSDK {
  metadata: {
    pluginId: string;
    pdpApplication: string;           // From manifest.authorization.pdp_application
    baseContext: Record<string, any>; // From manifest.authorization.context
  };
  
  api: {                              // HTTP requests
    fetch: (path, init?) => Promise<Response>;
    useQuery: (key[], fn, opts?) => UseQueryResult;
  };
  
  sse: {                              // Server-Sent Events
    subscribe: (path, onMessage) => () => void;
    unsubscribeAll: () => void;
  };
  
  authz: {                            // Authorization checks
    evaluate: (req) => Promise<AuthZENResponse>;
    batchEvaluate: (evaluations[]) => Promise<AuthZENBatchResponse>;
  };
  
  crud: {                             // Orchestration Service
    use: (system, object, action, params?) => UseQueryResult;
    execute: (system, object, action, params?) => Promise<any>;
    run: (workflowName, data) => Promise<WorkflowResponse>;
  };
  
  telemetry: {                        // Custom event tracking
    track: (event, properties?) => void;
  };
  
  logger: Console;
}

api.fetch() — Authenticated Requests

// GET request with auto-stamped X-Plugin-Id header
const response = await sdk.api.fetch('/crud/tasks');
const tasks = await response.json();

// POST with body
const response = await sdk.api.fetch('/crud/tasks', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ title: 'New task' })
});

authz.evaluate() — Authorization Checks

// Check if user can perform action on resource
const result = await sdk.authz.evaluate({
  resource: { type: 'workflow', id: workflowId },
  action: { name: 'start' },
  context: { reason: 'manual_launch' }
});

if (result.decision === true) {
  // User is authorized
}

authz.batchEvaluate() — Bulk Permissions (3x Faster!)

// Check multiple permissions in single API call
const results = await sdk.authz.batchEvaluate([
  { resource: { type: 'user', id: userId }, action: { name: 'edit' } },
  { resource: { type: 'user', id: userId }, action: { name: 'delete' } },
  { resource: { type: 'user', id: userId }, action: { name: 'reset-password' } }
]);

const permissions = {
  canEdit: results.decisions[0]?.decision === 'Permit',
  canDelete: results.decisions[1]?.decision === 'Permit',
  canReset: results.decisions[2]?.decision === 'Permit'
};

crud.use() — Data Fetching Hook

// React hook for CRUD data with automatic caching
const { data, isLoading, error, refetch } = sdk.crud.use(
  'av_openldap',          // system
  'account',              // object type
  'get_all_users',        // action
  { page_size: 50 }       // params
);

if (isLoading) return <div>Loading...</div>;
if (error) return <div>Error: {error.message}</div>;

return data.map(user => <li key={user.id}>{user.name}</li>);

sse.subscribe() — Real-Time Updates

// Subscribe to server-sent events
useEffect(() => {
  const unsubscribe = sdk.sse.subscribe('/events/tasks/summary', data => {
    setCount(data.pending_count);
  });
  
  return unsubscribe;  // Cleanup on unmount
}, []);

🔐Authorization Patterns

Protected Components

// ❌ BAD: Manual auth check (25 lines of boilerplate)
const [canDelete, setCanDelete] = useState(false);
const [loading, setLoading] = useState(true);

useEffect(() => {
  (async () => {
    try {
      const result = await sdk.authz.evaluate({...});
      setCanDelete(result.decision === 'Permit');
    } finally {
      setLoading(false);
    }
  })();
}, []);

if (loading) return <button disabled>Loading...</button>;
if (!canDelete) return null;
return <button onClick={handleDelete}>Delete</button>;

// ✅ GOOD: SDK handles everything (1 line!)
<Protected.Button resource="user" action="delete" onClick={handleDelete}>
  Delete
</Protected.Button>

Conditional Sections with IfCan

// Show entire section only if authorized
<IfCan resource="admin" action="view">
  <AdminPanel />
</IfCan>

// Multiple permissions (any match)
const { canAny } = usePluginAuth();

if (canAny([
  ['user', 'edit'],
  ['user', 'delete']
])) {
  return <UserActionsToolbar />;
}

Programmatic Checks

const { can, canAll, canAny } = usePluginAuth();

// Single permission
if (can('report', 'export')) {
  showExportButton = true;
}

// Multiple permissions (all required)
if (canAll([
  ['budget', 'view'],
  ['budget', 'approve']
])) {
  showApprovalUI = true;
}

🛡️API Permissions & Enforcement

How Enforcement Works

1. Request: Plugin makes API call via SDK
2. Header Stamp: SDK adds X-Plugin-Id: my-plugin
3. Validation: BFF checks method + path against permissions.api[]
4. Response: If allowed, request proceeds; if denied, 403

Permission Configuration

permissions:
  api:
    # Exact path matching
    - method: GET
      path: /api/crud/tasks
    
    # Path templates with wildcards
    - method: GET
      path: /api/crud/tasks/{id}
    
    # PDP authorization endpoint
    - method: POST
      path: /access/v1/evaluation
    
  sse:
    # Server-Sent Events endpoints
    - /api/events/tasks/summary
    - /crud/events/workflow/status

BFF Routes Reference

Enforcement Responses

📊CRUD Integration

CrudGrid — Data Table with Everything Built-in

<CrudGrid
  sdk={sdk}
  from="system.object.get_all"
  columns={['Name', 'Email', 'Status']}
  serverSidePagination={true}   // Handles 10,000+ items
  pageSize={50}
  enableSelection={true}
  multiSelect={true}
  rowActions={[
    'View: view',               // Format: "Label: action"
    'Edit: edit',
    'Delete: delete'
  ]}
  onRowClick={(row) => handleRowClick(row)}
  onSelectionChange={(selected) => setSelected(selected)}
/>

What CrudGrid Provides

• ✅ Server-side pagination (handles 10,000+ items)
• ✅ Sorting and filtering
• ✅ Row selection (single/multi)
• ✅ Row actions with authorization checks
• ✅ Loading states and error handling
• ✅ Empty states
• ✅ Responsive design

Execute Workflows

// Run a workflow
const result = await sdk.crud.run('av_openldap_create_user', {
  FirstName: 'John',
  LastName: 'Doe',
  Email: 'john.doe@example.com'
});

console.log('User created:', result.workflow_id);

// Monitor workflow status
const status = await sdk.crud.getWorkflowStatus(result.workflow_id);
console.log('Status:', status.status);  // 'running', 'completed', 'failed'

Subscribe to Workflow Updates

const unsubscribe = sdk.crud.subscribeWorkflowStatus(executionId, (update) => {
  setStatus(update);
  if (update.status === 'completed') {
    console.log('Workflow completed:', update.result);
    unsubscribe();
  }
});

// Requires SSE permission:
// sse:
//   - /crud/events/workflow/status

🔬Hands-on Labs

# Windows — tenant registry
type <YourRepoRoot>\ServiceConfigs\BFF\config\plugins\index.yaml

# macOS/Linux — tenant registry
cat <YourRepoRoot>/ServiceConfigs/BFF/config/plugins/index.yaml

# View a plugin manifest (e.g. it-shop)
cat <YourRepoRoot>/ServiceConfigs/BFF/config/plugins/manifests/it-shop.yaml

mkdir -p <YourRepoRoot>/plugins/anatomy-lab/1.0.0/src
cd <YourRepoRoot>/plugins/anatomy-lab/1.0.0

const React = (globalThis as any).React;

export function Dashboard() {
  return React.createElement('div', {
    style: {
      padding: '24px',
      background: 'var(--card-bg)',
      borderRadius: '12px'
    }
  },
    React.createElement('h1', { 
      style: { color: 'var(--main-text)' } 
    }, '🔬 Anatomy Lab Plugin')
  );
}

export const routes = { Dashboard };
export const widgets = {};
export default { routes, widgets };

npm install
npm run build
npm run integrity

const React = (globalThis as any).React;
const { useState, useEffect } = React;
const sdk = (globalThis as any).pluginSdk;

export function Dashboard() {
  const [data, setData] = useState(null);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState(null);
  
  useEffect(() => {
    (async () => {
      try {
        // Use SDK to fetch data
        const response = await sdk.api.fetch('/api/health');
        const result = await response.json();
        setData(result);
      } catch (err) {
        setError(err.message);
      } finally {
        setLoading(false);
      }
    })();
  }, []);
  
  if (loading) return React.createElement('div', null, 'Loading...');
  if (error) return React.createElement('div', null, 'Error: ' + error);
  
  return React.createElement('div', { style: { padding: '24px' } },
    React.createElement('h1', null, 'SDK Lab'),
    React.createElement('pre', null, JSON.stringify(data, null, 2))
  );
}

permissions:
  api:
    - method: GET
      path: /api/health

npm run build
# Restart BFF or wait for hot-reload

export function Dashboard() {
  const [canDelete, setCanDelete] = useState(false);
  const [checking, setChecking] = useState(true);
  
  useEffect(() => {
    (async () => {
      try {
        const result = await sdk.authz.evaluate({
          resource: { type: 'task', id: 'demo-task' },
          action: { name: 'delete' }
        });
        setCanDelete(result.decision === true);
      } finally {
        setChecking(false);
      }
    })();
  }, []);
  
  return React.createElement('div', { style: { padding: '24px' } },
    React.createElement('h1', null, 'Authorization Lab'),
    
    checking 
      ? React.createElement('p', null, 'Checking permissions...')
      : canDelete
        ? React.createElement('button', {
            onClick: () => alert('Delete clicked!'),
            style: { background: '#ef4444', color: 'white', padding: '8px 16px' }
          }, 'Delete Task')
        : React.createElement('p', { style: { color: '#6b7280' } }, 
            'You do not have permission to delete.')
  );
}

permissions:
  api:
    - method: POST
      path: /access/v1/evaluation

🔧Troubleshooting Plugin Anatomy Issues

// index.tsx
export function Dashboard() { ... }  // Function name

# plugins.yaml
component: Dashboard  # Must match exactly

// build.mjs
external: ['react', 'react-dom']  // Mark as external

// index.tsx
const React = (globalThis as any).React;  // Use platform's React

# Verify file exists at expected path (replace <YourRepoRoot> with your project root)
# Windows
dir <YourRepoRoot>\ServiceConfigs\BFF\plugins\my-plugin\1.0.0\

# macOS/Linux
ls <YourRepoRoot>/ServiceConfigs/BFF/plugins/my-plugin/1.0.0/

# Update plugins.yaml to match
bundle:
  file: "/app/plugins/my-plugin/1.0.0/index.esm.js"

# Check what you're calling
# sdk.api.fetch('/api/crud/tasks', { method: 'DELETE' })

# Add to plugins.yaml
permissions:
  api:
    - method: DELETE
      path: /api/crud/tasks/{id}

# Regenerate the hash
$hash = (Get-FileHash dist/index.esm.js -Algorithm SHA256).Hash.ToLower()
Write-Host "sha256:$hash"

# Update plugins.yaml
bundle:
  integrity: "sha256:$hash"

// Use platform's CSS variables
style: {
  background: 'var(--card-bg)',      // ✓ Platform variable
  color: 'var(--main-text)',         // ✓ Platform variable
  border: '1px solid var(--border)', // ✓ Platform variable
  
  // NOT these custom ones:
  // background: 'var(--my-custom-bg)',  // ✗ Won't work
}

❓Knowledge Check

📝Day 12 Checkpoint

• Understand the complete plugin directory structure
• Can read and write valid plugins.yaml entries
• Know what exports the entry point must provide
• Understand esbuild configuration and external dependencies
• Can generate and verify bundle integrity hashes
• Know how component names map between manifest and exports
• Understand all 5 Plugin SDK namespaces (api, sse, authz, crud, telemetry)
• Can use Protected components for authorization-gated UI
• Understand API permissions and allowlist enforcement
• Can use batchEvaluate() for efficient permission checks
• Know how to integrate with CrudGrid and CRUD operations
• Can troubleshoot common anatomy and SDK issues