Experience Platform Architecture

📋Learning Objectives

• Understand the Experience platform architecture and how it differs from traditional portals
• Learn how plugins are discovered, loaded, and secured via ARIA Shield
• Master the 8 Pillars of Plugin Excellence
• Understand the 9-theme system and CSS variable approach
• Use the Plugin SDK for API calls, authorization, and real-time updates
• Create a production-ready plugin from scratch in 5 minutes

🏗️Experience Platform Overview

What Makes Experience Different

• PDP-Aware UI: Every route, widget, and action is governed by OpenID AuthZEN decisions through ARIA Shield. Provable least-privilege UX.
• Runtime Module Activation: An ARIA Shield-served config enables/disables app modules on the fly—no rebuilds for tenants.
• Zero-Token SPA: Session in httpOnly cookies; no access tokens in browser. Eliminates token exfiltration.
• CSP-Safe Plugins: Plugins are ESM bundles loaded via ARIA Shield—no CSP relaxations or cross-origin scripts.
• Design System Consistency: Neon Flux tokens/components ensure premium, coherent UI across all plugins.

The Experience platform is a modular React application that hosts plugins:

Key Components

• App Shell: Main application frame with React Router, authentication, and theme management
• ARIA Shield (BFF): Security gateway handling auth, PDP evaluation, and API proxying
• Plugin Host: Dynamically loads and mounts plugins with isolation
• Shared UI Library: Common components (buttons, forms, tables) with theming built-in
• Plugin SDK: Hooks and utilities for API calls, authorization, and telemetry

📦Plugin Loading Mechanism

Plugins are loaded dynamically at runtime using module federation:

Loading Steps

1. Discovery: Shell fetches available plugins from registry
2. Manifest: Each plugin has a manifest.json with metadata
3. Loading: Plugin bundle loaded via dynamic import
4. Mounting: Plugin React component mounted in host container

🛣️Route Registration

Plugins register routes via their manifest:

{
  "name": "role-viewer",
  "routes": [
    {
      "path": "/roles",
      "component": "RoleListPage",
      "title": "Role List",
      "icon": "users"
    },
    {
      "path": "/roles/:id",
      "component": "RoleDetailPage",
      "title": "Role Details"
    }
  ]
}

📄Manifest Format (Plugin Config)

Example tenant registry in index.yaml:

tenants:
  - tenant_id: "*"
    plugins:
      - id: my-plugin
        title: "My Plugin"
        version: "1.0.0"
        enabled: true
        
        # 🔐 Security configuration (REQUIRED)
        authorization:
          pdp_application: "my-plugin"  # Unique scope for 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..."  # Verified on load
        
        # 🔒 API permissions (declare all endpoints)
        permissions:
          api:
            - method: POST
              path: /api/crud/execute
            - method: POST
              path: /access/v1/evaluation
        
        # 🗺️ Routes
        contributions:
          routes:
            - path: /my-plugin
              component: Dashboard
              title: "My Plugin"

Security Model

• pdp_application: Isolates authorization decisions—plugin A can't affect plugin B
• permissions.api: Allowlist of endpoints—requests outside this list get 403
• bundle.integrity: SHA256 hash verified before loading—prevents tampering

🏆The 8 Pillars of Plugin Excellence

// ❌ BAD: 25 lines of manual auth checking
const [canDelete, setCanDelete] = useState(false);
useEffect(() => { /* complex auth logic */ }, []);

// ✅ GOOD: 1 line with SDK
<Protected.Button resource="user" action="delete" onClick={handleDelete}>
  Delete User
</Protected.Button>

const { data, isLoading, error } = sdk.crud.use(
  'av_openldap', 'account', 'get_all_users',
  { page_size: 50 }
);

🎨The 9-Theme System

Available Themes

CSS Variables You MUST Use

// Page & Surfaces
background: 'var(--main-bg)'           // Page background
background: 'var(--card-bg)'           // Card backgrounds
color: 'var(--main-text)'              // Primary text
color: 'var(--main-text-secondary)'    // Muted text

// Interactive Elements
background: 'var(--button-bg)'         // Can be gradient!
border: '1px solid var(--border-color)'
boxShadow: 'var(--shadow-md)'

// State Colors
color: 'var(--error-color)'            // Errors
color: 'var(--success-color)'          // Success
color: 'var(--warning-color)'          // Warnings

🔌Plugin SDK Reference

SDK Namespaces

API Fetch (with automatic X-Plugin-Id header)

// GET request
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' })
});

Authorization Checks

// Single evaluation
const result = await sdk.authz.evaluate({
  resource: { type: 'workflow', id: 'wf-123' },
  action: { name: 'start' }
});
const allowed = result.decision === true;

// Batch evaluation (3x faster!)
const results = await sdk.authz.batchEvaluate([
  { resource: { type: 'user', id: userId }, action: { name: 'edit' } },
  { resource: { type: 'user', id: userId }, action: { name: 'delete' } }
]);

CRUD Operations

// Data fetching hook
const { data, isLoading, error } = sdk.crud.use(
  'av_openldap', 'account', 'get_all_users',
  { page_size: 50 }
);

// Execute command
const result = await sdk.crud.execute(
  'av_openldap', 'account', 'get_user_by_entryUUID',
  { SystemIdentifier: userId }
);

🔬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

# Browse per-plugin manifests
ls <YourRepoRoot>/ServiceConfigs/BFF/config/plugins/manifests/

# Windows
dir <YourRepoRoot>\ServiceConfigs\BFF\plugins

# macOS/Linux
ls <YourRepoRoot>/ServiceConfigs/BFF/plugins

mkdir -p <YourRepoRoot>/plugins/training-plugin/1.0.0/src
cd <YourRepoRoot>/plugins/training-plugin/1.0.0

{
  "name": "training-plugin",
  "version": "1.0.0",
  "type": "module",
  "scripts": {
    "build": "esbuild src/index.tsx --bundle --format=esm --platform=browser --target=es2020 --outfile=dist/index.esm.js --external:react --external:react-dom --minify"
  },
  "devDependencies": {
    "esbuild": "^0.21.0"
  }
}

const React = (globalThis as any).React;

export function Dashboard() {
  return React.createElement('div', {
    style: {
      padding: '24px',
      background: 'var(--main-bg)',
      color: 'var(--main-text)',
      minHeight: '100vh'
    }
  },
    React.createElement('h1', {
      style: { 
        fontSize: '28px', 
        marginBottom: '16px',
        color: 'var(--main-text)'
      }
    }, '🎓 Training Plugin'),
    
    React.createElement('div', {
      style: {
        background: 'var(--card-bg)',
        border: '1px solid var(--border-color)',
        borderRadius: '12px',
        padding: '20px'
      }
    }, 'Welcome to your first plugin!')
  );
}

export const routes = { Dashboard };

npm install
npm run build

# Generate integrity hash (PowerShell)
(Get-FileHash dist/index.esm.js -Algorithm SHA256).Hash.ToLower()

# Copy to ServiceConfigs — Windows
copy dist\index.esm.js <YourRepoRoot>\ServiceConfigs\BFF\plugins\training-plugin\1.0.0\

# macOS/Linux
cp dist/index.esm.js <YourRepoRoot>/ServiceConfigs/BFF/plugins/training-plugin/1.0.0/

🔧Troubleshooting Plugin Issues

permissions:
  api:
    - method: POST
      path: /api/crud/execute  # Add missing endpoint

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

# Update plugins.yaml with new hash

// ❌ BAD
color: '#ffffff'

// ✅ GOOD
color: 'var(--main-text)'

❓Knowledge Check

useEffect(() => {
  const unsubscribe = sdk.sse.subscribe('/events/tasks', data => {
    setTasks(data);
  });
  return unsubscribe;  // Cleanup on unmount
}, []);

📝Day 11 Checkpoint

• Understand what makes Experience different from typical portals
• Know how plugins are discovered, loaded, and secured via ARIA Shield
• Understand the 8 Pillars of Plugin Excellence
• Can use CSS variables for theme-aware styling
• Know the Plugin SDK namespaces and key methods
• Can create a basic plugin from scratch
• Can troubleshoot common plugin issues (403, integrity, theming)