@cdmbase/wiki-browser 12.0.18-alpha.5

package/lib/templates/content/docs/LLM/inngest/INNGEST_FUNCTION_DEVELOPMENT_GUIDE_LLM.md

@@ -0,0 +1,1241 @@
+# Complete Guide: Creating Inngest Functions in AdminIDE Stack
+
+## Overview
+
+This comprehensive guide provides step-by-step instructions for creating, configuring, and deploying Inngest workflow functions in the AdminIDE Stack project. This guide is designed for AI/LLM assistants and developers to create consistent, production-ready Inngest functions.
+
+---
+
+## Table of Contents
+
+1. [Architecture Overview](#1-architecture-overview)
+2. [Project Structure](#2-project-structure)
+3. [Creating WorkflowNamespace Templates](#3-creating-workflownamespace-templates)
+4. [Creating Inngest Functions](#4-creating-inngest-functions)
+5. [Registering with Feature System](#5-registering-with-feature-system)
+6. [Dependency Injection Patterns](#6-dependency-injection-patterns)
+7. [Step Functions and Workflows](#7-step-functions-and-workflows)
+8. [Triggering Events from Services](#8-triggering-events-from-services)
+9. [Best Practices](#9-best-practices)
+10. [Complete Examples](#10-complete-examples)
+11. [Troubleshooting](#11-troubleshooting)
+
+---
+
+## 1. Architecture Overview
+
+### What is Inngest?
+
+Inngest is a workflow engine that enables:
+
+- **Background Jobs**: Long-running tasks that don't block user requests
+- **Step Functions**: Multi-step workflows with automatic retry and state management
+- **Event-Driven Architecture**: Trigger workflows based on events
+- **Orchestration**: Coordinate multiple services and functions
+
+### How It Integrates with AdminIDE Stack
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                    AdminIDE Stack Architecture                   │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                   │
+│  ┌─────────────┐    ┌──────────────────┐    ┌─────────────────┐ │
+│  │   Feature   │───▶│ inngestFunctions │───▶│ /api/inngest    │ │
+│  │   System    │    │     Factory      │    │   Endpoint      │ │
+│  └─────────────┘    └──────────────────┘    └─────────────────┘ │
+│         │                    │                       │           │
+│         ▼                    ▼                       ▼           │
+│  ┌─────────────┐    ┌──────────────────┐    ┌─────────────────┐ │
+│  │   DI        │    │ WorkflowNamespace│    │    Inngest      │ │
+│  │ Container   │    │   Constants      │    │    Cloud/Dev    │ │
+│  └─────────────┘    └──────────────────┘    └─────────────────┘ │
+│                                                                   │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+### Key Components
+
+| Component               | Purpose                                                     |
+| ----------------------- | ----------------------------------------------------------- |
+| **WorkflowNamespace**   | Centralized constants for function IDs and event names      |
+| **Function Factory**    | Creates Inngest functions with DI container access          |
+| **Feature System**      | Registers functions and exposes `/api/inngest` endpoint     |
+| **Service Integration** | Triggers events from services using injected Inngest client |
+
+---
+
+## 2. Project Structure
+
+### Standard Module Structure
+
+```
+packages-modules/{module-name}/server/
+├── package.json                              # Contains cdecode template references
+├── src/
+│   └── modules/{feature}/
+│       ├── templates/
+│       │   └── constants/
+│       │       └── WorkflowNamespace.ts.template  # 🔑 Namespace definitions
+│       ├── inngest/
+│       │   ├── index.ts                      # Export factory function
+│       │   ├── functions.ts                  # Main factory that combines all functions
+│       │   ├── {action}Function.ts           # Individual function implementations
+│       │   └── ...
+│       ├── services/
+│       │   └── {ServiceName}.ts              # Services that trigger events
+│       └── module.ts                         # Feature registration
+└── docs/
+    └── inngest/                              # Documentation
+```
+
+### Example: user-auth0 Module
+
+```
+packages-modules/user-auth0/server/
+├── package.json
+└── src/modules/user-auth/
+    ├── templates/constants/
+    │   └── WorkflowNamespace.ts.template
+    ├── inngest/
+    │   ├── index.ts
+    │   ├── functions.ts
+    │   ├── configureKeycloakAuthSettings.ts
+    │   ├── createCompleteStackFunction.ts
+    │   ├── fetchAuthProviderByIdFunction.ts
+    │   └── configureAuthenticationProviderJob.ts
+    └── module.ts
+```
+
+---
+
+## 3. Creating WorkflowNamespace Templates
+
+### 3.1 Naming Convention
+
+**Pattern**: `{MODULE}_{FUNCTION_TYPE}_{SPECIFIC_ACTION}`
+
+#### Module Prefixes
+
+| Prefix         | Module                    |
+| -------------- | ------------------------- |
+| `TENANT_MGMT`  | Tenant Management         |
+| `AUTH_MGMT`    | Authentication Management |
+| `USER_AUTH`    | User Authentication       |
+| `BILLING`      | Billing Operations        |
+| `PROJECT_MGMT` | Project Management        |
+| `NOTIFICATION` | Notification Services     |
+| `KEY_MGMT`     | Key/Secret Management     |
+
+#### Suffix Types
+
+| Suffix     | Purpose              | Example                           |
+| ---------- | -------------------- | --------------------------------- |
+| (none)     | Function ID          | `TENANT_MGMT_CREATE_TENANT`       |
+| `_EVENT`   | Trigger event name   | `TENANT_MGMT_CREATE_TENANT_EVENT` |
+| `_SUCCESS` | Success result event | `TENANT_MGMT_TENANT_CREATED`      |
+| `_FAILED`  | Failure result event | `TENANT_MGMT_TENANT_FAILED`       |
+
+### 3.2 Template File Format
+
+**Location**: `src/modules/{feature}/templates/constants/WorkflowNamespace.ts.template`
+
+```typescript
+export const WorkflowNamespace = {
+    // ══════════════════════════════════════════════════════════════════
+    // {MODULE_NAME} Module - Function IDs
+    // ══════════════════════════════════════════════════════════════════
+
+    // Main orchestrating workflow
+    {PREFIX}_MAIN_WORKFLOW: '{prefix}-main-workflow',
+
+    // Individual function IDs
+    {PREFIX}_CREATE_{ENTITY}: '{prefix}-create-{entity}',
+    {PREFIX}_UPDATE_{ENTITY}: '{prefix}-update-{entity}',
+    {PREFIX}_DELETE_{ENTITY}: '{prefix}-delete-{entity}',
+    {PREFIX}_FETCH_{ENTITY}: '{prefix}-fetch-{entity}',
+
+    // ══════════════════════════════════════════════════════════════════
+    // {MODULE_NAME} Module - Trigger Events (what functions listen for)
+    // ══════════════════════════════════════════════════════════════════
+
+    {PREFIX}_MAIN_EVENT: '{prefix}-main-workflow/trigger',
+    {PREFIX}_CREATE_{ENTITY}_EVENT: '{prefix}/create-{entity}-trigger',
+    {PREFIX}_UPDATE_{ENTITY}_EVENT: '{prefix}/update-{entity}-trigger',
+    {PREFIX}_DELETE_{ENTITY}_EVENT: '{prefix}/delete-{entity}-trigger',
+    {PREFIX}_FETCH_{ENTITY}_EVENT: '{prefix}/fetch-{entity}-trigger',
+
+    // ══════════════════════════════════════════════════════════════════
+    // {MODULE_NAME} Module - Result Events (optional, for event chaining)
+    // ══════════════════════════════════════════════════════════════════
+
+    {PREFIX}_{ENTITY}_CREATED: '{prefix}/{entity}-created',
+    {PREFIX}_{ENTITY}_UPDATED: '{prefix}/{entity}-updated',
+    {PREFIX}_{ENTITY}_DELETED: '{prefix}/{entity}-deleted',
+};
+```
+
+### 3.3 Real Example: Auth Management
+
+```typescript
+export const WorkflowNamespace = {
+    // ══════════════════════════════════════════════════════════════════
+    // Auth Management Module - Function IDs
+    // ══════════════════════════════════════════════════════════════════
+
+    AUTH_MGMT_CONFIGURE_KEYCLOAK_SETTINGS: 'auth-mgmt-configure-keycloak-settings',
+    AUTH_MGMT_UPDATE_KEYCLOAK_SETTINGS: 'auth-mgmt-update-keycloak-settings',
+    AUTH_MGMT_CREATE_COMPLETE_STACK_FUNCTION: 'auth-mgmt-create-complete-stack-function',
+    AUTH_MGMT_CONFIGURE_AUTH_PROVIDER: 'auth-mgmt-configure-auth-provider',
+    AUTH_MGMT_FETCH_AUTH_PROVIDER: 'auth-mgmt-fetch-auth-provider',
+
+    // ══════════════════════════════════════════════════════════════════
+    // Auth Management Module - Trigger Events
+    // ══════════════════════════════════════════════════════════════════
+
+    AUTH_MGMT_CREATE_COMPLETE_STACK_EVENT: 'auth-mgmt-create-complete-stack-trigger',
+    AUTH_MGMT_CONFIGURE_KEYCLOAK_SETTINGS_EVENT: 'auth-mgmt/configure-keycloak-settings-trigger',
+    AUTH_MGMT_UPDATE_KEYCLOAK_SETTINGS_EVENT: 'auth-mgmt/update-keycloak-settings-trigger',
+    AUTH_MGMT_CONFIGURE_AUTH_PROVIDER_EVENT: 'auth-mgmt/configure-auth-provider-trigger',
+    AUTH_MGMT_FETCH_AUTH_PROVIDER_EVENT: 'auth-mgmt/fetch-auth-provider-trigger',
+};
+```
+
+### 3.4 Register Template in package.json
+
+Add template reference in `package.json`:
+
+```json
+{
+    "cdecode": {
+        "common": {
+            "constants": ["./${libDir}/modules/{feature}/templates/constants/WorkflowNamespace.ts.template"]
+        }
+    }
+}
+```
+
+### 3.5 Regenerate Common Module
+
+After creating/updating templates:
+
+```bash
+yarn regenerateGraphql && yarn generateGraphql
+```
+
+Or if using lerna:
+
+```bash
+lerna run build --scope=common
+```
+
+---
+
+## 4. Creating Inngest Functions
+
+### 4.1 Function Types
+
+| Type                      | Use Case                       | Container Access |
+| ------------------------- | ------------------------------ | ---------------- |
+| **Simple Function**       | Standalone operations          | No               |
+| **Container Function**    | Operations needing services    | Yes              |
+| **Orchestrator Function** | Coordinates multiple functions | Yes              |
+
+### 4.2 Simple Function (No Container)
+
+**File**: `src/modules/{feature}/inngest/simpleFunction.ts`
+
+```typescript
+import { Inngest } from 'inngest';
+import { WorkflowNamespace } from 'common/server';
+
+export const simpleFunction = (inngest: Inngest) =>
+    inngest.createFunction(
+        {
+            id: WorkflowNamespace.{PREFIX}_SIMPLE_ACTION,
+            name: 'Simple Action Description',  // Optional: Human-readable name
+            retries: 3,                          // Optional: Default is 3
+        },
+        {
+            event: WorkflowNamespace.{PREFIX}_SIMPLE_ACTION_EVENT
+        },
+        async ({ event, step }) => {
+            // Access event data
+            const { userId, payload } = event.data;
+
+            // Single step operation
+            const result = await step.run('process-data', async () => {
+                // Your business logic here
+                return { processed: true, userId };
+            });
+
+            return result;
+        },
+    );
+```
+
+### 4.3 Container Function (With DI)
+
+**File**: `src/modules/{feature}/inngest/containerFunction.ts`
+
+```typescript
+import { Container } from 'inversify';
+import { Inngest } from 'inngest';
+import { WorkflowNamespace, SERVER_TYPES, IMyService } from 'common/server';
+
+export const containerFunction = (container: Container, inngest: Inngest) =>
+    inngest.createFunction(
+        {
+            id: WorkflowNamespace.{PREFIX}_CONTAINER_ACTION,
+            name: 'Container Action with DI'
+        },
+        {
+            event: WorkflowNamespace.{PREFIX}_CONTAINER_ACTION_EVENT
+        },
+        async ({ event, step }) => {
+            const { entityId, data } = event.data;
+
+            // Step 1: Get service from container and perform operation
+            const entity = await step.run('fetch-entity', async () => {
+                const myService = container.get<IMyService>(SERVER_TYPES.MyService);
+                return myService.getById(entityId);
+            });
+
+            // Step 2: Process with another service
+            const processed = await step.run('process-entity', async () => {
+                const processorService = container.get<IProcessorService>(SERVER_TYPES.ProcessorService);
+                return processorService.process(entity, data);
+            });
+
+            // Step 3: Notify completion
+            await step.run('notify-completion', async () => {
+                const notificationService = container.get<INotificationService>(SERVER_TYPES.NotificationService);
+                await notificationService.notify({
+                    type: 'entity-processed',
+                    entityId,
+                    result: processed,
+                });
+            });
+
+            return {
+                status: 'completed',
+                entityId,
+                processed,
+            };
+        },
+    );
+```
+
+### 4.4 Orchestrator Function (Coordinates Other Functions)
+
+**File**: `src/modules/{feature}/inngest/mainWorkflow.ts`
+
+```typescript
+import { Container } from 'inversify';
+import { Inngest } from 'inngest';
+import { WorkflowNamespace } from 'common/server';
+import { createEntityFunction } from './createEntityFunction';
+import { configureEntityFunction } from './configureEntityFunction';
+import { notifyEntityFunction } from './notifyEntityFunction';
+
+export const mainWorkflowFunction = (container: Container, inngest: Inngest) =>
+    inngest.createFunction(
+        {
+            id: WorkflowNamespace.{PREFIX}_MAIN_WORKFLOW,
+            name: 'Main Orchestration Workflow'
+        },
+        {
+            event: WorkflowNamespace.{PREFIX}_MAIN_EVENT
+        },
+        async ({ event, step }) => {
+            const { userId, config } = event.data;
+
+            // Step 1: Invoke create function
+            const createResult = await step.invoke(WorkflowNamespace.{PREFIX}_CREATE_ENTITY, {
+                function: createEntityFunction(container, inngest),
+                data: { userId, config },
+            });
+
+            // Step 2: Wait for external process (if needed)
+            await step.sleep('wait-for-processing', '5s');
+
+            // Step 3: Invoke configure function
+            const configureResult = await step.invoke(WorkflowNamespace.{PREFIX}_CONFIGURE_ENTITY, {
+                function: configureEntityFunction(container, inngest),
+                data: {
+                    entityId: createResult.id,
+                    config
+                },
+            });
+
+            // Step 4: Parallel invocations (if supported)
+            const notifyResult = await step.invoke(WorkflowNamespace.{PREFIX}_NOTIFY_ENTITY, {
+                function: notifyEntityFunction(inngest),
+                data: {
+                    entityId: createResult.id,
+                    status: 'configured'
+                },
+            });
+
+            return {
+                status: 'workflow-completed',
+                createdEntity: createResult,
+                configuration: configureResult,
+                notification: notifyResult,
+            };
+        },
+    );
+```
+
+---
+
+## 5. Registering with Feature System
+
+### 5.1 Create Function Factory
+
+**File**: `src/modules/{feature}/inngest/functions.ts`
+
+```typescript
+import { Container } from 'inversify';
+import { Inngest } from 'inngest';
+import { simpleFunction } from './simpleFunction';
+import { containerFunction } from './containerFunction';
+import { mainWorkflowFunction } from './mainWorkflow';
+import { createEntityFunction } from './createEntityFunction';
+import { configureEntityFunction } from './configureEntityFunction';
+
+/**
+ * Factory function that creates all Inngest functions for this module.
+ * Called by the Feature system during initialization.
+ */
+export const inngestFunctionsFactory = (args: { container: Container; inngest: Inngest }) => [
+    // Simple functions (no container needed)
+    simpleFunction(args.inngest),
+
+    // Container functions (need DI)
+    containerFunction(args.container, args.inngest),
+    createEntityFunction(args.container, args.inngest),
+    configureEntityFunction(args.container, args.inngest),
+
+    // Orchestrator workflows
+    mainWorkflowFunction(args.container, args.inngest),
+];
+```
+
+### 5.2 Export from Index
+
+**File**: `src/modules/{feature}/inngest/index.ts`
+
+```typescript
+export { inngestFunctionsFactory } from './functions';
+```
+
+### 5.3 Register in Feature Module
+
+**File**: `src/modules/{feature}/module.ts`
+
+```typescript
+import { Feature } from '@common-stack/server-core';
+import { inngestFunctionsFactory } from './inngest';
+import { featureContainer } from './container';
+import { schema, resolver } from './graphql';
+
+export default new Feature({
+    // GraphQL
+    schema,
+    createResolversFunc: resolver,
+
+    // DI Container modules
+    createContainerFunc: [featureContainer],
+
+    // 🔑 Inngest Functions Registration
+    inngestFunctions: [({ container, inngest }) => inngestFunctionsFactory({ container, inngest })],
+
+    // Other feature configuration...
+    beforeware: [],
+    createServiceFunc: [],
+});
+```
+
+### 5.4 Alternative: Object Return Format
+
+The factory can also return an object (automatically handled):
+
+```typescript
+export const inngestFunctionsFactory = (args: { container: Container; inngest: Inngest }) => ({
+    simpleFunction: simpleFunction(args.inngest),
+    containerFunction: containerFunction(args.container, args.inngest),
+    mainWorkflow: mainWorkflowFunction(args.container, args.inngest),
+});
+```
+
+---
+
+## 6. Dependency Injection Patterns
+
+### 6.1 Accessing Services in Functions
+
+```typescript
+import { Container } from 'inversify';
+import { Inngest } from 'inngest';
+import { SERVER_TYPES, IUserService, ITenantService, WorkflowNamespace } from 'common/server';
+import { INTERNAL_SERVER_TYPES } from '../constants';
+
+export const myFunction = (container: Container, inngest: Inngest) =>
+    inngest.createFunction(
+        { id: WorkflowNamespace.MY_FUNCTION },
+        { event: WorkflowNamespace.MY_FUNCTION_EVENT },
+        async ({ event, step }) => {
+            // ✅ Get services inside step.run() for proper error handling
+            await step.run('step-with-services', async () => {
+                // Get services from container
+                const userService = container.get<IUserService>(SERVER_TYPES.IUserService);
+                const tenantService = container.get<ITenantService>(SERVER_TYPES.TenantService);
+
+                // Internal services use INTERNAL_SERVER_TYPES
+                const internalService = container.get(INTERNAL_SERVER_TYPES.IMyInternalService);
+
+                // Use services
+                const user = await userService.getById(event.data.userId);
+                const tenant = await tenantService.getById(event.data.tenantId);
+
+                return { user, tenant };
+            });
+        },
+    );
+```
+
+### 6.2 Common Service Identifiers
+
+```typescript
+// From common/server - SERVER_TYPES
+SERVER_TYPES.IUserService;
+SERVER_TYPES.TenantService;
+SERVER_TYPES.IAuthProviderService;
+SERVER_TYPES.KeyMgmtSecretService;
+
+// From @common-stack/core - CommonType
+CommonType.INNGEST_CLIENT;
+CommonType.REDIS_CLIENT;
+CommonType.MOLECULER_BROKER;
+
+// Internal module constants
+INTERNAL_SERVER_TYPES.IMyRepository;
+INTERNAL_SERVER_TYPES.IMyService;
+```
+
+---
+
+## 7. Step Functions and Workflows
+
+### 7.1 Step Types
+
+| Step Method           | Purpose                           | Example                   |
+| --------------------- | --------------------------------- | ------------------------- |
+| `step.run()`          | Execute code with automatic retry | Database operations       |
+| `step.invoke()`       | Call another Inngest function     | Orchestration             |
+| `step.sleep()`        | Pause execution                   | Wait for external process |
+| `step.sleepUntil()`   | Sleep until specific time         | Scheduled operations      |
+| `step.waitForEvent()` | Wait for an event                 | External triggers         |
+| `step.sendEvent()`    | Send events to other functions    | Event chaining            |
+
+### 7.2 step.run() - Execute Code
+
+```typescript
+// Simple step
+const result = await step.run('step-name', async () => {
+    return await someAsyncOperation();
+});
+
+// Step with service access
+const user = await step.run('get-user', async () => {
+    const userService = container.get<IUserService>(SERVER_TYPES.IUserService);
+    return userService.getById(userId);
+});
+```
+
+### 7.3 step.invoke() - Call Another Function
+
+```typescript
+import { createUserFunction } from './createUserFunction';
+
+// Invoke another function
+const userResult = await step.invoke(WorkflowNamespace.USER_CREATE, {
+    function: createUserFunction(container, inngest),
+    data: {
+        email: 'user@example.com',
+        name: 'John Doe',
+    },
+});
+```
+
+### 7.4 step.sleep() - Pause Execution
+
+```typescript
+// Sleep for duration
+await step.sleep('wait-for-processing', '30s');
+await step.sleep('long-wait', '5m');
+await step.sleep('very-long', '1h');
+
+// Sleep until specific time
+await step.sleepUntil('schedule-for-tomorrow', new Date('2024-12-25T10:00:00Z'));
+```
+
+### 7.5 step.waitForEvent() - Wait for External Event
+
+```typescript
+const paymentEvent = await step.waitForEvent('wait-for-payment', {
+    event: 'payment.completed',
+    timeout: '30m',
+    match: 'data.orderId', // Match on orderId
+});
+
+if (!paymentEvent) {
+    // Timeout occurred
+    throw new Error('Payment timeout');
+}
+```
+
+### 7.6 step.sendEvent() - Emit Events
+
+```typescript
+await step.sendEvent('notify-completion', {
+    name: WorkflowNamespace.ENTITY_CREATED,
+    data: {
+        entityId: result.id,
+        createdAt: new Date().toISOString(),
+    },
+});
+```
+
+---
+
+## 8. Triggering Events from Services
+
+### 8.1 Inject Inngest Client in Service
+
+```typescript
+import { injectable, inject } from 'inversify';
+import type { Inngest } from 'inngest';
+import { CommonType } from '@common-stack/core';
+import { WorkflowNamespace } from 'common/server';
+
+@injectable()
+export class TenantService implements ITenantService {
+    constructor(
+        @inject(SERVER_TYPES.TenantRepository)
+        private readonly tenantRepository: ITenantRepository,
+
+        @inject(CommonType.INNGEST_CLIENT)
+        private readonly inngestClient: Inngest,
+
+        @inject('Logger')
+        private readonly logger: Logger,
+    ) {}
+
+    async createTenant(input: ICreateTenantInput): Promise<ITenant> {
+        // Business logic
+        const tenant = await this.tenantRepository.create(input);
+
+        // Trigger Inngest workflow
+        await this.inngestClient.send({
+            name: WorkflowNamespace.TENANT_MGMT_CREATE_CLIENT_EVENT,
+            data: {
+                tenantId: tenant.id,
+                clientConfigurations: input.clientConfigurations,
+                organizationId: input.organization,
+            },
+        });
+
+        this.logger.info(`Triggered tenant client creation for ${tenant.id}`);
+        return tenant;
+    }
+}
+```
+
+### 8.2 Trigger from GraphQL Resolver
+
+```typescript
+import { CommonType } from '@common-stack/core';
+import { WorkflowNamespace } from 'common/server';
+
+export const createResolversFunc = (container: Container) => ({
+    Mutation: {
+        createProject: async (_, { input }, context) => {
+            const inngestClient = container.get(CommonType.INNGEST_CLIENT);
+            const projectService = container.get(SERVER_TYPES.ProjectService);
+
+            // Create project
+            const project = await projectService.create(input);
+
+            // Trigger background workflow
+            await inngestClient.send({
+                name: WorkflowNamespace.PROJECT_MGMT_SETUP_EVENT,
+                data: {
+                    projectId: project.id,
+                    userId: context.userId,
+                    config: input.config,
+                },
+            });
+
+            return project;
+        },
+    },
+});
+```
+
+### 8.3 Send Multiple Events
+
+```typescript
+// Send multiple events in parallel
+await Promise.all([
+    this.inngestClient.send({
+        name: WorkflowNamespace.NOTIFY_ADMIN_EVENT,
+        data: { entityId, type: 'created' },
+    }),
+    this.inngestClient.send({
+        name: WorkflowNamespace.AUDIT_LOG_EVENT,
+        data: { entityId, action: 'create', userId },
+    }),
+    this.inngestClient.send({
+        name: WorkflowNamespace.SYNC_EXTERNAL_EVENT,
+        data: { entityId },
+    }),
+]);
+```
+
+---
+
+## 9. Best Practices
+
+### 9.1 Namespace Consistency
+
+```typescript
+// ✅ CORRECT: Use WorkflowNamespace constants everywhere
+inngest.createFunction(
+    { id: WorkflowNamespace.TENANT_MGMT_CREATE_TENANT },
+    { event: WorkflowNamespace.TENANT_MGMT_CREATE_TENANT_EVENT },
+    async ({ event, step }) => {
+        /* ... */
+    },
+);
+
+// ❌ WRONG: Never hardcode event names
+inngest.createFunction(
+    { id: 'tenant-create' }, // ❌ Hardcoded
+    { event: 'tenant.create' }, // ❌ Hardcoded
+    async ({ event, step }) => {
+        /* ... */
+    },
+);
+
+// ❌ WRONG: Never mix namespace systems
+inngest.createFunction(
+    { id: WorkflowNamespace.TENANT_MGMT_CREATE_TENANT },
+    { event: LEGACY_EVENTS.CREATE_TENANT }, // ❌ Mixed systems
+    async ({ event, step }) => {
+        /* ... */
+    },
+);
+```
+
+### 9.2 Error Handling
+
+```typescript
+export const robustFunction = (container: Container, inngest: Inngest) =>
+    inngest.createFunction(
+        {
+            id: WorkflowNamespace.ROBUST_FUNCTION,
+            retries: 5, // Configure retries
+            onFailure: async ({ error, event }) => {
+                // Handle final failure
+                const logger = container.get('Logger');
+                logger.error('Function failed after all retries', {
+                    error,
+                    eventData: event.data,
+                });
+            },
+        },
+        { event: WorkflowNamespace.ROBUST_FUNCTION_EVENT },
+        async ({ event, step }) => {
+            try {
+                const result = await step.run('risky-operation', async () => {
+                    // Operation that might fail
+                    return await riskyOperation();
+                });
+                return { success: true, result };
+            } catch (error) {
+                // Log but rethrow to trigger retry
+                const logger = container.get('Logger');
+                logger.warn('Operation failed, will retry', { error });
+                throw error;
+            }
+        },
+    );
+```
+
+### 9.3 Data Structure Preservation
+
+```typescript
+// ✅ CORRECT: Preserve expected data structure
+await this.inngestClient.send({
+    name: WorkflowNamespace.TENANT_MGMT_DELETE_TENANT_EVENT,
+    data: {
+        clientConfiguration: [secretKey], // Function expects array
+    },
+});
+
+// ❌ WRONG: Breaking expected data structure
+await this.inngestClient.send({
+    name: WorkflowNamespace.TENANT_MGMT_DELETE_TENANT_EVENT,
+    data: {
+        tenantId, // ❌ Function doesn't expect this
+    },
+});
+```
+
+### 9.4 Step Naming
+
+```typescript
+// ✅ CORRECT: Descriptive step names
+await step.run('fetch-user-from-database', async () => {
+    /* ... */
+});
+await step.run('validate-payment-details', async () => {
+    /* ... */
+});
+await step.run('send-confirmation-email', async () => {
+    /* ... */
+});
+
+// ❌ WRONG: Vague step names
+await step.run('step1', async () => {
+    /* ... */
+});
+await step.run('do-stuff', async () => {
+    /* ... */
+});
+```
+
+### 9.5 Function Organization
+
+```typescript
+// functions.ts - Keep the factory clean and organized
+export const inngestFunctionsFactory = (args: { container: Container; inngest: Inngest }) => [
+    // Group 1: CRUD Operations
+    createEntityFunction(args.container, args.inngest),
+    updateEntityFunction(args.container, args.inngest),
+    deleteEntityFunction(args.container, args.inngest),
+
+    // Group 2: Workflows
+    mainWorkflowFunction(args.container, args.inngest),
+    setupWorkflowFunction(args.container, args.inngest),
+
+    // Group 3: Utility Functions
+    syncExternalFunction(args.container, args.inngest),
+    cleanupFunction(args.inngest),
+];
+```
+
+---
+
+## 10. Complete Examples
+
+### 10.1 Complete Module Setup
+
+#### Step 1: WorkflowNamespace Template
+
+**File**: `src/modules/order/templates/constants/WorkflowNamespace.ts.template`
+
+```typescript
+export const WorkflowNamespace = {
+    // Order Management - Function IDs
+    ORDER_MGMT_MAIN_WORKFLOW: 'order-mgmt-main-workflow',
+    ORDER_MGMT_CREATE_ORDER: 'order-mgmt-create-order',
+    ORDER_MGMT_PROCESS_PAYMENT: 'order-mgmt-process-payment',
+    ORDER_MGMT_SEND_CONFIRMATION: 'order-mgmt-send-confirmation',
+    ORDER_MGMT_UPDATE_INVENTORY: 'order-mgmt-update-inventory',
+
+    // Order Management - Trigger Events
+    ORDER_MGMT_MAIN_EVENT: 'order-mgmt-main-workflow/trigger',
+    ORDER_MGMT_CREATE_ORDER_EVENT: 'order-mgmt/create-order-trigger',
+    ORDER_MGMT_PROCESS_PAYMENT_EVENT: 'order-mgmt/process-payment-trigger',
+    ORDER_MGMT_SEND_CONFIRMATION_EVENT: 'order-mgmt/send-confirmation-trigger',
+    ORDER_MGMT_UPDATE_INVENTORY_EVENT: 'order-mgmt/update-inventory-trigger',
+
+    // Order Management - Result Events
+    ORDER_MGMT_ORDER_CREATED: 'order-mgmt/order-created',
+    ORDER_MGMT_PAYMENT_PROCESSED: 'order-mgmt/payment-processed',
+    ORDER_MGMT_ORDER_COMPLETED: 'order-mgmt/order-completed',
+};
+```
+
+#### Step 2: Individual Functions
+
+**File**: `src/modules/order/inngest/createOrderFunction.ts`
+
+```typescript
+import { Container } from 'inversify';
+import { Inngest } from 'inngest';
+import { WorkflowNamespace, SERVER_TYPES, IOrderService } from 'common/server';
+
+export const createOrderFunction = (container: Container, inngest: Inngest) =>
+    inngest.createFunction(
+        {
+            id: WorkflowNamespace.ORDER_MGMT_CREATE_ORDER,
+            name: 'Create Order',
+        },
+        {
+            event: WorkflowNamespace.ORDER_MGMT_CREATE_ORDER_EVENT,
+        },
+        async ({ event, step }) => {
+            const { userId, items, shippingAddress } = event.data;
+
+            const order = await step.run('create-order-record', async () => {
+                const orderService = container.get<IOrderService>(SERVER_TYPES.OrderService);
+                return orderService.create({
+                    userId,
+                    items,
+                    shippingAddress,
+                    status: 'pending',
+                });
+            });
+
+            await step.run('reserve-inventory', async () => {
+                const inventoryService = container.get(SERVER_TYPES.InventoryService);
+                for (const item of items) {
+                    await inventoryService.reserve(item.productId, item.quantity);
+                }
+            });
+
+            return {
+                orderId: order.id,
+                status: 'created',
+                total: order.total,
+            };
+        },
+    );
+```
+
+**File**: `src/modules/order/inngest/processPaymentFunction.ts`
+
+```typescript
+import { Container } from 'inversify';
+import { Inngest } from 'inngest';
+import { WorkflowNamespace, SERVER_TYPES } from 'common/server';
+
+export const processPaymentFunction = (container: Container, inngest: Inngest) =>
+    inngest.createFunction(
+        {
+            id: WorkflowNamespace.ORDER_MGMT_PROCESS_PAYMENT,
+            name: 'Process Payment',
+            retries: 3,
+        },
+        {
+            event: WorkflowNamespace.ORDER_MGMT_PROCESS_PAYMENT_EVENT,
+        },
+        async ({ event, step }) => {
+            const { orderId, paymentDetails } = event.data;
+
+            const paymentResult = await step.run('charge-payment', async () => {
+                const paymentService = container.get(SERVER_TYPES.PaymentService);
+                return paymentService.charge(orderId, paymentDetails);
+            });
+
+            await step.run('update-order-status', async () => {
+                const orderService = container.get(SERVER_TYPES.OrderService);
+                await orderService.updateStatus(orderId, 'paid');
+            });
+
+            return {
+                orderId,
+                paymentId: paymentResult.id,
+                status: 'payment-processed',
+            };
+        },
+    );
+```
+
+#### Step 3: Orchestrator Workflow
+
+**File**: `src/modules/order/inngest/mainWorkflow.ts`
+
+```typescript
+import { Container } from 'inversify';
+import { Inngest } from 'inngest';
+import { WorkflowNamespace } from 'common/server';
+import { createOrderFunction } from './createOrderFunction';
+import { processPaymentFunction } from './processPaymentFunction';
+import { sendConfirmationFunction } from './sendConfirmationFunction';
+
+export const orderMainWorkflow = (container: Container, inngest: Inngest) =>
+    inngest.createFunction(
+        {
+            id: WorkflowNamespace.ORDER_MGMT_MAIN_WORKFLOW,
+            name: 'Order Processing Workflow',
+        },
+        {
+            event: WorkflowNamespace.ORDER_MGMT_MAIN_EVENT,
+        },
+        async ({ event, step }) => {
+            const { userId, items, shippingAddress, paymentDetails } = event.data;
+
+            // Step 1: Create the order
+            const orderResult = await step.invoke(WorkflowNamespace.ORDER_MGMT_CREATE_ORDER, {
+                function: createOrderFunction(container, inngest),
+                data: { userId, items, shippingAddress },
+            });
+
+            // Step 2: Process payment
+            const paymentResult = await step.invoke(WorkflowNamespace.ORDER_MGMT_PROCESS_PAYMENT, {
+                function: processPaymentFunction(container, inngest),
+                data: {
+                    orderId: orderResult.orderId,
+                    paymentDetails,
+                },
+            });
+
+            // Step 3: Send confirmation
+            const confirmationResult = await step.invoke(WorkflowNamespace.ORDER_MGMT_SEND_CONFIRMATION, {
+                function: sendConfirmationFunction(container, inngest),
+                data: {
+                    orderId: orderResult.orderId,
+                    userId,
+                    total: orderResult.total,
+                },
+            });
+
+            return {
+                status: 'workflow-completed',
+                orderId: orderResult.orderId,
+                paymentId: paymentResult.paymentId,
+                confirmationSent: confirmationResult.sent,
+            };
+        },
+    );
+```
+
+#### Step 4: Functions Factory
+
+**File**: `src/modules/order/inngest/functions.ts`
+
+```typescript
+import { Container } from 'inversify';
+import { Inngest } from 'inngest';
+import { createOrderFunction } from './createOrderFunction';
+import { processPaymentFunction } from './processPaymentFunction';
+import { sendConfirmationFunction } from './sendConfirmationFunction';
+import { updateInventoryFunction } from './updateInventoryFunction';
+import { orderMainWorkflow } from './mainWorkflow';
+
+export const inngestFunctionsFactory = (args: { container: Container; inngest: Inngest }) => [
+    // Individual functions
+    createOrderFunction(args.container, args.inngest),
+    processPaymentFunction(args.container, args.inngest),
+    sendConfirmationFunction(args.container, args.inngest),
+    updateInventoryFunction(args.container, args.inngest),
+
+    // Main orchestrator
+    orderMainWorkflow(args.container, args.inngest),
+];
+```
+
+**File**: `src/modules/order/inngest/index.ts`
+
+```typescript
+export { inngestFunctionsFactory } from './functions';
+```
+
+#### Step 5: Feature Module
+
+**File**: `src/modules/order/module.ts`
+
+```typescript
+import { Feature } from '@common-stack/server-core';
+import { inngestFunctionsFactory } from './inngest';
+import { orderContainerModule } from './container';
+import { schema, resolver } from './graphql';
+
+export default new Feature({
+    schema,
+    createResolversFunc: resolver,
+    createContainerFunc: [orderContainerModule],
+
+    // Register Inngest functions
+    inngestFunctions: [({ container, inngest }) => inngestFunctionsFactory({ container, inngest })],
+});
+```
+
+#### Step 6: Service Integration
+
+**File**: `src/modules/order/services/OrderService.ts`
+
+```typescript
+import { injectable, inject } from 'inversify';
+import type { Inngest } from 'inngest';
+import { CommonType } from '@common-stack/core';
+import { WorkflowNamespace, SERVER_TYPES } from 'common/server';
+
+@injectable()
+export class OrderService implements IOrderService {
+    constructor(
+        @inject(SERVER_TYPES.OrderRepository)
+        private readonly orderRepository: IOrderRepository,
+
+        @inject(CommonType.INNGEST_CLIENT)
+        private readonly inngestClient: Inngest,
+
+        @inject('Logger')
+        private readonly logger: Logger,
+    ) {}
+
+    async createOrder(input: ICreateOrderInput): Promise<IOrderResponse> {
+        // Trigger the main workflow
+        const { id: eventId } = await this.inngestClient.send({
+            name: WorkflowNamespace.ORDER_MGMT_MAIN_EVENT,
+            data: {
+                userId: input.userId,
+                items: input.items,
+                shippingAddress: input.shippingAddress,
+                paymentDetails: input.paymentDetails,
+            },
+        });
+
+        this.logger.info(`Order workflow triggered: ${eventId}`);
+
+        return {
+            status: 'processing',
+            workflowId: eventId,
+            message: 'Order is being processed',
+        };
+    }
+}
+```
+
+---
+
+## 11. Troubleshooting
+
+### 11.1 Common Issues
+
+#### Functions Not Loading
+
+```bash
+# Check if template is registered in package.json
+cat packages-modules/{module}/server/package.json | grep WorkflowNamespace
+
+# Regenerate common module
+yarn regenerateGraphql && yarn generateGraphql
+
+# Verify build
+lerna run build --scope=common
+```
+
+#### Import Errors for WorkflowNamespace
+
+```typescript
+// ✅ CORRECT import path
+import { WorkflowNamespace } from 'common/server';
+
+// ❌ WRONG - Don't import from common directly for server constants
+import { WorkflowNamespace } from 'common';
+```
+
+#### Container Service Not Found
+
+```typescript
+// Ensure service is bound in container module
+container.bind(SERVER_TYPES.MyService).to(MyService);
+
+// Check binding identifier matches
+const service = container.get<IMyService>(SERVER_TYPES.MyService);
+```
+
+#### Events Not Triggering
+
+1. Check Inngest dev server is running
+2. Verify event name matches exactly
+3. Check `/api/inngest` endpoint is registered
+4. Review server logs for errors
+
+### 11.2 Debug Commands
+
+```bash
+# Check common module build
+lerna run build --scope=common
+
+# Validate TypeScript
+npx tsc --noEmit
+
+# Check for lint errors
+npm run lint
+
+# Start Inngest dev server
+npx inngest-cli dev
+
+# Check registered functions
+curl http://localhost:3000/api/inngest
+```
+
+### 11.3 Validation Checklist
+
+Before deploying:
+
+- [ ] WorkflowNamespace template created in correct location
+- [ ] Template registered in `package.json` under `cdecode.common.constants`
+- [ ] Common module regenerated (`yarn regenerateGraphql && yarn generateGraphql`)
+- [ ] Function factory created and exports array of functions
+- [ ] Factory exported from `inngest/index.ts`
+- [ ] Feature module updated with `inngestFunctions` array
+- [ ] All event names use `WorkflowNamespace` constants
+- [ ] No TypeScript/ESLint errors
+- [ ] Functions tested in Inngest dev server
+
+---
+
+## Quick Reference Card
+
+### Create New Function Checklist
+
+1. **Add to WorkflowNamespace template**:
+    - Function ID: `{PREFIX}_ACTION: '{prefix}-action'`
+    - Event: `{PREFIX}_ACTION_EVENT: '{prefix}/action-trigger'`
+
+2. **Create function file**: `{action}Function.ts`
+
+3. **Add to factory**: `functions.ts`
+
+4. **Regenerate**: `yarn regenerateGraphql && yarn generateGraphql`
+
+### Function Signature
+
+```typescript
+// Without container
+export const fn = (inngest: Inngest) => inngest.createFunction(...);
+
+// With container
+export const fn = (container: Container, inngest: Inngest) => inngest.createFunction(...);
+```
+
+### Feature Registration
+
+```typescript
+inngestFunctions: [({ container, inngest }) => inngestFunctionsFactory({ container, inngest })];
+```
+
+### Trigger from Service
+
+```typescript
+await this.inngestClient.send({
+    name: WorkflowNamespace.EVENT_NAME,
+    data: {
+        /* your data */
+    },
+});
+```
+
+---
+
+**Version**: 1.0.0  
+**Last Updated**: December 2024  
+**Maintainer**: AdminIDE Stack Team