@cdmbase/wiki-browser 12.0.18-alpha.10

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

@@ -0,0 +1,384 @@
+# LLM Template: Workflow Namespace Management
+
+## Overview
+
+This template provides guidelines for AI/LLM assistants (like GPT) to follow when creating, updating, or managing workflow namespaces in the AdminIDE Stack project.
+
+## Namespace Naming Convention
+
+### Pattern: `{MODULE}_{FUNCTION_TYPE}_{SPECIFIC_ACTION}`
+
+### Module Prefixes:
+
+- `TENANT_MGMT` - Tenant Management operations
+- `USER_AUTH` - User Authentication operations
+- `FORM_BUILDER` - Form Builder operations
+- `PROJECT_MGMT` - Project Management operations
+- `BILLING` - Billing and payment operations
+- `NOTIFICATION` - Notification services
+- `INTEGRATION` - Third-party integrations
+
+### Function Types:
+
+- `MAIN_WORKFLOW` - Primary orchestrating workflow
+- `CREATE` - Creation operations
+- `UPDATE` - Update operations
+- `DELETE` - Deletion operations
+- `SYNC` - Synchronization operations
+- `VALIDATE` - Validation operations
+
+### Example Namespace Structure:
+
+```typescript
+export const WorkflowNamespace = {
+    // Tenant Management Module - Auth0/Keycloak
+    TENANT_MGMT_MAIN_WORKFLOW: 'tenant-mgmt-auth0-main-workflow',
+    TENANT_MGMT_MAIN_EVENT: 'tenant-mgmt-auth0-main-workflow/trigger',
+    TENANT_MGMT_CREATE_TENANT: 'tenant-mgmt-auth0-create-tenant',
+    TENANT_MGMT_CREATE_CLIENT: 'tenant-mgmt-auth0-create-client',
+    TENANT_MGMT_CREATE_REALM: 'tenant-mgmt-auth0-create-realm',
+    TENANT_MGMT_DELETE_TENANT: 'tenant-mgmt-auth0-delete-tenant',
+    TENANT_MGMT_UPDATE_TENANT: 'tenant-mgmt-auth0-update-tenant',
+
+    // Tenant Management Events
+    TENANT_MGMT_TENANT_CREATED: 'tenant-mgmt-auth0/tenant-created',
+    TENANT_MGMT_CLIENT_CREATED: 'tenant-mgmt-auth0/client-created',
+    TENANT_MGMT_REALM_CREATED: 'tenant-mgmt-auth0/realm-created',
+    TENANT_MGMT_TENANT_DELETED: 'tenant-mgmt-auth0/tenant-deleted',
+};
+```
+
+## Implementation Steps for New Modules
+
+### 1. Create Template File
+
+- **Location**: `packages-modules/{module-name}/server/src/modules/{feature}/templates/constants/WorkflowNamespace.ts.template`
+- **Content**: Follow the namespace pattern above
+- **Comments**: Include module description and grouping
+
+### 2. Update Package.json
+
+- **File**: `packages-modules/{module-name}/server/package.json`
+- **Section**: Add template path to `cdecode.common.constants` array
+- **Format**: `"./${libDir}/modules/{feature}/templates/constants/WorkflowNamespace.ts.template"`
+
+### 3. Regenerate Common Module
+
+```bash
+yarn regenerateGraphql && yarn generateGraphql
+```
+
+### 4. Update Function Files
+
+- Import `WorkflowNamespace` from `'common/server'`
+- Update function IDs to use namespace constants
+- **IMPORTANT**: Update event triggers to use namespace constants (not hardcoded event names)
+- Update step.invoke calls to use namespace constants
+
+## Service Layer Integration
+
+### Using Inngest in Service Classes
+
+When triggering Inngest workflows from service classes, use dependency injection for the Inngest client:
+
+**Import and Inject:**
+
+```typescript
+import { WorkflowNamespace } from 'common/server';
+import type { Inngest } from 'inngest';
+import { CommonType } from '@common-stack/core';
+
+@injectable()
+export class TenantService extends BaseService2<ITenantModel> implements ITenantService {
+    constructor(
+        @inject(SERVER_TYPES.TenantRepository)
+        private readonly tenantRepository: ITenantRepository,
+        @inject(CommonType.INNGEST_CLIENT)
+        private readonly inngestClient: Inngest,
+        @inject('Logger')
+        logger: Logger,
+    ) {
+        super(tenantRepository);
+        this.logger = logger.child({ className: 'TenantService' });
+    }
+}
+```
+
+**Trigger Events from Service Methods:**
+
+```typescript
+async createTenant(input: ICreateTenantInput): Promise<ITenantCreationResponse> {
+    // Business logic...
+    const tenant = await this.create(tenantData);
+
+    // Trigger workflow using injected client
+    if (input.clientConfigurations && input.clientConfigurations.length > 0) {
+        await this.inngestClient.send({
+            name: WorkflowNamespace.TENANT_MGMT_CREATE_CLIENT_EVENT,
+            data: {
+                tenantId: tenant.id,
+                clientConfigurations: input.clientConfigurations,
+            },
+        });
+    }
+
+    return tenant;
+}
+
+async revokeSecretKey(tenantId: string, keyId: string): Promise<string> {
+    // Business logic...
+    const secretKey = clientConfigs.find((key) => key._id.toString() === keyId);
+
+    // Trigger cleanup workflow
+    await this.inngestClient.send({
+        name: WorkflowNamespace.TENANT_MGMT_DELETE_TENANT_EVENT,
+        data: {
+            clientConfiguration: [secretKey], // Pass specific config to delete
+        },
+    });
+
+    return keyId;
+}
+```
+
+**Key Patterns:**
+
+- ✅ Use `this.inngestClient.send()` in service classes
+- ✅ Always use `WorkflowNamespace` constants for event names
+- ✅ Pass relevant data that the workflow function expects
+- ✅ Use proper TypeScript types for Inngest client injection
+
+## File Structure Requirements
+
+```
+packages-modules/{module-name}/server/
+├── package.json (updated with template reference)
+├── src/modules/{feature}/
+│   ├── templates/constants/
+│   │   └── WorkflowNamespace.ts.template
+│   └── inngest/
+│       ├── functions.ts (main orchestrator)
+│       ├── {action}Function.ts (individual functions)
+│       └── ...
+└── docs/
+    └── LLM_WORKFLOW_NAMESPACE_TEMPLATE.md (this file)
+```
+
+## Best Practices
+
+### 1. Namespace Uniqueness
+
+- Always use module-specific prefixes
+- Include technology stack in naming (e.g., auth0, keycloak)
+- Avoid generic names like "create-tenant"
+
+### 2. Event Naming
+
+- Use forward slashes for event hierarchies: `module/action`
+- **CRITICAL**: Always use namespace constants for event triggers, never hardcode event names
+- **Main Workflow Triggers** (`_EVENT` with `/trigger` suffix): Main orchestrating workflows
+- **Function Triggers** (`_EVENT` with `/action-trigger` suffix): Individual function triggers
+- **Result Events** (`_SUCCESS`, `_FAILED`, `_CREATED`): What functions emit when complete (optional)
+- All trigger events end with `_EVENT` suffix for consistency
+
+### 3. Function Organization
+
+- Main workflow orchestrates other functions
+- Individual functions handle specific operations
+- Use descriptive function names matching namespace
+
+### 4. Error Handling
+
+- Always check for TypeScript/ESLint errors after updates
+- Ensure proper imports and exports
+- Validate namespace constants are accessible
+
+## Template Validation Checklist
+
+Before submitting changes:
+
+- [ ] Template file created in correct location
+- [ ] Package.json updated with template reference
+- [ ] Common module regenerated successfully
+- [ ] All function files updated with new namespace
+- [ ] No TypeScript/ESLint errors
+- [ ] Namespace follows naming convention
+- [ ] No conflicts with existing namespaces
+
+## Conflict Resolution
+
+### Naming Conflicts
+
+- Check existing namespaces in `packages/common/src/constants/WorkflowNamespace.ts`
+- Use more specific module prefixes if needed
+- Include version numbers for major changes: `V2_TENANT_MGMT_`
+
+### Template Generation Issues
+
+- Manually update common module if regeneration fails
+- Ensure template syntax is correct TypeScript
+- Check for missing commas or syntax errors
+
+## Example Implementation
+
+### 1. Template File (`WorkflowNamespace.ts.template`):
+
+```typescript
+export const WorkflowNamespace = {
+    // User Authentication Module - JWT/OAuth Function IDs
+    USER_AUTH_MAIN_WORKFLOW: 'user-auth-jwt-main-workflow',
+    USER_AUTH_LOGIN: 'user-auth-jwt-login',
+    USER_AUTH_LOGOUT: 'user-auth-jwt-logout',
+    USER_AUTH_REFRESH_TOKEN: 'user-auth-jwt-refresh-token',
+
+    // User Authentication Trigger Events (what functions listen for from Inngest)
+    USER_AUTH_MAIN_EVENT: 'user-auth-jwt-main-workflow/trigger', // 🎯 Main workflow trigger
+    USER_AUTH_LOGIN_EVENT: 'user-auth-jwt/login-trigger', // 🎯 Login function trigger
+    USER_AUTH_LOGOUT_EVENT: 'user-auth-jwt/logout-trigger', // 🎯 Logout function trigger
+    USER_AUTH_REFRESH_EVENT: 'user-auth-jwt/refresh-trigger', // 🎯 Refresh function trigger
+
+    // User Authentication Result Events (what functions emit when complete - optional)
+    USER_AUTH_LOGIN_SUCCESS: 'user-auth-jwt/login-success',
+    USER_AUTH_LOGIN_FAILED: 'user-auth-jwt/login-failed',
+    USER_AUTH_TOKEN_REFRESHED: 'user-auth-jwt/token-refreshed',
+    USER_AUTH_LOGOUT_SUCCESS: 'user-auth-jwt/logout-success',
+};
+```
+
+### 2. Package.json Update:
+
+```json
+{
+    "cdecode": {
+        "common": {
+            "constants": ["./${libDir}/modules/user-auth/templates/constants/WorkflowNamespace.ts.template"]
+        }
+    }
+}
+```
+
+### 3. Function Implementation:
+
+```typescript
+import { WorkflowNamespace } from 'common/server';
+
+export const loginFunction = (inngest: Inngest) =>
+    inngest.createFunction(
+        { id: WorkflowNamespace.USER_AUTH_LOGIN },
+        { event: WorkflowNamespace.USER_AUTH_LOGIN_EVENT }, // 🎯 TRIGGER event (what this function listens for)
+        async ({ event, step }) => {
+            // Implementation logic here
+            const result = await step.run('authenticate-user', async () => {
+                // Auth logic
+                return { success: true, userId: '123' };
+            });
+
+            // Optionally emit result events (not shown here, but could send to other systems)
+            return result;
+        },
+    );
+
+// Main workflow example
+export const userAuthMainWorkflow = (inngest: Inngest) =>
+    inngest.createFunction(
+        { id: WorkflowNamespace.USER_AUTH_MAIN_WORKFLOW },
+        { event: WorkflowNamespace.USER_AUTH_MAIN_EVENT }, // 🎯 MAIN workflow trigger event
+        async ({ event, step }) => {
+            // Trigger login step using step.invoke
+            await step.invoke(WorkflowNamespace.USER_AUTH_LOGIN, {
+                function: loginFunction(inngest),
+                data: event.data,
+            });
+        },
+    );
+```
+
+## Troubleshooting
+
+### Common Issues:
+
+1. **Build Failures**: Check for syntax errors in template
+2. **Import Errors**: Ensure common module is built after regeneration
+3. **Duplicate Keys**: Avoid naming conflicts across modules
+4. **Missing Constants**: Verify template is referenced in package.json
+5. **Mixed Event Systems**: ❌ NEVER mix WorkflowNamespace constants with old TENANT_EVENTS constants
+
+### ⚠️ Critical: Event Trigger Pattern
+
+**WRONG** ❌:
+
+```typescript
+inngest.createFunction(
+    { id: WorkflowNamespace.TENANT_MGMT_MAIN_WORKFLOW },
+    { event: TENANT_EVENTS.GENERATED_INVOKER_FUNCTION }, // ❌ Mixed systems
+    async ({ event, step }) => {
+        /* ... */
+    },
+);
+```
+
+**CORRECT** ✅:
+
+```typescript
+inngest.createFunction(
+    { id: WorkflowNamespace.TENANT_MGMT_MAIN_WORKFLOW },
+    { event: WorkflowNamespace.TENANT_MGMT_MAIN_EVENT }, // ✅ Consistent namespace
+    async ({ event, step }) => {
+        /* ... */
+    },
+);
+```
+
+### ⚠️ Critical: Data Structure Preservation
+
+When updating event triggers, **NEVER** change the data structure that workflow functions expect:
+
+**WRONG** ❌:
+
+```typescript
+// Original workflow expects clientConfiguration array
+await this.inngestClient.send({
+    name: WorkflowNamespace.TENANT_MGMT_DELETE_TENANT_EVENT,
+    data: {
+        tenantId, // ❌ Wrong! Function expects clientConfiguration
+    },
+});
+```
+
+**CORRECT** ✅:
+
+```typescript
+// Maintain the expected data structure
+await this.inngestClient.send({
+    name: WorkflowNamespace.TENANT_MGMT_DELETE_TENANT_EVENT,
+    data: {
+        clientConfiguration: [secretKey], // ✅ Correct! Matches function expectation
+    },
+});
+```
+
+**Validation Steps:**
+
+1. Check the target workflow function's `event.data` usage
+2. Ensure data structure matches what the function expects
+3. Only update event names to use namespace constants
+4. Preserve all data payloads exactly as they were
+
+### Debug Commands:
+
+```bash
+# Check common module build
+lerna run build --scope=common
+
+# Validate TypeScript
+npx tsc --noEmit
+
+# Check for lint errors
+npm run lint
+```
+
+---
+
+**Last Updated**: September 18, 2025
+**Version**: 1.0.0
+**Maintainer**: AdminIDE Stack Team