@cdmbase/wiki-browser 12.0.18-alpha.5

package/lib/templates/content/docs/LLM/backend-proxies-services-llm.md

@@ -0,0 +1,2687 @@
+# LLM Proxy Service Generator Prompt
+
+## Quick Start Prompt
+
+Copy and paste this prompt to an LLM to generate a new proxy service:
+
+---
+
+## 🤖 PROMPT START
+
+I need you to create a Proxy Service AND Moleculer Service for the AdminIDE Stack following the **modern auto-generation pattern**.
+
+### 🎯 Recommended Approach Summary
+
+**ALWAYS use auto-generation for both Moleculer services and Proxy services (Pattern 1):**
+
+1. **Moleculer Service**: Use `Moleculer.generateActionsAndEvents<IService>(service)`
+    - 30 lines instead of 200+
+    - Auto-detects all methods including parent class methods
+    - Auto-registers event handlers from decorators
+    - **Auto-derive topic** from `ServiceSchemas.topic` - no enum imports needed!
+    - **No configuration needed** - just one line to generate everything
+
+2. **Proxy Service**: Use `generateProxyMethods<IService>(this, ServiceSchemas, broker, logger)`
+    - 40 lines instead of 120+
+    - Auto-generates all proxy methods
+    - Correct parameter ordering guaranteed
+    - **No manual `topic` property needed** - extracted automatically from `ServiceSchemas.topic`
+
+**Benefits**:
+
+- ✅ 90% less code
+- ✅ Zero boilerplate - no configuration needed
+- ✅ Type-safe with full TypeScript inference
+- ✅ Maintainable - add method once, available everywhere
+- ✅ No manual synchronization needed
+- ✅ **Zero dependencies** - topic auto-derived from class name, no enums needed
+
+**When to use optional configurations (Patterns 2-4):**
+
+- Pattern 2: Custom validation - RARE (~5% of cases)
+- Pattern 3: Manual overrides - VERY RARE (~1% of cases)
+- Pattern 4: Whitelist methods - RARE (~2% of cases)
+
+**For 99% of services, use Pattern 1 with zero configuration!**
+
+**Topic Convention (Auto-Generated & Minification-Safe)**:
+The topic is **automatically generated** in the service schemas and derived from the service interface name:
+
+```typescript
+// Auto-generated in service-schemas.ts (from IProjectService interface)
+export const ProjectServiceSchemas = {
+    /** Moleculer service topic/name - safe for minification */
+    topic: 'ProjectService' as const,
+    // ... method schemas
+};
+
+// In moleculer service - extract topic from schemas
+import { ProjectServiceSchemas } from 'common/server';
+const { topic } = ProjectServiceSchemas; // "ProjectService"
+
+// In proxy service - topic is automatically extracted by generateProxyMethods()
+// No manual topic property needed!
+```
+
+**Benefits**:
+
+- ✅ **Zero manual configuration** - topic auto-derived from interface name (e.g., `IProjectService` → `ProjectService`)
+- ✅ **Minification-safe** - stored as string constant in generated schemas
+- ✅ **Single source of truth** - schemas object contains both topic and validation
+- ✅ **No enum imports needed** - eliminates `MoleculerTopics` or `MoleculerServiceName` dependencies
+- ✅ **Type-safe** - `as const` provides literal type inference
+
+### Context
+
+This codebase uses a microservice architecture with Moleculer message broker. The architecture consists of THREE key components:
+
+1. **Service Interface**: Defines the contract (methods and types)
+2. **Actual Service Implementation**: Contains business logic
+3. **Moleculer Service**: Registers actions that delegate to the actual service
+4. **Proxy Service**: Used by clients to call methods via Moleculer broker
+
+**Important**: When creating services, you must create BOTH the Moleculer service AND the proxy service. They work together:
+
+**Important**: When creating services, you must create BOTH the Moleculer service AND the proxy service. They work together:
+
+- **Moleculer Service**: Lives on the server with business logic, exposes actions
+- **Proxy Service**: Lives on clients, calls Moleculer actions via broker
+
+### Files to Reference
+
+1. **Service Interface**: `packages/common/src/services/[ServiceName].ts`
+    - Contains the interface definition with all methods
+
+2. **Actual Service**: `packages-modules/[module-name]/server/src/services/[ServiceName].ts`
+    - Contains the actual implementation (for understanding method signatures)
+
+3. **Example Moleculer Services**:
+    - **Account Service**: `packages-modules/account-api/server/src/plugins/AccountMoleculerService.ts` (40+ actions)
+    - **Project Service**: `packages-modules/account-api/server/src/modules/project/plugins/ProjectMoleculerService.ts` (10+ actions)
+
+4. **Example Proxy Services** (choose based on complexity):
+    - Simple: `packages-modules/account-api/core/src/servers/services/ProjectProxyService.ts`
+    - Medium: `packages-modules/account-api/core/src/servers/services/TeamMicroservice.ts`
+    - Complex: `packages-modules/account-api/core/src/servers/services/AccountProxyService.ts` (40+ methods)
+
+5. **GraphQL Schema**: `packages-modules/[module-name]/server/src/graphql/schema/service.graphql`
+    - Contains service action enums
+
+### Task 0: Service Schema Generation (Automatic)
+
+**AUTO-GENERATED**: Service schemas with topics are automatically generated by running `yarn generateGraphql`.
+
+The schema generator (`@common-stack/server-core/lib/moleculer-generation/generateAllServiceSchemas.cjs`) automatically:
+
+- Scans all service interfaces (e.g., `IProjectService`)
+- Generates Zod validation schemas for each method
+- Auto-derives topic from interface name: `IProjectService` → `ProjectService`
+- Outputs to `packages/common/src/generated/service-schemas.ts`
+
+```typescript
+// Auto-generated in service-schemas.ts
+export const ProjectServiceSchemas = {
+    /** Moleculer service topic/name - safe for minification */
+    topic: 'ProjectService' as const,
+    createProject: z.object({
+        /* ... */
+    }),
+    getProject: z.object({
+        /* ... */
+    }),
+    // ... all other methods
+};
+```
+
+**Benefits of auto-generation**:
+
+- ✅ **Zero manual work**: Topic and schemas generated from TypeScript interfaces
+- ✅ **Minification-safe**: Topic stored as string constant
+- ✅ **Type-safe**: Full TypeScript inference with `as const`
+- ✅ **Always in sync**: Regenerate after interface changes with `yarn generateGraphql`
+- ✅ **Single source of truth**: Interface defines everything (methods, params, topic)
+
+### Task 1: Update GraphQL Schema
+
+Add all missing actions to the `[ServiceName]ServiceAction` enum in `service.graphql`:
+
+```graphql
+enum [ServiceName]ServiceAction {
+    # Read operations (get*, find*, search*, etc.)
+    getItem
+    findItems
+
+    # Create operations (create*, add*, generate*, etc.)
+    createItem
+    addItem
+
+    # Update operations (update*, modify*, change*, set*, etc.)
+    updateItem
+    changeStatus
+
+    # Delete operations (delete*, remove*, archive*, etc.)
+    deleteItem
+    removeItem
+
+    # Event handlers (on* methods) - MUST start with 'on' prefix
+    onItemCreated
+    onItemDeleted
+    onItemUpdated
+    onUserRemoved
+}
+```
+
+**Rules for enum values**:
+
+- Use camelCase (first letter lowercase)
+- Match method names from the interface
+- Group by operation type
+- Include all interface methods except lifecycle methods like `dispose()`
+- **Event handlers MUST use `on` prefix** (e.g., `onAccountDeleted`, `onPropertyCreated`)
+- Event names should match the pattern: `OnEventName` → `onEventName`
+
+### Task 2: Create Moleculer Service
+
+**CRITICAL**: The Moleculer service must be created FIRST. This is where the actual work happens.
+
+**STRICT FILE NAMING CONVENTION:**
+
+✅ **CORRECT**: Use PascalCase matching the class name
+
+- File: `AccountMoleculerService.ts` → Class: `AccountMoleculerService`
+- File: `ProjectMoleculerService.ts` → Class: `ProjectMoleculerService`
+- File: `TeamMoleculerService.ts` → Class: `TeamMoleculerService`
+
+❌ **WRONG**: Do NOT use kebab-case or snake-case
+
+- ❌ `accounts-moleculer-service.ts` (kebab-case)
+- ❌ `account-moleculer-service.ts` (kebab-case)
+- ❌ `accounts_moleculer_service.ts` (snake-case)
+
+**File Location Patterns:**
+
+Pattern 1 (Main module):
+`packages-modules/[module-name]/server/src/plugins/[ServiceName]MoleculerService.ts`
+
+Examples:
+
+- `packages-modules/account-api/server/src/plugins/AccountMoleculerService.ts`
+- `packages-modules/billing-api/server/src/plugins/InvoiceMoleculerService.ts`
+
+Pattern 2 (Sub-module):
+`packages-modules/[module-name]/server/src/modules/[service]/plugins/[ServiceName]MoleculerService.ts`
+
+Examples:
+
+- `packages-modules/account-api/server/src/modules/project/plugins/ProjectMoleculerService.ts`
+- `packages-modules/account-api/server/src/modules/team/plugins/TeamMoleculerService.ts`
+
+**Naming Rules:**
+
+1. ✅ File name MUST match class name exactly
+2. ✅ Use PascalCase (first letter uppercase)
+3. ✅ Always end with `MoleculerService.ts`
+4. ✅ Service name comes first: `[ServiceName]MoleculerService`
+5. ❌ Never use kebab-case (dashes)
+6. ❌ Never use snake-case (underscores)
+7. ❌ Never use plural form (e.g., `AccountsMoleculerService` is wrong)
+
+---
+
+## 🎯 RECOMMENDED APPROACH: Auto-Generation
+
+**Use `Moleculer.generateActionsAndEvents()` from common package** - eliminates 90% of boilerplate code!
+
+**Quick Example:**
+
+```typescript
+import { Service, ServiceBroker } from 'moleculer';
+import { Container } from 'inversify';
+import { I[ServiceName]Service, [ServiceName]ServiceSchemas, SERVER_TYPES } from 'common/server';
+import { Moleculer, zodSchemasToMoleculer } from '@common-stack/codegen-zod';
+
+export class [ServiceName]MoleculerService extends Service {
+    constructor(broker: ServiceBroker, { container }: { container: Container }) {
+        super(broker);
+        // Get topic from auto-generated schemas
+        const { topic } = [ServiceName]ServiceSchemas;
+        const service = container.get<I[ServiceName]Service>(SERVER_TYPES.[ServiceName]Service);
+
+        // Convert Zod schemas to Moleculer param validation
+        const paramOverrides = zodSchemasToMoleculer([ServiceName]ServiceSchemas);
+
+        // ⚡ Auto-generate actions and events with validation
+        const { actions, events } = Moleculer.generateActionsAndEvents<I[ServiceName]Service>(service, {
+            paramOverrides,
+        });
+
+        this.parseServiceSchema({
+            name: topic,  // ✅ Auto-derived from interface name
+            actions,      // ✅ All methods (including parent class) with validation
+            events,       // ✅ All @Moleculer.EventHandler decorators
+        });
+    }
+}
+```
+
+**That's it! 30 lines instead of 200+**
+
+### 📊 Auto-Generation vs Manual Comparison
+
+| Feature                  | Auto-Generation                   | Manual                    |
+| ------------------------ | --------------------------------- | ------------------------- |
+| **Code Size**            | ~30 lines                         | ~200+ lines               |
+| **Parent Class Methods** | ✅ Automatic                      | ❌ Must copy each one     |
+| **Event Handlers**       | ✅ Auto-detected from decorators  | ❌ Must define each one   |
+| **Type Safety**          | ✅ Full TypeScript inference      | ⚠️ Manual typing required |
+| **Maintenance**          | ✅ Add method → auto-available    | ❌ Must update 3 places   |
+| **Parameter Validation** | ✅ Auto-generated from TypeScript | ✅ Explicit schemas       |
+| **Custom Logic**         | ⚠️ Requires Pattern 3 override    | ✅ Full control           |
+| **Best For**             | **ALL services (99% of cases)**   | Complex custom validation |
+
+**Recommendation**: **USE PATTERN 1 FOR ALL NEW SERVICES**. Add manual overrides (Pattern 2/3) only in rare cases where you need custom validation or logic.
+
+For detailed patterns, see sections below ⬇️
+
+---
+
+### ⚡ Auto-Generation from Common Package
+
+**IMPORTANT**: The common package (`packages/common/src/utils/typed-moleculer-service.ts`) provides powerful utilities to auto-generate actions and events from service classes.
+
+#### Primary Function (Use This):
+
+**`Moleculer.generateActionsAndEvents<TService>(service, config?)`**
+
+- Generates BOTH actions AND events from a single service instance
+- Actions: Generated from regular service methods
+- Events: Generated from methods decorated with `@Moleculer.EventHandler()`
+- Automatically excludes event handler methods from actions
+- **USE THIS FOR ALL SERVICES** (with or without event handlers)
+
+#### Alternative Function (Rarely Needed):
+
+**`Moleculer.generateAutoInferredActions<TService>(service, config?)`**
+
+- Automatically generates Moleculer actions from ALL service methods
+- Infers parameters from TypeScript function signatures
+- Traverses entire prototype chain to include inherited methods from parent classes
+- Excludes lifecycle methods (dispose) and base CRUD methods by default
+- Use this ONLY if you don't have event handlers and want slightly different behavior
+
+#### Auto-Generation Configuration (All Optional):
+
+```typescript
+type AutoInferredActionConfig<TService> = {
+    // Override param schemas for specific methods (OPTIONAL - Pattern 2)
+    paramOverrides?: Partial<{
+        [K in ServiceMethods<TService>]: Record<string, unknown>;
+    }>;
+
+    // Only include specific methods - whitelist (OPTIONAL - Pattern 4)
+    include?: Array<ServiceMethods<TService>>;
+
+    // Exclude specific methods - blacklist (OPTIONAL - Pattern 3)
+    exclude?: Array<ServiceMethods<TService>>;
+
+    // Map action names to different method names (OPTIONAL - Advanced)
+    actionToMethodMap?: Record<string, string>;
+
+    // Add custom Moleculer action properties (cache, visibility, etc.)
+    actionConfig?: Partial<{
+        [K in ServiceMethods<TService>]: {
+            cache?: boolean | object;
+            visibility?: 'public' | 'protected' | 'private';
+            [key: string]: unknown;
+        };
+    }>;
+};
+```
+
+#### Usage Patterns:
+
+**Pattern 1: Full Auto-Generation (USE THIS IN ALL CASES)**
+
+```typescript
+import { Moleculer } from '@common-stack/codegen-zod';
+
+export class [ServiceName]MoleculerService extends Service {
+    constructor(broker: ServiceBroker, { container }: { container: Container }) {
+        super(broker);
+        const [serviceName]Service = container.get<I[ServiceName]Service>(SERVER_TYPES.I[ServiceName]Service);
+
+        const { topic } = [ServiceName]ServiceSchemas;
+
+        // Auto-generate ALL actions and events
+        const { actions, events } = Moleculer.generateActionsAndEvents<I[ServiceName]Service>(
+            [serviceName]Service
+        );
+
+        this.parseServiceSchema({
+            name: topic,
+            actions,  // All service methods auto-generated
+            events,   // All @Moleculer.EventHandler methods auto-generated
+        });
+    }
+}
+```
+
+**Benefits:**
+
+- ✅ Simplest implementation - zero configuration needed
+- ✅ All methods automatically included (including parent class methods)
+- ✅ Event handlers automatically detected from `@Moleculer.EventHandler` decorators
+- ✅ Zero maintenance - add method to interface, it's automatically available
+- ✅ Type-safe with full TypeScript inference
+
+**When to use:** Use this pattern for **ALL new services** unless you have specific validation requirements (see Pattern 2 below).
+
+---
+
+**Pattern 2: Auto-Generation with Custom Validation (OPTIONAL - Only for Special Cases)**
+
+Use this pattern ONLY when you need custom Moleculer validation schemas that differ from the auto-generated ones.
+
+```typescript
+export class [ServiceName]MoleculerService extends Service {
+    constructor(broker: ServiceBroker, { container }: { container: Container }) {
+        super(broker);
+        const [serviceName]Service = container.get<I[ServiceName]Service>(SERVER_TYPES.I[ServiceName]Service);
+
+        const { topic } = [ServiceName]ServiceSchemas;
+
+        // Auto-generate with custom validation overrides
+        const { actions, events } = Moleculer.generateActionsAndEvents<I[ServiceName]Service>(
+            [serviceName]Service,
+            {
+                // Override param schemas for specific methods
+                paramOverrides: {
+                    findById: { id: 'string' },  // Add Moleculer validation
+                    updateItem: { id: 'string', input: 'object' },
+                }
+            }
+        );
+
+        this.parseServiceSchema({
+            name: topic,
+            actions,
+            events,
+        });
+    }
+}
+```
+
+**When to use:** Only when you need:
+
+- Custom Moleculer validation rules (min, max, positive, etc.)
+- Different validation than TypeScript types provide
+- Backward compatibility with existing validation
+
+---
+
+**Pattern 3: Partial Auto-Generation with Manual Overrides (ADVANCED - Rarely Needed)**
+
+Use this pattern ONLY when you need complete control over specific actions with custom logic.
+
+```typescript
+export class [ServiceName]MoleculerService extends Service {
+    constructor(broker: ServiceBroker, { container }: { container: Container }) {
+        super(broker);
+        const [serviceName]Service = container.get<I[ServiceName]Service>(SERVER_TYPES.I[ServiceName]Service);
+
+        const { topic } = [ServiceName]ServiceSchemas;
+
+        // Auto-generate with exclusions for manual override
+        const { actions, events } = Moleculer.generateActionsAndEvents<I[ServiceName]Service>(
+            [serviceName]Service,
+            {
+                // Exclude methods that need custom handling
+                exclude: ['complexMethod', 'customLogicMethod'],
+            }
+        );
+
+        this.parseServiceSchema({
+            name: topic,
+            actions: {
+                ...actions,  // All auto-generated actions
+
+                // Manual overrides for excluded methods
+                [[ServiceName]ServiceAction.ComplexMethod]: {
+                    params: zodSchemasToMoleculer([ServiceName]ServiceSchemas.complexMethod),
+                    handler: async (ctx: Context<ComplexParams>) => {
+                        // Custom pre-processing logic
+                        const processed = await this.preProcess(ctx.params);
+
+                        // Call service method
+                        const result = await [serviceName]Service.complexMethod(processed);
+
+                        // Custom post-processing
+                        return this.postProcess(result);
+                    },
+                },
+            },
+            events,
+        });
+    }
+}
+```
+
+**When to use:** Only when you need:
+
+- Custom pre/post-processing logic in action handlers
+- Different parameter transformation before calling service
+- Special error handling or caching logic
+- **In 99% of cases, Pattern 1 is sufficient**
+
+---
+
+**Pattern 4: Include Only Specific Methods (OPTIONAL - For Whitelisting)**
+
+Use this ONLY when you want to expose a limited subset of service methods as Moleculer actions.
+
+```typescript
+const { actions, events } = Moleculer.generateActionsAndEvents<I[ServiceName]Service>(
+    [serviceName]Service,
+    {
+        include: ['findById', 'createItem', 'updateItem'],  // Only these methods
+    }
+);
+```
+
+**When to use:** Only when you need:
+
+- Expose only specific methods via Moleculer (security/API design)
+- Create a limited public API from a larger service interface
+- **In 99% of cases, Pattern 1 is sufficient**
+
+---
+
+#### Key Benefits of Auto-Generation:
+
+✅ **Automatic inheritance**: Parent class methods automatically included
+✅ **Type-safe**: Full TypeScript support with generics
+✅ **Event integration**: Seamlessly handles `@Moleculer.EventHandler` decorators
+✅ **Zero boilerplate**: No repetitive handler code
+✅ **Compile-time safety**: TypeScript catches method changes
+✅ **Flexible**: Override specific methods when needed
+
+#### 🔍 How Prototype Chain Traversal Works:
+
+The auto-generation uses `getAllMethodNames()` helper that traverses the ENTIRE prototype chain:
+
+```typescript
+function getAllMethodNames(obj: unknown): string[] {
+    const methods = new Set<string>();
+    let current = obj;
+
+    // Traverse up the prototype chain
+    while (current && current !== Object.prototype) {
+        const prototype = Object.getPrototypeOf(current);
+        if (prototype && prototype !== Object.prototype) {
+            Object.getOwnPropertyNames(prototype).forEach((name) => {
+                // Only add functions, not constructors or private methods
+                if (name !== 'constructor' && !name.startsWith('_')) {
+                    const descriptor = Object.getOwnPropertyDescriptor(prototype, name);
+                    if (descriptor && typeof descriptor.value === 'function') {
+                        methods.add(name);
+                    }
+                }
+            });
+        }
+        current = prototype;
+    }
+
+    return Array.from(methods);
+}
+```
+
+**Why This Matters:**
+
+- **Problem**: `Object.getOwnPropertyNames(Object.getPrototypeOf(service))` only gets immediate class methods
+- **Solution**: `getAllMethodNames()` traverses entire chain to include parent class methods
+- **Example**: `OrganizationService extends BaseOrganizationService`
+    - Without traversal: Only ~5 methods from OrganizationService
+    - With traversal: All 60+ methods from both classes
+    - Result: All inherited CRUD operations automatically available as Moleculer actions
+
+**Real-World Impact:**
+
+```typescript
+// Before (missing parent methods):
+OrganizationMoleculerService actions: [
+    'createOrganization',    // ✅ From OrganizationService
+    'updateOrganization',    // ✅ From OrganizationService
+    // ❌ Missing 50+ methods from BaseOrganizationService
+]
+
+// After (with prototype chain traversal):
+OrganizationMoleculerService actions: [
+    'createOrganization',    // ✅ From OrganizationService
+    'updateOrganization',    // ✅ From OrganizationService
+    'findById',              // ✅ From BaseOrganizationService
+    'findAll',               // ✅ From BaseOrganizationService
+    'updateStatus',          // ✅ From BaseOrganizationService
+    // ... 50+ more methods from parent classes
+]
+```
+
+#### When to Use Each Pattern:
+
+**Pattern 1 (Full Auto-Generation) - DEFAULT CHOICE:**
+
+✅ **Use for ALL new services (99% of cases)**
+
+- Service has any number of methods (small or large)
+- Standard CRUD operations
+- Event handlers using `@Moleculer.EventHandler` decorator
+- Automatic parent class method inclusion
+- No special validation requirements
+
+**Pattern 2 (Custom Validation) - RARE:**
+
+⚠️ **Use ONLY when:**
+
+- Need Moleculer-specific validation (min, max, positive, etc.) that differs from TypeScript types
+- Backward compatibility with existing validation rules
+- **Estimate: ~5% of services need this**
+
+**Pattern 3 (Manual Overrides) - VERY RARE:**
+
+⚠️ **Use ONLY when:**
+
+- Need custom logic before/after service calls (pre/post-processing)
+- Parameters need transformation before passing to service
+- Special error handling or caching logic
+- **Estimate: ~1% of services need this**
+
+**Pattern 4 (Whitelist) - RARE:**
+
+⚠️ **Use ONLY when:**
+
+- Need to expose limited subset of methods (API security/design)
+- **Estimate: ~2% of services need this**
+
+**Manual Implementation - LEGACY:**
+
+❌ **Avoid - use Pattern 1 instead**
+
+- Only for backward compatibility with existing services
+- Will be migrated to auto-generation over time
+
+---
+
+#### 📡 Event Handler Pattern with Decorators:
+
+**Modern Approach**: Use `@Moleculer.EventHandler()` decorator in service classes:
+
+**CRITICAL NAMING CONVENTION**: Event handler methods MUST be prefixed with `on` (e.g., `onUserCreated`, `onAccountDeleted`, `onPropertyUpdated`).
+
+```typescript
+import { Moleculer } from '@common-stack/codegen-zod';
+
+@injectable()
+export class TeamService extends BaseTeamService {
+    // Event handler for cross-service notifications
+    // ✅ CORRECT: Method name starts with 'on'
+    @Moleculer.EventHandler(OrganizationServiceAction.OnOrgMemberRemoved)
+    async onOrgMemberRemoved(event: { orgName: string; userId: string }): Promise<void> {
+        await this.changeTeamMemberStatus(event.userId, TeamMemberStatus.Deactivated);
+    }
+
+    // Event handler for cleanup on deletion
+    // ✅ CORRECT: Method name starts with 'on'
+    @Moleculer.EventHandler(AccountServiceAction.OnAccountDeleted)
+    async onAccountDeleted(event: { userId: string }): Promise<void> {
+        await this.removeMemberFromTeams(event.userId);
+    }
+
+    // ❌ WRONG: Missing 'on' prefix
+    // @Moleculer.EventHandler(AccountServiceAction.OnAccountDeleted)
+    // async handleAccountDeleted(event: { userId: string }): Promise<void> { }
+}
+```
+
+**Event Handler Naming Rules:**
+
+1. ✅ **MUST start with `on` prefix** - Makes it clear these are event handlers
+2. ✅ Use camelCase after the prefix (e.g., `onUserCreated`, not `onusercreated`)
+3. ✅ Match the event name structure: `OnEventName` → `onEventName`
+4. ❌ Never use other prefixes (handle, process, react, etc.)
+5. ❌ Never use snake_case or kebab-case
+
+**Examples:**
+
+```typescript
+// Event: AccountServiceAction.OnAccountDeleted
+// ✅ Handler: onAccountDeleted
+@Moleculer.EventHandler(AccountServiceAction.OnAccountDeleted)
+async onAccountDeleted(event: { userId: string }): Promise<void> { }
+
+// Event: PropertyMoleculerServiceEvent.OnPropertyCreated
+// ✅ Handler: onPropertyCreated
+@Moleculer.EventHandler(PropertyMoleculerServiceEvent.OnPropertyCreated)
+async onPropertyCreated(property: IProperty): Promise<void> { }
+
+// Event: OrganizationServiceAction.OnOrgMemberRemoved
+// ✅ Handler: onOrgMemberRemoved
+@Moleculer.EventHandler(OrganizationServiceAction.OnOrgMemberRemoved)
+async onOrgMemberRemoved(event: { orgName: string; userId: string }): Promise<void> { }
+```
+
+**Auto-Generation Handles:**
+
+1. Detects all `@Moleculer.EventHandler` decorated methods
+2. Excludes them from actions (they're not callable actions)
+3. Generates event handlers in Moleculer schema
+4. Sets up proper event routing and payload handling
+
+**Event Handler Metadata:**
+
+```typescript
+// Decorator stores metadata:
+{
+    eventName: 'OrganizationServiceAction.OnOrgMemberRemoved',
+    methodName: 'onOrgMemberRemoved',
+    group?: 'team-service'  // Optional event group for load balancing
+}
+```
+
+**What Auto-Generation Does with Event Handlers:**
+
+1. **Detects** all methods decorated with `@Moleculer.EventHandler`
+2. **Excludes** them from actions list (they're not callable actions, they react to events)
+3. **Generates** proper Moleculer event handlers in the service schema
+4. **Validates** that method name starts with `on` prefix (convention enforcement)
+5. **Sets up** proper event routing and payload handling
+
+**Important: Event Handlers vs Regular Methods:**
+
+```typescript
+@injectable()
+export class PropertyService extends BaseService {
+    // ✅ Regular method → becomes Moleculer ACTION (can be called directly)
+    async updateProperty(id: string, data: any): Promise<IProperty> {
+        // Business logic
+        return updatedProperty;
+    }
+
+    // ✅ Event handler → becomes Moleculer EVENT HANDLER (reacts to broadcasts)
+    // NOT exposed as an action - cannot be called directly
+    @Moleculer.EventHandler(AccountServiceAction.OnAccountDeleted)
+    async onAccountDeleted(event: { userId: string }): Promise<void> {
+        // React to event - find and deactivate user's properties
+        await this.updateStatus({ user: event.userId }, PropertyStatusMachineState.Deactivated);
+    }
+}
+```
+
+**Event Flow Pattern:**
+
+```
+Service A (creates entity)
+    ↓
+Direct service call: teamService.createTeam()
+    ↓
+Broadcast notification: broker.broadcast(OnCreateTeam, { team })
+    ↓
+Service B (reacts to event)
+    ↓
+@Moleculer.EventHandler(OnCreateTeam)
+async onCreateTeam(event: { team: ITeam }): Promise<void>
+```
+
+**Important Rules:**
+
+- ✅ Broadcasts send result objects (created entity)
+- ✅ Event handlers perform side effects only (logging, notifications, cleanup)
+- ❌ Event handlers should NOT recreate entities (causes duplicates)
+- ✅ Cross-service events use namespace prefixes (OrganizationServiceAction, AccountServiceAction)
+
+**Template Structure (Manual - Use when auto-generation doesn't fit):**
+
+```typescript
+import { Context, Service, ServiceBroker } from 'moleculer';
+import { Container } from 'inversify';
+import {
+    [ServiceName]ServiceAction,
+    MoleculerServiceName,
+    I[ServiceName]Service,
+    SERVER_TYPES,
+    // Import all required types for method parameters
+} from 'common/server';
+
+/**
+ * Type utility to verify that all I[ServiceName]Service methods have corresponding Moleculer actions.
+ * This ensures compile-time checking when the service interface changes.
+ *
+ * Excluded methods:
+ * - dispose: Lifecycle method, not proxied
+ * - get/getAll/count/etc: BaseService CRUD methods
+ * - bulkDelete/delete: Not supported in proxy services
+ */
+type ServiceMethodsToActions<T> = {
+    // eslint-disable-next-line @typescript-eslint/ban-types
+    [K in keyof T as T[K] extends Function
+        ? K extends
+              | 'dispose'
+              | 'get'
+              | 'getAll'
+              | 'bulkDelete'
+              | 'delete'
+              | 'count'
+              | 'getByName'
+              | 'getByIds'
+              | 'getAllWithCount'
+              | 'create'
+              | 'update'
+              | 'bulkCreate'
+              | 'insert'
+            ? never
+            : K
+        : never]: K;
+};
+
+// This type will show a compile error if any method is missing from the actions
+type Required[ServiceName]Actions = ServiceMethodsToActions<I[ServiceName]Service>;
+
+// Compile-time verification helper - causes error if methods don't match actions
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+const _typeCheck: Record<keyof Required[ServiceName]Actions, boolean> = {
+    methodName1: true,
+    methodName2: true,
+    // ... list ALL service methods here (except excluded ones)
+    // TypeScript will error if you miss any or add extra ones
+};
+
+/**
+ * Moleculer Service for [ServiceName] operations.
+ * Registers actions that delegate to the actual [ServiceName]Service implementation.
+ *
+ * This service runs on the server side and handles incoming Moleculer action calls.
+ * Each action validates parameters and calls the corresponding service method.
+ *
+ * @see [ServiceName]Service for business logic implementation
+ * @see [ServiceName]ProxyService for client-side proxy
+ */
+export class [ServiceName]MoleculerService extends Service {
+    constructor(broker: ServiceBroker, { container }: { container: Container; settings?: unknown }) {
+        super(broker);
+        const topic = MoleculerServiceName.[ServiceName];
+        const [serviceName]Service = container.get<I[ServiceName]Service>(SERVER_TYPES.I[ServiceName]Service);
+
+        this.parseServiceSchema({
+            name: topic,
+
+            // ============================================================================
+            // EVENTS (optional - for reacting to other services)
+            // ============================================================================
+            events: {
+                // Example: React to external events
+                // [OtherServiceAction.OnSomethingHappened]: {
+                //     params: {
+                //         id: 'string',
+                //     },
+                //     handler: async (ctx: Context<{ event: any }>) => {
+                //         // React to event
+                //         this.logger.debug('Event received');
+                //     },
+                // },
+            },
+
+            // ============================================================================
+            // ACTIONS (required - one for each service method)
+            // ============================================================================
+            actions: {
+                // READ OPERATIONS
+                [[ServiceName]ServiceAction.GetItem]: {
+                    params: {
+                        id: 'string',
+                    },
+                    handler: async (ctx: Context<{ id: string }>) =>
+                        [serviceName]Service.getItem(ctx.params.id),
+                },
+
+                [[ServiceName]ServiceAction.FindItems]: {
+                    params: {
+                        where: 'object',
+                    },
+                    handler: async (ctx: Context<{ where: IWhereInput }>) =>
+                        [serviceName]Service.findItems(ctx.params.where),
+                },
+
+                // CREATE OPERATIONS
+                [[ServiceName]ServiceAction.CreateItem]: {
+                    params: {
+                        input: 'object',
+                    },
+                    handler: async (ctx: Context<{ input: ICreateInput }>) =>
+                        [serviceName]Service.createItem(ctx.params.input),
+                },
+
+                // UPDATE OPERATIONS
+                [[ServiceName]ServiceAction.UpdateItem]: {
+                    params: {
+                        id: 'string',
+                        input: 'object',
+                    },
+                    handler: async (ctx: Context<{ id: string; input: IUpdateInput }>) =>
+                        [serviceName]Service.updateItem(ctx.params.id, ctx.params.input),
+                },
+
+                // DELETE OPERATIONS
+                [[ServiceName]ServiceAction.DeleteItem]: {
+                    params: {
+                        id: 'string',
+                    },
+                    handler: async (ctx: Context<{ id: string }>) =>
+                        [serviceName]Service.deleteItem(ctx.params.id),
+                },
+
+                // For methods with multiple parameters, wrap in params object
+                [[ServiceName]ServiceAction.ComplexMethod]: {
+                    params: {
+                        param1: 'string',
+                        param2: 'object',
+                        param3: { type: 'string', optional: true },
+                    },
+                    handler: async (ctx: Context<{ param1: string; param2: IType; param3?: string }>) =>
+                        [serviceName]Service.complexMethod(ctx.params.param1, ctx.params.param2, ctx.params.param3),
+                },
+            },
+        });
+    }
+}
+```
+
+### Moleculer Service Implementation Rules
+
+#### Type Safety with Compile-Time Verification
+
+**CRITICAL**: Use the type checking pattern to ensure all service methods have corresponding actions:
+
+```typescript
+/**
+ * Type utility to verify that all I[ServiceName]Service methods have corresponding Moleculer actions.
+ * This ensures compile-time checking when the service interface changes.
+ *
+ * Excluded methods:
+ * - dispose: Lifecycle method, not proxied
+ * - get/getAll/count/etc: BaseService CRUD methods (inherited from BaseService)
+ * - bulkDelete/delete: Not supported in proxy services
+ */
+type ServiceMethodsToActions<T> = {
+    // eslint-disable-next-line @typescript-eslint/ban-types
+    [K in keyof T as T[K] extends Function
+        ? K extends
+              | 'dispose'
+              | 'get'
+              | 'getAll'
+              | 'bulkDelete'
+              | 'delete'
+              | 'count'
+              | 'getByName'
+              | 'getByIds'
+              | 'getAllWithCount'
+              | 'create'
+              | 'update'
+              | 'bulkCreate'
+              | 'insert'
+            ? never
+            : K
+        : never]: K;
+};
+
+// This type will show a compile error if any method is missing from the actions
+type Required[ServiceName]Actions = ServiceMethodsToActions<I[ServiceName]Service>;
+
+// Compile-time verification helper - causes error if methods don't match actions
+// Add this BEFORE the service class definition
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+const _typeCheck: Record<keyof Required[ServiceName]Actions, boolean> = {
+    methodName1: true,
+    methodName2: true,
+    // ... list ALL service methods here (except excluded ones)
+    // TypeScript will error if you:
+    // 1. Miss a method that exists in the interface
+    // 2. Add a method that doesn't exist in the interface
+    // 3. Misspell a method name
+};
+```
+
+**Important Limitation**:
+
+⚠️ **The `_typeCheck` constant only verifies that method names are listed** - it does NOT verify that:
+
+1. Action handlers are actually implemented in the `actions` object
+2. Action handlers correctly delegate to the service methods
+3. Actions provided by mixins (like `BaseServiceMixin2`) are working
+
+**Why this limitation exists**:
+
+- TypeScript cannot verify that a string key in one object (actions) matches a boolean key in another object (\_typeCheck)
+- Moleculer's dynamic action registration happens at runtime, not compile time
+- Mixins add actions dynamically, which TypeScript cannot track
+
+**What \_typeCheck DOES catch**:
+
+```typescript
+// ✅ CATCHES: Method added to interface but not listed in _typeCheck
+interface IAccountService {
+    newMethod(): void; // Added
+}
+const _typeCheck = {
+    // Missing newMethod - COMPILE ERROR
+};
+
+// ✅ CATCHES: Method removed from interface but still in _typeCheck
+const _typeCheck = {
+    oldMethod: true, // No longer in interface - COMPILE ERROR
+};
+
+// ✅ CATCHES: Method name typo in _typeCheck
+const _typeCheck = {
+    creeateAccount: true, // Typo - COMPILE ERROR (should be createAccount)
+};
+```
+
+**What \_typeCheck DOES NOT catch**:
+
+```typescript
+// ❌ DOES NOT CATCH: Listed in _typeCheck but action handler not implemented
+const _typeCheck = {
+    createAccount: true,  // Listed
+};
+actions: {
+    // createAccount handler missing - NO COMPILE ERROR!
+};
+
+// ❌ DOES NOT CATCH: Action handler exists but doesn't call service method
+actions: {
+    [AccountServiceAction.CreateAccount]: {
+        handler: () => console.log('oops'),  // Wrong implementation - NO COMPILE ERROR!
+    },
+};
+```
+
+**Best Practices to Address Limitations**:
+
+1. **Use \_typeCheck as a checklist** - When you add a method to \_typeCheck, immediately implement the action handler
+
+2. **Follow naming convention** - Use consistent enum values that match method names:
+
+    ```typescript
+    // Good: Easy to verify visually
+    createAccount: true,  // in _typeCheck
+    [ServiceAction.CreateAccount]: { ... }  // in actions
+
+    // Bad: Hard to match
+    createAccount: true,  // in _typeCheck
+    [ServiceAction.AddNew]: { ... }  // in actions - what method does this call?
+    ```
+
+3. **Group actions by \_typeCheck order** - List actions in same order as \_typeCheck for easy visual verification
+
+4. **Use BaseServiceMixin2 for CRUD operations** - Don't manually implement get/create/update if the mixin provides them:
+
+    ```typescript
+    this.parseServiceSchema({
+        name: topic,
+        mixins: [BaseServiceMixin2(this.serviceInstance)], // Provides CRUD actions
+        actions: {
+            // Only service-specific actions here
+        },
+    });
+    ```
+
+5. **Add runtime validation** (optional) - For critical services, add runtime checks:
+
+    ```typescript
+    constructor(broker: ServiceBroker, { container }: { container: Container }) {
+        super(broker);
+        this.parseServiceSchema({...});
+
+        // Runtime verification (development only)
+        if (process.env.NODE_ENV !== 'production') {
+            const requiredActions: (keyof RequiredAccountActions)[] = [
+                'createAccount', 'updateAccount', // ...list all methods
+            ];
+            requiredActions.forEach(method => {
+                if (!this.schema.actions[AccountServiceAction[method]]) {
+                    console.warn(`Missing action handler for ${method}`);
+                }
+            });
+        }
+    }
+    ```
+
+**Benefits**:
+
+- **Immediate feedback**: TypeScript compiler fails when interface changes but \_typeCheck doesn't
+- **Prevents runtime errors**: Catches missing methods at compile time (when used as checklist)
+- **Self-documenting**: Lists all service methods in one place
+- **Refactoring safety**: Renaming/removing methods triggers errors automatically
+
+**Example Error Messages**:
+
+```
+Type '{ ... }' is missing the following properties from type 'Record<...>': newMethod, anotherMethod
+```
+
+This error means you added `newMethod` and `anotherMethod` to the interface but forgot to add them to `_typeCheck`.
+
+#### ✅ DO:
+
+1. **Create an action for EVERY service method** (except `dispose()`):
+
+    ```typescript
+    [[ServiceName]ServiceAction.MethodName]: {
+        params: { /* validation schema */ },
+        handler: async (ctx: Context<TypedParams>) => service.methodName(ctx.params.arg1, ctx.params.arg2),
+    },
+    ```
+
+2. **Add all method names to \_typeCheck constant**:
+
+    ```typescript
+    const _typeCheck: Record<keyof RequiredAccountActions, boolean> = {
+        createDefaultAccount: true,
+        createUserToken: true,
+        updateUserAccount: true,
+        // ... all other methods
+    };
+    ```
+
+3. **Always use strongly typed Context**:
+4. **Always use strongly typed Context**:
+
+    ```typescript
+    handler: async (ctx: Context<{ id: string; input: IUpdateInput }>) =>
+    ```
+
+5. **Validate parameters using Moleculer params schema**:
+
+    ```typescript
+    params: {
+        id: 'string',                              // Required string
+        name: { type: 'string', optional: true },  // Optional string
+        items: 'array',                            // Required array
+        data: 'object',                            // Required object
+        count: 'number',                           // Required number
+        active: 'boolean',                         // Required boolean
+    },
+    ```
+
+6. **Extract all parameters from ctx.params**:
+
+    ```typescript
+    handler: async (ctx: Context<{ a: string; b: number; c?: boolean }>) =>
+        service.method(ctx.params.a, ctx.params.b, ctx.params.c),
+    ```
+
+7. **Import ALL required types** from 'common/server'
+
+8. **Group actions by operation type** with comments
+
+#### ❌ DON'T:
+
+1. **Don't add business logic in handlers**
+2. **Don't transform data** (that's the service's job)
+3. **Don't use `any` types** - use proper interfaces
+4. **Don't forget optional parameter handling**
+5. **Don't skip parameter validation schemas**
+
+### Special Cases for Moleculer Services
+
+**Synchronous methods**:
+
+```typescript
+[[ServiceName]ServiceAction.SyncMethod]: {
+    params: { email: 'string', secret: 'string' },
+    handler: (ctx: Context<{ email: string; secret: string }>) =>
+        service.syncMethod(ctx.params.email, ctx.params.secret),  // No async
+},
+```
+
+**Methods with complex nested objects**:
+
+```typescript
+[[ServiceName]ServiceAction.ComplexParams]: {
+    params: { args: 'object' },
+    handler: async (ctx: Context<{
+        args: {
+            details: IDetailsInput;
+            metadata: IMetadata;
+            options?: IOptions;
+        };
+    }>) => service.complexMethod(ctx.params.args),
+},
+```
+
+**Methods with union types or optional chaining**:
+
+```typescript
+[[ServiceName]ServiceAction.WithOptions]: {
+    params: {
+        id: 'string',
+        options: { type: 'object', optional: true },
+    },
+    handler: async (ctx: Context<{ id: string; options?: IOptions }>) =>
+        service.method(ctx.params.id, ctx.params.options),
+},
+```
+
+### Task 3: Create Proxy Service
+
+**STRICT FILE NAMING CONVENTION:**
+
+✅ **CORRECT**: Use PascalCase matching the class name
+
+- File: `AccountProxyService.ts` → Class: `AccountProxyService`
+- File: `ProjectProxyService.ts` → Class: `ProjectProxyService`
+- File: `TeamProxyService.ts` → Class: `TeamProxyService`
+- File: `PropertyProxyService.ts` → Class: `PropertyProxyService`
+
+❌ **WRONG**: Do NOT use kebab-case or other variations
+
+- ❌ `account-proxy-service.ts` (kebab-case)
+- ❌ `property-proxy-service.ts` (kebab-case)
+- ❌ `AccountProxy.ts` (missing Service)
+- ❌ `AccountMicroservice.ts` (wrong suffix - use ProxyService)
+- ❌ `account_proxy_service.ts` (snake-case)
+
+**File Location Patterns:**
+
+Pattern 1 (Core module - MOST COMMON):
+`packages-modules/[module-name]/core/src/server-context/proxy-services/[ServiceName]ProxyService.ts`
+
+Examples:
+
+- `packages-modules/property/core/src/server-context/proxy-services/PropertyProxyService.ts`
+- `packages-modules/billing-api/core/src/server-context/proxy-services/InvoiceProxyService.ts`
+- `packages-modules/calendar-events/core/src/server-context/proxy-services/CalendarEventProxyService.ts`
+
+Pattern 2 (Servers module - LEGACY):
+`packages-modules/[module-name]/core/src/servers/services/[ServiceName]ProxyService.ts`
+
+Examples:
+
+- `packages-modules/account-api/core/src/servers/services/AccountProxyService.ts`
+- `packages-modules/account-api/core/src/servers/services/ProjectProxyService.ts`
+
+**Directory Structure:**
+
+```
+packages-modules/
+  property/                           # Module folder
+    core/                            # Core package (client-side code)
+      src/
+        server-context/              # Server context (NEW STANDARD)
+          proxy-services/            # Proxy services folder
+            PropertyProxyService.ts  # ✅ Proxy service here
+            index.ts                 # Export from this folder
+    server/                          # Server package (server-side code)
+      src/
+        plugins/                     # Moleculer services folder
+          PropertyMoleculerService.ts # Moleculer service here
+        services/                    # Business logic services
+          property-service.ts        # Actual service implementation
+```
+
+**Directory Naming Rules:**
+
+1. ✅ Use `server-context/proxy-services/` for NEW proxy services (preferred)
+2. ⚠️ `servers/services/` is LEGACY pattern (still valid but being migrated)
+3. ✅ Always plural: `proxy-services/` not `proxy-service/`
+4. ✅ Always kebab-case for directories: `server-context/` not `serverContext/`
+5. ✅ Always PascalCase for files: `PropertyProxyService.ts`
+6. ❌ Never mix cases: `ProxyServices/` or `proxy_services/` are wrong
+
+**File Naming Rules:**
+
+1. ✅ File name MUST match class name exactly
+2. ✅ Use PascalCase (first letter uppercase)
+3. ✅ Always end with `ProxyService.ts`
+4. ✅ Service name comes first: `[ServiceName]ProxyService`
+5. ❌ Never use kebab-case (dashes)
+6. ❌ Never use snake-case (underscores)
+7. ❌ Never use `Microservice` suffix (legacy naming)
+8. ❌ Never use plural form (e.g., `PropertiesProxyService` is wrong)
+
+**Index File Pattern:**
+
+Create an `index.ts` in the proxy-services folder to export all proxies:
+
+```typescript
+// packages-modules/property/core/src/server-context/proxy-services/index.ts
+export * from './PropertyProxyService';
+export * from './PropertyTypeProxyService';
+// ... other proxy services
+```
+
+**Migration Guide:**
+
+If you find proxy services in the OLD location (`servers/services/`):
+
+1. Create new directory structure: `server-context/proxy-services/`
+2. Move proxy service files to new location
+3. Update imports in container modules
+4. Update index.ts exports
+5. Keep file names EXACTLY the same (PascalCase)
+
+---
+
+## 🎯 MANDATORY APPROACH: Auto-Generation with Declaration Merging
+
+**⚠️ STRICT REQUIREMENT**: ALL new proxy services MUST use this exact pattern with declaration merging.
+
+**DO NOT use:**
+
+- ❌ `implements IService` - causes TypeScript errors
+- ❌ `extends BaseProxyService2` - legacy pattern, deprecated
+- ❌ Manual method definitions - defeats auto-generation
+- ❌ Index signatures `[key: string]: any` - unsafe hack
+- ❌ Manual property declarations (`topic`, `broker`, `callAction`)
+
+**REQUIRED Pattern - Copy Exactly:**
+
+```typescript
+import { injectable, inject } from 'inversify';
+import { ServiceBroker } from 'moleculer';
+import type { CdmLogger } from '@cdm-logger/core';
+import { CommonType } from '@common-stack/core';
+import { generateProxyMethods } from '@common-stack/codegen-zod';
+import type { I[ServiceName]Service } from 'common/server';
+import { [ServiceName]ServiceSchemas } from 'common/server';
+
+/**
+ * Client-side proxy for [ServiceName] operations using AUTO-GENERATION.
+ *
+ * 🎉 FULLY AUTOMATIC: All I[ServiceName]Service methods auto-generated!
+ *
+ * ✅ ZERO BOILERPLATE: No manual method definitions
+ * ✅ TYPE-SAFE: Full TypeScript inference from I[ServiceName]Service
+ * ✅ VALIDATED: Zod schemas for parameter validation
+ * ✅ MAINTAINABLE: Add method to interface → automatically available as proxy
+ */
+@injectable()
+// eslint-disable-next-line @typescript-eslint/no-unsafe-declaration-merging
+export class [ServiceName]ProxyService {
+    constructor(
+        @inject(CommonType.MOLECULER_BROKER)
+        broker: ServiceBroker,
+        @inject(CommonType.LOGGER)
+        logger: CdmLogger.ILogger,
+    ) {
+        const childLogger = logger.child({ className: '[ServiceName]ProxyService' });
+
+        // ⚡ ONE LINE: Auto-generate all proxy methods
+        generateProxyMethods<I[ServiceName]Service>(this, [ServiceName]ServiceSchemas, broker, childLogger);
+    }
+}
+
+// Declaration merging for type safety - provides full interface implementation
+// eslint-disable-next-line @typescript-eslint/no-unsafe-declaration-merging
+export interface [ServiceName]ProxyService extends I[ServiceName]Service {}
+```
+
+**CRITICAL RULES - DO NOT DEVIATE:**
+
+1. ✅ **MUST use declaration merging** - separate class and interface with same name
+2. ✅ **MUST have both eslint-disable comments** for `no-unsafe-declaration-merging`
+3. ✅ **MUST import service schemas** - `[ServiceName]ServiceSchemas` (not as type)
+4. ✅ **MUST import service interface as type** - `import type { I[ServiceName]Service }`
+5. ✅ **MUST use `generateProxyMethods()`** - single call in constructor
+6. ✅ **MUST create child logger** - for proper logging context
+7. ✅ **NO manual method definitions** - all methods come from generateProxyMethods
+8. ✅ **NO implements keyword** - declaration merging handles this
+9. ✅ **NO extends BaseProxyService2** - deprecated pattern
+10. ✅ **NO manual property declarations** - generateProxyMethods adds them
+
+**Template Validation Checklist:**
+
+Before submitting generated code, verify:
+
+- [ ] Class name ends with `ProxyService`
+- [ ] Has `@injectable()` decorator
+- [ ] Has declaration merging comment: `// eslint-disable-next-line @typescript-eslint/no-unsafe-declaration-merging`
+- [ ] Constructor has exactly 2 parameters: `broker` and `logger`
+- [ ] Creates child logger with className
+- [ ] Single `generateProxyMethods()` call with 4 arguments
+- [ ] Interface declaration after class with same name
+- [ ] Interface extends service interface
+- [ ] No method definitions in class body
+- [ ] No property declarations in class body
+- [ ] Total file length: ~40 lines
+
+**Example Output:**
+
+```typescript
+// ✅ CORRECT - Exact pattern to follow
+@injectable()
+// eslint-disable-next-line @typescript-eslint/no-unsafe-declaration-merging
+export class AccountProxyService {
+    constructor(
+        @inject(CommonType.MOLECULER_BROKER)
+        broker: ServiceBroker,
+        @inject(CommonType.LOGGER)
+        logger: CdmLogger.ILogger,
+    ) {
+        const childLogger = logger.child({ className: 'AccountProxyService' });
+        generateProxyMethods<IAccountService>(this, AccountServiceSchemas, broker, childLogger);
+    }
+}
+
+// eslint-disable-next-line @typescript-eslint/no-unsafe-declaration-merging
+export interface AccountProxyService extends IAccountService {}
+```
+
+**Common Mistakes to Avoid:**
+
+```typescript
+// ❌ WRONG - Using implements
+export class ProxyService implements IService {
+    [key: string]: any;  // Unsafe hack!
+}
+
+// ❌ WRONG - Extending BaseProxyService2
+export class ProxyService extends BaseProxyService2<IModel> implements IService {
+}
+
+// ❌ WRONG - Manual method definitions
+export class ProxyService {
+    getItem(id: string): Promise<Item> {
+        return this.callAction(...);  // Defeats auto-generation!
+    }
+}
+
+// ❌ WRONG - Manual property declarations
+export class ProxyService {
+    protected topic!: string;  // Don't declare manually!
+    protected broker!: ServiceBroker;
+}
+
+// ❌ WRONG - Missing declaration merging
+export class ProxyService {
+    // Class only, no interface
+}
+```
+
+**Why Declaration Merging:**
+
+1. TypeScript merges class and interface into single type
+2. No need for `implements` - interface provides the type
+3. No TypeScript errors about missing methods
+4. Full IntelliSense support
+5. Runtime methods added by `generateProxyMethods()`
+6. Clean, minimal code
+
+---
+
+## 📋 Manual Proxy Service Template (DEPRECATED - DO NOT USE)
+
+**⚠️ DEPRECATED**: This pattern is no longer supported. Use auto-generation with declaration merging instead.
+
+**Only mentioned for reference when maintaining legacy code.**
+
+**Template Structure (LEGACY - Use Auto-Generation Instead)**:
+
+```typescript
+import { inject, injectable } from 'inversify';
+import { ServiceBroker } from 'moleculer';
+import { CommonType } from '@common-stack/core';
+import type { CdmLogger } from '@cdm-logger/core';
+import { BaseProxyService2 } from '@common-stack/store-mongo';
+import {
+    [ServiceName]ServiceAction,
+    MoleculerServiceName,
+    I[ServiceName]Service,
+    AsDomainType,
+    I[ServiceName]Model,
+    // Import other types as needed
+} from 'common/server';
+
+/**
+ * Proxy Service for [ServiceName] operations.
+ * Delegates all operations to [ServiceName]Service through Moleculer broker.
+ *
+ * Pattern:
+ * - Extends BaseProxyService2 which provides callAction method
+ * - Implements I[ServiceName]Service interface
+ * - Each method calls this.callAction with appropriate action enum and parameters
+ * - No business logic - pure delegation
+ *
+ * @see [ServiceName]Service for actual implementation
+ * @see BaseProxyService2 for base proxy functionality
+ */
+@injectable()
+export class [ServiceName]ProxyService
+    extends BaseProxyService2<I[ServiceName]Model>
+    implements I[ServiceName]Service
+{
+    protected logger?: CdmLogger.ILogger;
+
+    // ⚠️ CRITICAL: Set the Moleculer service name - REQUIRED for proxy to work
+    protected topic = MoleculerServiceName.[ServiceName];
+
+    constructor(
+        @inject(CommonType.MOLECULER_BROKER)
+        broker: ServiceBroker,
+        @inject(CommonType.LOGGER)
+        logger: CdmLogger.ILogger,
+    ) {
+        super(broker, logger);
+        this.logger = logger.child({ className: '[ServiceName]ProxyService' });
+    }
+
+    // ============================================================================
+    // READ OPERATIONS
+    // ============================================================================
+
+    methodName(param: Type): Promise<ReturnType> {
+        return this.callAction([ServiceName]ServiceAction.MethodName, { param });
+    }
+
+    // ============================================================================
+    // CREATE OPERATIONS
+    // ============================================================================
+
+    // ... implement create methods
+
+    // ============================================================================
+    // UPDATE OPERATIONS
+    // ============================================================================
+
+    // ... implement update methods
+
+    // ============================================================================
+    // DELETE OPERATIONS
+    // ============================================================================
+
+    // ... implement delete methods
+
+    // ============================================================================
+    // LIFECYCLE METHODS
+    // ============================================================================
+
+    dispose(): void {
+        // Dispose is a lifecycle method, not proxied
+        // No-op for proxy service
+    }
+}
+```
+
+### Implementation Rules
+
+#### ✅ DO:
+
+1. **For each interface method**, create a corresponding proxy method:
+
+    ```typescript
+    interfaceMethod(param1: Type1, param2?: Type2): Promise<ReturnType> {
+        return this.callAction(ServiceAction.InterfaceMethod, { param1, param2 });
+    }
+    ```
+
+2. **Pass ALL parameters as a single object**:
+
+    ```typescript
+    updateItem(id: string, data: UpdateInput, userId: string): Promise<Item> {
+        return this.callAction(ServiceAction.UpdateItem, { id, data, userId });
+    }
+    ```
+
+3. **Include optional parameters** in the params object:
+
+    ```typescript
+    getItems(filter?: Filter, limit?: number): Promise<Item[]> {
+        return this.callAction(ServiceAction.GetItems, { filter, limit });
+    }
+    ```
+
+4. **Group methods by operation type** with clear section comments
+
+5. **Use section dividers** (80-char lines of =)
+
+6. **Match parameter names exactly** from the interface
+
+7. **Handle void returns** - still use callAction:
+    ```typescript
+    notifyUser(userId: string, message: string): Promise<void> {
+        return this.callAction(ServiceAction.NotifyUser, { userId, message });
+    }
+    ```
+
+#### ❌ DON'T:
+
+1. **Don't add ANY business logic**:
+
+    ```typescript
+    // ❌ BAD
+    createItem(data: Input): Promise<Item> {
+        if (!data.name) throw new Error('Name required');
+        return this.callAction(ServiceAction.CreateItem, { data });
+    }
+
+    // ✅ GOOD
+    createItem(data: Input): Promise<Item> {
+        return this.callAction(ServiceAction.CreateItem, { data });
+    }
+    ```
+
+2. **Don't transform or validate data**
+
+3. **Don't add logging** (already in callAction)
+
+4. **Don't catch errors** (unless re-throwing)
+
+5. **Don't add async/await** (return Promise directly):
+
+    ```typescript
+    // ❌ BAD
+    async getItem(id: string): Promise<Item> {
+        return await this.callAction(ServiceAction.GetItem, { id });
+    }
+
+    // ✅ GOOD
+    getItem(id: string): Promise<Item> {
+        return this.callAction(ServiceAction.GetItem, { id });
+    }
+    ```
+
+### Special Cases
+
+**Synchronous methods** that can't be proxied:
+
+```typescript
+createToken(_param1: string, _param2: string): string {
+    throw new Error('createToken should be called directly on [ServiceName]Service, not via proxy.');
+}
+```
+
+**Methods with Types.ObjectId parameters**:
+
+```typescript
+acceptInvitation(id: string | Types.ObjectId, user: User): Promise<boolean> {
+    return this.callAction(ServiceAction.AcceptInvitation, { id, user });
+}
+```
+
+**Methods with complex union types** - pass as-is
+
+### Task 4: Update Container Module
+
+Update the DI container module to register the proxy service:
+`packages-modules/[module-name]/server/src/modules/[service]/containers/module.ts`
+
+**Pattern for Proxy Module**:
+
+```typescript
+import { ContainerModule, interfaces } from 'inversify';
+import { SERVER_TYPES, I[ServiceName]Service } from 'common/server';
+import { [ServiceName]ProxyService } from '../services';
+
+export const [ServiceName]ProxyModule: (settings: any) => ContainerModule = (setting) =>
+    new ContainerModule((bind: interfaces.Bind) => {
+        // Bind proxy service to interface
+        bind<I[ServiceName]Service>(SERVER_TYPES.I[ServiceName]Service)
+            .to([ServiceName]ProxyService)
+            .inSingletonScope();
+    });
+```
+
+**Complete module file example**:
+
+```typescript
+import { ContainerModule, interfaces } from 'inversify';
+import {
+    I[ServiceName]Repository,
+    SERVER_TYPES,
+    I[ServiceName]Service,
+} from 'common/server';
+import { [ServiceName]Repository } from '../store/repositories';
+import {
+    [ServiceName]ProxyService,
+    [ServiceName]Service,
+} from '../services';
+
+// Database Module (registers actual service + repository)
+export const [ServiceName]DbModule: (settings: any) => ContainerModule = (setting) =>
+    new ContainerModule((bind: interfaces.Bind) => {
+        bind<I[ServiceName]Repository>(SERVER_TYPES.I[ServiceName]Repository)
+            .to([ServiceName]Repository)
+            .inSingletonScope();
+
+        bind<I[ServiceName]Service>(SERVER_TYPES.I[ServiceName]Service)
+            .to([ServiceName]Service)
+            .inSingletonScope();
+    });
+
+// Proxy Module (registers proxy service only)
+export const [ServiceName]ProxyModule: (settings: any) => ContainerModule = (setting) =>
+    new ContainerModule((bind: interfaces.Bind) => {
+        bind<I[ServiceName]Service>(SERVER_TYPES.I[ServiceName]Service)
+            .to([ServiceName]ProxyService)
+            .inSingletonScope();
+    });
+```
+
+**Rules for container modules**:
+
+- **DbModule**: Binds actual service + repository (used by server that runs business logic)
+- **ProxyModule**: Binds proxy service only (used by client services that call via Moleculer)
+- Use same `SERVER_TYPES.I[ServiceName]Service` symbol for both
+- Both use `.inSingletonScope()` for performance
+- Keep consistent naming: `[ServiceName]DbModule` and `[ServiceName]ProxyModule`
+
+### Output Requirements
+
+1. **Complete GraphQL enum** with all actions
+2. **Complete Moleculer service** file with:
+    - All imports (including Service, ServiceBroker, Context from 'moleculer')
+    - Container injection for service instance
+    - All actions mapped to service methods
+    - Proper parameter validation schemas
+    - Strongly typed Context handlers
+3. **Complete proxy service** file with:
+    - All imports
+    - Proper class structure
+    - All interface methods implemented
+    - Organized by operation type
+    - Section comments
+    - JSDoc on class
+4. **Updated container module** with proxy registration
+5. **Instructions**: "After creating these files, run: `yarn generateGraphql && yarn build`"
+
+### Quality Checklist
+
+Before outputting, verify:
+
+#### Moleculer Service (Auto-Generation):
+
+- [ ] Uses `Moleculer.generateActionsAndEvents<IService>(service)` or `Moleculer.generateAutoInferredActions<IService>(service)`
+- [ ] Service instance retrieved from DI container
+- [ ] Correct `name` set to MoleculerServiceName enum value
+- [ ] Actions and events destructured from generation function
+- [ ] Optional: paramOverrides specified for methods needing custom validation
+- [ ] Optional: exclude specified for manually handled methods
+- [ ] No manual action definitions (unless override needed)
+- [ ] Event handlers use `@Moleculer.EventHandler` decorator in service class
+
+#### Moleculer Service (Manual - Only if needed):
+
+- [ ] All interface methods have corresponding actions
+- [ ] All actions use strongly typed `Context<TypedParams>`
+- [ ] Parameter validation schemas are complete
+- [ ] All parameters extracted from `ctx.params`
+- [ ] No `any` types used
+- [ ] Actions grouped by operation type
+- [ ] Correct `name` set to MoleculerServiceName
+- [ ] Service instance retrieved from DI container
+
+#### Proxy Service (Auto-Generation - RECOMMENDED):
+
+- [ ] Uses `generateProxyMethods<IService>(this, ServiceSchemas, broker, logger)`
+- [ ] Imports from `@common-stack/server-core`
+- [ ] Service schemas imported (e.g., `ProjectServiceSchemas`)
+- [ ] Declaration merging used: `export interface ProxyService extends IService {}`
+- [ ] Both class and interface have eslint-disable for unsafe-declaration-merging
+- [ ] No manual method definitions
+- [ ] No `topic` property needed (derived automatically)
+- [ ] Class is injectable with proper DI
+- [ ] Logger passed to generateProxyMethods
+
+#### Proxy Service (Manual - Legacy):
+
+- [ ] All interface methods have corresponding proxy methods
+- [ ] All proxy methods use `this.callAction()`
+- [ ] All parameters passed as single object
+- [ ] Parameter names match interface exactly
+- [ ] Methods grouped by operation type
+- [ ] No business logic added
+- [ ] Lifecycle methods (dispose) are no-ops
+- [ ] ⚠️ **CRITICAL**: `topic` property set to MoleculerServiceName (REQUIRED)
+- [ ] Extends BaseProxyService2<ModelType>
+- [ ] Implements IService interface
+
+#### Container Module:
+
+- [ ] Container module updated with proxy registration
+- [ ] Uses same SERVER_TYPES symbol as actual service
+
+### Example Output
+
+See these reference implementations:
+
+**Moleculer Services**:
+
+- **Simple (10-15 actions)**: `modules/project/plugins/ProjectMoleculerService.ts`
+- **Complex (40+ actions)**: `plugins/AccountMoleculerService.ts`
+
+**Proxy Services**:
+
+- **Simple (10-15 methods)**: `ProjectProxyService.ts`
+- **Medium (15-20 methods)**: `TeamMicroservice.ts`
+- **Complex (40+ methods)**: `AccountProxyService.ts`
+
+### Complete Example: Account Module
+
+**1. Moleculer Service with Auto-Generation** (`plugins/AccountMoleculerService.ts`):
+
+```typescript
+import { Context, Service, ServiceBroker } from 'moleculer';
+import { Container } from 'inversify';
+import { Moleculer } from '@common-stack/codegen-zod';
+import { AccountServiceAction, IAccountService, MoleculerServiceName, SERVER_TYPES } from 'common/server';
+
+/**
+ * Moleculer Service for Account operations using AUTO-GENERATION.
+ *
+ * This service demonstrates the modern approach:
+ * - Uses Moleculer.generateActionsAndEvents() for automatic action/event generation
+ * - All service methods become actions automatically
+ * - All @Moleculer.EventHandler decorated methods become event handlers
+ * - No manual action definitions needed
+ * - Parent class methods automatically included
+ *
+ * @see AccountService for business logic and event handlers
+ * @see AccountProxyService for client-side proxy
+ */
+export class AccountMoleculerService extends Service {
+    constructor(broker: ServiceBroker, { container }: { container: Container; settings?: unknown }) {
+        super(broker);
+        const topic = MoleculerServiceName.Account;
+        const accountService = container.get<IAccountService>(SERVER_TYPES.IAccountService);
+
+        // ⚡ AUTO-GENERATE both actions and events
+        const { actions, events } = Moleculer.generateActionsAndEvents<IAccountService>(accountService);
+
+        this.parseServiceSchema({
+            name: topic,
+            actions, // ✅ All 60+ methods auto-generated (including parent class methods)
+            events, // ✅ All @Moleculer.EventHandler methods auto-generated
+        });
+    }
+}
+```
+
+**Benefits of Auto-Generation:**
+
+- **30 lines** instead of 200+ lines of manual action definitions
+- **Automatic inheritance**: All parent class methods included
+- **Type-safe**: Full TypeScript inference
+- **Maintainable**: Add method to service → automatically available as action
+- **Event integration**: Decorators handled automatically
+
+**2. Service with Event Handlers** (showing what auto-generation detects):
+
+```typescript
+import { injectable } from 'inversify';
+import { Moleculer } from '@common-stack/codegen-zod';
+import { UserBroadcasterAction, AuthStrategy } from 'common/server';
+
+@injectable()
+export class AccountService extends BaseAccountService {
+    // Regular method → becomes Moleculer action
+    async findAccountById(id: string): Promise<IAccount> {
+        return this.repository.findById(id);
+    }
+
+    // Regular method → becomes Moleculer action
+    async createAccount(account: IAccountInput): Promise<IAccount> {
+        return this.repository.create(account);
+    }
+
+    // Decorated method → becomes Moleculer event handler
+    @Moleculer.EventHandler(UserBroadcasterAction.OnUserCreated)
+    async onUserCreated(event: IUserProfile & { authStrategy: AuthStrategy }): Promise<void> {
+        await this.createDefaultAccount(event, { authStrategy: event.authStrategy });
+    }
+
+    // Decorated method → becomes Moleculer event handler
+    @Moleculer.EventHandler(UserBroadcasterAction.OnAccountLinked)
+    async onAccountLinked(event: { email: string; aliases: string[] }): Promise<void> {
+        await this.updateUserAccountAliases({
+            email: event?.email,
+            aliasesToAdd: event?.aliases,
+        });
+    }
+}
+```
+
+**Result of Auto-Generation:**
+
+- `findAccountById` → action: `AccountServiceAction.FindAccountById`
+- `createAccount` → action: `AccountServiceAction.CreateAccount`
+- `onUserCreated` → event: `UserBroadcasterAction.OnUserCreated` (excluded from actions)
+- `onAccountLinked` → event: `UserBroadcasterAction.OnAccountLinked` (excluded from actions)
+
+**1. Moleculer Service (MANUAL - Legacy Pattern)** (`plugins/AccountMoleculerService.ts`):
+
+```typescript
+import { Context, Service, ServiceBroker } from 'moleculer';
+import { Container } from 'inversify';
+import {
+    AccountServiceAction,
+    IAccountService,
+    IPhoneNumberInput,
+    IUserToken,
+    SERVER_TYPES,
+    TokenTypesEnum,
+} from 'common/server';
+
+export class AccountMoleculerService extends Service {
+    constructor(broker: ServiceBroker, { container }: { container: Container; settings?: unknown }) {
+        super(broker);
+        const accountService = container.get<IAccountService>(SERVER_TYPES.IAccountService);
+
+        this.parseServiceSchema({
+            name: 'accountUser',
+            actions: {
+                // READ OPERATIONS
+                [AccountServiceAction.FindAccountById]: {
+                    params: { id: 'string' },
+                    handler: async (ctx: Context<{ id: string }>) => accountService.findAccountById(ctx.params.id),
+                },
+
+                // CREATE OPERATIONS
+                [AccountServiceAction.CreateAccount]: {
+                    handler: async (ctx: Context<{ account: any }>) => accountService.createAccount(ctx.params.account),
+                },
+
+                // Synchronous method
+                [AccountServiceAction.CreateUserToken]: {
+                    params: {
+                        email: 'string',
+                        secret: 'string',
+                        expiresIn: { type: 'string', optional: true },
+                    },
+                    handler: (ctx: Context<{ email: string; secret: string; expiresIn?: string }>) =>
+                        accountService.createUserToken(ctx.params.email, ctx.params.secret, ctx.params.expiresIn),
+                },
+
+                // With complex parameters
+                [AccountServiceAction.ValidateAndFetchUserToken]: {
+                    params: { userId: 'string', tokens: 'array', type: 'string' },
+                    handler: async (ctx: Context<{ userId: string; tokens: IUserToken[]; type: TokenTypesEnum }>) =>
+                        accountService.validateAndFetchUserToken(ctx.params.userId, ctx.params.tokens, ctx.params.type),
+                },
+            },
+        });
+    }
+}
+```
+
+**2a. Proxy Service (AUTO-GENERATION - RECOMMENDED)** (`ProjectProxyService.ts`):
+
+```typescript
+import { injectable, inject } from 'inversify';
+import { ServiceBroker } from 'moleculer';
+import type { CdmLogger } from '@cdm-logger/core';
+import { CommonType } from '@common-stack/core';
+import { generateProxyMethods } from '@common-stack/codegen-zod';
+import { IProjectService, ProjectServiceSchemas } from 'common/server';
+
+/**
+ * Client-side proxy for Project operations using AUTO-GENERATION.
+ *
+ * 🎉 FULLY AUTOMATIC: All IProjectService methods auto-generated!
+ *
+ * Uses generateProxyMethods() to automatically create all proxy methods:
+ *  • getProjects(), addProject(), updateProject(), deleteProject(), etc.
+ *
+ * ✅ ZERO BOILERPLATE: No manual method definitions (~100 lines eliminated)
+ * ✅ TYPE-SAFE: Full TypeScript inference from IProjectService
+ * ✅ VALIDATED: Zod schemas for parameter validation
+ * ✅ MAINTAINABLE: Add method to interface → automatically available as proxy
+ * ✅ CORRECT ORDERING: Parameters passed in correct order
+ */
+@injectable()
+// eslint-disable-next-line @typescript-eslint/no-unsafe-declaration-merging
+export class ProjectProxyService {
+    constructor(
+        @inject(CommonType.MOLECULER_BROKER)
+        broker: ServiceBroker,
+        @inject('Logger')
+        logger: CdmLogger.ILogger,
+    ) {
+        const childLogger = logger.child({ className: 'ProjectProxyService' });
+        generateProxyMethods<IProjectService>(this, ProjectServiceSchemas, broker, childLogger);
+    }
+}
+
+// Declaration merging for type safety - provides full interface implementation
+// eslint-disable-next-line @typescript-eslint/no-unsafe-declaration-merging
+export interface ProjectProxyService extends IProjectService {}
+```
+
+**2b. Proxy Service (MANUAL - LEGACY)** (`AccountProxyService.ts`):
+
+```typescript
+import { inject, injectable } from 'inversify';
+import { ServiceBroker } from 'moleculer';
+import { BaseProxyService2 } from '@common-stack/store-mongo';
+import {
+    AccountServiceAction,
+    IAccountService,
+    IPhoneNumberInput,
+    IUserAccountModel,
+    IUserToken,
+    TokenTypesEnum,
+} from 'common/server';
+
+@injectable()
+export class AccountProxyService extends BaseProxyService2<IUserAccountModel> implements IAccountService {
+    // ⚠️ CRITICAL: topic is REQUIRED for manual proxy services
+    protected topic = 'accountUser';
+
+    constructor(broker: ServiceBroker, logger: any) {
+        super(broker, logger);
+    }
+
+    // READ OPERATIONS
+    findAccountById(id: string): Promise<any> {
+        return this.callAction(AccountServiceAction.FindAccountById, { id });
+    }
+
+    // CREATE OPERATIONS
+    createAccount(account: any): Promise<any> {
+        return this.callAction(AccountServiceAction.CreateAccount, { account });
+    }
+
+    // Synchronous method - throws error (cannot be proxied)
+    createUserToken(email: string, secret: string, expiresIn?: string): string {
+        throw new Error('createUserToken should be called directly on AccountService, not via proxy.');
+    }
+
+    // With complex parameters
+    validateAndFetchUserToken(userId: string, tokens: IUserToken[], type: TokenTypesEnum): Promise<IUserToken> {
+        return this.callAction(AccountServiceAction.ValidateAndFetchUserToken, { userId, tokens, type });
+    }
+
+    // ... other methods (~40+ manual method definitions)
+}
+```
+
+**3. Container Module** (`modules/account/containers/module.ts`):
+
+**3. Container Module** (`modules/account/containers/module.ts`):
+
+```typescript
+import { ContainerModule, interfaces } from 'inversify';
+import { IAccountRepository, SERVER_TYPES, IAccountService } from 'common/server';
+import { AccountRepository } from '../store/repositories';
+import { AccountProxyService, AccountService } from '../services';
+
+// Database Module - Registers actual service + repository (for server)
+export const AccountDbModule: (settings: any) => ContainerModule = (setting) =>
+    new ContainerModule((bind: interfaces.Bind) => {
+        bind<IAccountRepository>(SERVER_TYPES.IAccountRepository).to(AccountRepository).inSingletonScope();
+        bind<IAccountService>(SERVER_TYPES.IAccountService).to(AccountService).inSingletonScope();
+    });
+
+// Proxy Module - Registers proxy service only (for clients)
+export const AccountProxyModule: (settings: any) => ContainerModule = (setting) =>
+    new ContainerModule((bind: interfaces.Bind) => {
+        bind<IAccountService>(SERVER_TYPES.IAccountService).to(AccountProxyService).inSingletonScope();
+    });
+```
+
+### Complete Example: Project Module
+
+**1. Moleculer Service** (`modules/project/plugins/project-moleculer-service.ts`):
+
+```typescript
+import { Context, Service, ServiceBroker } from 'moleculer';
+import { MoleculerTopics, IProjectService, ProjectCommand, SERVER_TYPES } from 'common/server';
+import { Container } from 'inversify';
+
+export class ProjectMolecularService extends Service {
+    private projectService: IProjectService;
+
+    constructor(broker: ServiceBroker, { container }: { container: Container }) {
+        super(broker);
+        this.projectService = container.get<IProjectService>(SERVER_TYPES.IProjectService);
+
+        this.parseServiceSchema({
+            name: MoleculerTopics.Project,
+            actions: {
+                [ProjectCommand.GetProjects]: {
+                    handler: async (ctx: Context<{ orgName: string; offset?: number; limit?: number }>) =>
+                        this.projectService.getProjects(ctx.params.orgName, ctx.params.offset, ctx.params.limit),
+                },
+                [ProjectCommand.AddProject]: {
+                    handler: async (ctx: Context<{ project: any; orgId: string; orgName: string }>) =>
+                        this.projectService.addProject(ctx.params.project, ctx.params.orgId, ctx.params.orgName),
+                },
+                [ProjectCommand.UpdateProject]: {
+                    handler: async (ctx: Context<{ where: any; project: any; orgName: string }>) =>
+                        this.projectService.updateProject(ctx.params.where, ctx.params.project, ctx.params.orgName),
+                },
+                [ProjectCommand.DeleteProject]: {
+                    handler: async (ctx: Context<{ where: any; tenantId: string }>) =>
+                        this.projectService.deleteProject(ctx.params.where, ctx.params.tenantId),
+                },
+            },
+        });
+    }
+}
+```
+
+**2. Container Module** (`modules/project/containers/module.ts`):
+
+**2. Container Module** (`modules/project/containers/module.ts`):
+
+```typescript
+import { ContainerModule, interfaces } from 'inversify';
+import { IProjectRepository, SERVER_TYPES, IProjectService } from 'common/server';
+import { ProjectRepository } from '../store/repositories';
+import { ProjectProxyService, ProjectService } from '../services';
+
+// Database Module - Registers actual service
+export const ProjectDbModule: (settings: any) => ContainerModule = (setting) =>
+    new ContainerModule((bind: interfaces.Bind) => {
+        bind<IProjectRepository>(SERVER_TYPES.IProjectRepository).to(ProjectRepository).inSingletonScope();
+        bind<IProjectService>(SERVER_TYPES.IProjectService).to(ProjectService).inSingletonScope();
+    });
+
+// Proxy Module - Registers proxy service
+export const ProjectProxyModule: (settings: any) => ContainerModule = (setting) =>
+    new ContainerModule((bind: interfaces.Bind) => {
+        bind<IProjectService>(SERVER_TYPES.IProjectService).to(ProjectProxyService).inSingletonScope();
+    });
+```
+
+**Key Points**:
+
+- **Both modules use same interface** (`IProjectService`)
+- **Both use same DI symbol** (`SERVER_TYPES.IProjectService`)
+- DbModule includes repository + actual service
+- ProxyModule includes only proxy service
+- Consumer code doesn't know if using proxy or actual service (polymorphism)
+- **Moleculer service** must be registered separately in server bootstrap
+
+---
+
+## 🤖 PROMPT END
+
+---
+
+## Usage Instructions
+
+1. **Copy the prompt above** (from "PROMPT START" to "PROMPT END")
+
+2. **Customize the placeholders**:
+    - Replace `[ServiceName]` with your service name (e.g., "Project", "User", "Invoice")
+    - Replace `[module-name]` with your module name (e.g., "account-api", "project-api")
+    - Replace `[service]` with lowercase service name (e.g., "project", "user", "invoice")
+
+3. **Provide to LLM** with the following files:
+
+    ```
+    Attached files:
+    1. packages/common/src/services/[ServiceName].ts
+    2. packages-modules/[module]/server/src/graphql/schema/service.graphql
+    3. packages-modules/[module]/server/src/modules/[service]/containers/module.ts
+    4. (Optional) packages-modules/[module]/server/src/services/[ServiceName].ts
+    ```
+
+4. **Review the output** and verify against the checklist
+
+5. **Run the generation command**:
+
+    ```bash
+    yarn generateGraphql
+    ```
+
+6. **Update the container module** with the generated proxy registration
+
+7. **Verify compilation**:
+    ```bash
+    # Check for TypeScript errors
+    cd packages-modules/[module]/core
+    npx tsc --noEmit
+    ```
+
+---
+
+## Example Conversation
+
+**You**: "I need to create a proxy service for UserService"
+
+**Attach**:
+
+- `packages/common/src/services/UserService.ts`
+- `packages-modules/user-api/server/src/graphql/schema/service.graphql`
+- `packages-modules/user-api/server/src/modules/user/containers/module.ts`
+
+**Paste**: [The full prompt from above with [ServiceName] replaced with "User"]
+
+**LLM Output**:
+
+1. Complete proxy service implementation
+2. GraphQL enum updates
+3. Container module registration code
+
+**You Run**:
+
+```bash
+yarn generateGraphql
+```
+
+**You Update**: Apply the container module changes
+
+**Done**: Proxy service ready to use!
+
+---
+
+## Troubleshooting
+
+### Issue: Generated proxy has wrong method signatures
+
+**Fix**: Ensure you attached the correct interface file. The LLM must see the exact method signatures.
+
+### Issue: Missing imports
+
+**Fix**: Check that `MoleculerServiceName` enum includes your service. Add if missing:
+
+```graphql
+extend enum MoleculerServiceName {
+    YourService
+}
+```
+
+### Issue: callAction type errors
+
+**Fix**: After running `yarn generateGraphql`, restart your TypeScript server (VS Code: Cmd+Shift+P → "Restart TS Server")
+
+### Issue: DI container can't resolve service
+
+**Error**: `No matching bindings found for serviceIdentifier: Symbol(IYourService)`
+
+**Fix**: Ensure you're loading the correct module:
+
+- **For server (business logic)**: Load `YourServiceDbModule`
+- **For client (via Moleculer)**: Load `YourServiceProxyModule`
+- Never load both in same container
+
+### Issue: Service methods not being called / "Service not found" errors
+
+**Symptoms**:
+
+- Moleculer throws "Service '[ServiceName]' not found" errors
+- Proxy methods timeout or fail silently
+- Actions not reaching the moleculer service
+
+**Root Cause**: Missing or incorrect `topic` property in manual proxy service
+
+**Fix for Manual Proxy Services**:
+
+⚠️ **CRITICAL**: The `topic` property is **REQUIRED** for manual proxy services extending BaseProxyService2
+
+```typescript
+// ❌ BAD - Missing topic
+@injectable()
+export class YourProxyService extends BaseProxyService2<IYourModel> implements IYourService {
+    constructor(broker: ServiceBroker, logger: CdmLogger.ILogger) {
+        super(broker, logger);
+    }
+    // Methods won't work - no topic set!
+}
+
+// ✅ GOOD - Topic properly set
+@injectable()
+export class YourProxyService extends BaseProxyService2<IYourModel> implements IYourService {
+    protected topic = MoleculerServiceName.YourService; // REQUIRED!
+
+    constructor(broker: ServiceBroker, logger: CdmLogger.ILogger) {
+        super(broker, logger);
+    }
+}
+
+// ✅ BEST - Use auto-generation (topic handled automatically)
+@injectable()
+export class YourProxyService {
+    constructor(broker: ServiceBroker, logger: CdmLogger.ILogger) {
+        const childLogger = logger.child({ className: 'YourProxyService' });
+        generateProxyMethods<IYourService>(this, YourServiceSchemas, broker, childLogger);
+    }
+}
+export interface YourProxyService extends IYourService {}
+```
+
+**Verify topic matches Moleculer service registration**:
+
+```typescript
+// In proxy service
+protected topic = MoleculerServiceName.YourService;
+
+// Must match in moleculer service
+this.parseServiceSchema({
+    name: MoleculerServiceName.YourService, // Must match!
+    actions,
+    events,
+});
+```
+
+### Issue: Multiple bindings for same service
+
+**Error**: Ambiguous binding resolution
+
+**Fix**:
+
+1. Check only ONE service module is loaded per container
+2. Don't bind same service in multiple modules
+3. Use conditional binding if needed:
+    ```typescript
+    if (useMicroservices) {
+        container.load(YourServiceProxyModule(settings));
+    } else {
+        container.load(YourServiceDbModule(settings));
+    }
+    ```
+
+---
+
+## Tips for Best Results
+
+1. **Always attach the interface file** - this is the source of truth
+2. **Provide the actual service file** if methods have complex signatures
+3. **Reference similar complexity** - mention which example to follow
+4. **Be specific about module name** - helps LLM determine correct paths
+5. **Review section organization** - ensure methods are grouped logically
+
+---
+
+## Advanced: Batch Generation
+
+To generate multiple proxy services:
+
+```bash
+# Create a list file
+cat > services-to-generate.txt << EOF
+UserService user-api
+InvoiceService billing-api
+NotificationService notification-api
+EOF
+
+# Use with your favorite LLM tool
+# Each line: ServiceName module-name
+```
+
+---
+
+## Configuration & Code Generation
+
+### Prerequisites
+
+**Required Package Version**:
+
+```json
+{
+    "devDependencies": {
+        "@common-stack/graphql-codegen-zod-schemas": "^7.2.1-alpha.21"
+    }
+}
+```
+
+**Minimum Version**: `7.2.1-alpha.21` or higher
+
+This version includes:
+
+- Support for `constEnums` configuration
+- Proper handling of `zodImportPath`
+- Export as `@common-stack` scoped package
+- GraphQL and Service schema generation plugins
+
+**Installation**:
+
+```bash
+yarn add -D @common-stack/graphql-codegen-zod-schemas@^7.2.1-alpha.21
+```
+
+### GraphQL Codegen Plugin Configuration
+
+The project uses `@common-stack/graphql-codegen-zod-schemas` for generating Zod validation schemas from GraphQL schemas. The configuration is centralized in `cdecode-config.json`.
+
+**Configuration File**: `cdecode-config.json` (root level)
+
+This file contains ALL project code generation and automation configuration. Key sections:
+
+1. **`servers`**: Frontend and backend server config paths
+2. **`codegen`**: GraphQL code generation configuration (including Zod schemas)
+3. **`serviceSchemas`**: TypeScript service interface Zod schema generation
+4. **`updateDependencies`**: Dependency synchronization rules
+5. **`updateDependencyVersion`**: Version management across packages
+6. **`sortPackageJson`**: Package.json formatting rules
+7. **`deployVersionUpdate`**: Deployment version tracking
+8. **`projectPaths`**: Project structure paths
+
+**Complete Configuration Structure** (`cdecode-config.json`):
+
+```json
+{
+    "servers": ["servers/frontend-server/config.json", "servers/backend-server/config.json"],
+    "codegen": {
+        "outputFile": "codegen.ts",
+        "rootSchema": "node_modules/@common-stack/graphql-api/root-schema.graphqls",
+        "fullConfig": {
+            "overwrite": true,
+            "schema": ["$PRIMARY_SCHEMA_PLACEHOLDER$"],
+            "hooks": {
+                "afterAllFileWrite": [
+                    "node scripts/fix-enum-references.js",
+                    "node scripts/generate-all-service-schemas.js"
+                ]
+            },
+            "generates": {
+                "packages/common/src/generated/generated-zod-schemas.ts": {
+                    "schema": "%discoveredSchemas%",
+                    "config": {
+                        "enumsAsTypes": true,
+                        "enumValues": {
+                            "ConfigurationScope": "@workbench-stack/core/lib/interfaces/configuration/configuration.js#ConfigurationScope",
+                            "ConfigurationTarget": "../configuration#ConfigurationTarget"
+                        },
+                        "constEnums": {
+                            "ConfigurationScope": [1, 2, 3, 4],
+                            "ConfigurationTarget": [1, 2, 3, 4, 5, 6, 7]
+                        },
+                        "zodImportPath": "zod"
+                    },
+                    "plugins": ["@common-stack/codegen-zod/graphql"]
+                }
+            }
+        }
+    },
+    "serviceSchemas": {
+        "servicesDir": "packages/common/src/services",
+        "outputFile": "packages/common/src/generated/service-schemas.ts",
+        "skipServices": [
+            "AuthBackendClient",
+            "PubSub",
+            "RedisCacheManager",
+            "InngestClient",
+            "JSONContributionRegistry",
+            "PageStore",
+            "PublisherEventService"
+        ],
+        "knownEnums": [],
+        "constEnumSchemas": ["ConfigurationTarget", "ConfigurationScope"],
+        "graphqlSchemasPath": "packages/common/src/generated/generated-zod-schemas.ts"
+    }
+}
+```
+
+**Key Configuration Options**:
+
+- **`enumsAsTypes`**: Generates TypeScript enums as union types for better Zod compatibility
+- **`enumValues`**: Maps GraphQL enums to TypeScript module imports for shared enum definitions
+- **`constEnums`**: Defines numeric values for const enums (used for runtime validation)
+- **`zodImportPath`**: Specifies the Zod import path (defaults to "zod")
+- **`hooks.afterAllFileWrite`**: Scripts that run after code generation completes
+- **`plugins`**: Must reference `@common-stack/codegen-zod/graphql` (version ^7.2.1-alpha.21 or higher)
+
+### Service Schema Generation Configuration
+
+The project automatically generates Zod schemas for TypeScript service interfaces using the centralized schema generator from `@common-stack/server-core`. Configuration is in the `serviceSchemas` section of `cdecode-config.json` (shown in the complete configuration above).
+
+**Schema Generator**: `@common-stack/server-core/lib/moleculer-generation/generateAllServiceSchemas.cjs`
+
+This CJS script is published as part of the `@common-stack/server-core` package and shared across all projects.
+
+**Service Schema Configuration Properties**:
+
+- **`servicesDir`**: Directory containing service interface TypeScript files
+- **`outputFile`**: Where to generate the service schemas file
+- **`skipServices`**: Services to exclude from schema generation (external dependencies, special cases)
+- **`knownEnums`**: Additional enums to recognize during schema generation
+- **`constEnumSchemas`**: Enums that should use const enum schemas (numeric values)
+- **`graphqlSchemasPath`**: Path to GraphQL Zod schemas file (for importing shared schemas)
+
+**Automatic Relative Path Calculation**:
+
+The service schema generator automatically calculates the correct relative import path from `outputFile` to `graphqlSchemasPath`. You don't need to specify a separate import path - it's derived automatically.
+
+**Example**:
+
+```typescript
+// Configuration
+{
+  "outputFile": "packages/common/src/generated/service-schemas.ts",
+  "graphqlSchemasPath": "packages/common/src/generated/generated-zod-schemas.ts"
+}
+
+// Generated import (automatically calculated as same directory)
+import { ConfigurationScopeSchema, ConfigurationTargetSchema } from './generated-zod-schemas';
+```
+
+### Running Code Generation
+
+**Generate GraphQL schemas and service schemas**:
+
+```bash
+yarn generateGraphql
+```
+
+This command:
+
+1. Runs GraphQL Codegen to generate TypeScript types and Zod schemas from GraphQL schemas
+2. Fixes enum references in generated files (via `scripts/fix-enum-references.js`)
+3. Generates Zod schemas for all service interfaces (via `scripts/generate-all-service-schemas.js`)
+4. Rebuilds the common package with updated schemas
+
+**Generation happens automatically via hooks** defined in `cdecode-config.json`:
+
+```json
+{
+    "hooks": {
+        "afterAllFileWrite": [
+            "node scripts/fix-enum-references.js",
+            "node node node_modules/@common-stack/codegen-zod/dist/service/generateAllServiceSchemas.js"
+        ]
+    }
+}
+```
+
+### Schema Generation Script
+
+The service schema generator (`@common-stack/server-core/lib/moleculer-generation/generateAllServiceSchemas.cjs`) uses the configuration from `cdecode-config.json` to:
+
+1. **Discover all service interfaces** in the configured services directory
+2. **Parse TypeScript** to extract method signatures and parameter types
+3. **Auto-generate topic** from interface name (e.g., `IProjectService` → `ProjectService`)
+4. **Generate Zod schemas** for each method's parameters
+5. **Import shared schemas** from GraphQL Zod schemas (enums, input types)
+6. **Skip configured services** that shouldn't have schemas generated
+7. **Use const enum schemas** for numeric enums where configured
+8. **Calculate relative import paths** automatically based on file locations
+
+**Script Location**: `node node_modules/@common-stack/codegen-zod/dist/service/generateAllServiceSchemas.js`
+
+**How it works**:
+
+```javascript
+// 1. Load configuration from cdecode-config.json
+const configPath = path.join(__dirname, '../cdecode-config.json');
+const fullConfig = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+const serviceConfig = fullConfig.serviceSchemas || {};
+
+// 2. Calculate relative import path automatically
+function calculateRelativeImportPath() {
+    if (!serviceConfig.outputFile || !serviceConfig.graphqlSchemasPath) {
+        return './generated-zod-schemas';
+    }
+
+    const outputDir = path.dirname(serviceConfig.outputFile);
+    const graphqlSchemaPath = serviceConfig.graphqlSchemasPath;
+
+    // Calculate relative path from output file to GraphQL schemas
+    const relativePath = path.relative(outputDir, graphqlSchemaPath);
+
+    // Remove .ts extension and ensure it starts with ./
+    const withoutExt = relativePath.replace(/\.ts$/, '');
+    return withoutExt.startsWith('.') ? withoutExt : `./${withoutExt}`;
+}
+
+const GRAPHQL_SCHEMAS_IMPORT_PATH = calculateRelativeImportPath();
+
+// 3. Discover GraphQL Zod types from generated file
+function discoverGraphQLZodTypes() {
+    const graphqlSchemaFile = path.join(__dirname, '..', serviceConfig.graphqlSchemasPath);
+    const content = fs.readFileSync(graphqlSchemaFile, 'utf8');
+    const graphqlTypes = new Set();
+
+    // Find all exported schema functions like: export function UserInputSchema()
+    const schemaFunctionPattern = /export function ([A-Z][a-zA-Z0-9]+)Schema\(\)/g;
+    let match;
+
+    while ((match = schemaFunctionPattern.exec(content)) !== null) {
+        const schemaName = match[1];
+        // Convert schema name to interface name (add 'I' prefix)
+        const interfaceName = 'I' + schemaName;
+        graphqlTypes.add(interfaceName);
+    }
+
+    return graphqlTypes;
+}
+
+// 4. Find all service interfaces (excluding skipServices)
+function findServiceInterfaces() {
+    const files = fs.readdirSync(SERVICES_DIR).filter((f) => f.endsWith('.ts'));
+    const services = [];
+
+    files.forEach((file) => {
+        const content = fs.readFileSync(path.join(SERVICES_DIR, file), 'utf8');
+        const interfaceMatch = content.match(/export interface (I[A-Z][a-zA-Z0-9]*Service)/);
+
+        if (interfaceMatch) {
+            const serviceName = interfaceMatch[1];
+            if (!SKIP_SERVICES.includes(serviceName.replace(/^I/, ''))) {
+                services.push({ name: serviceName, file, path: filePath });
+            }
+        }
+    });
+
+    return services;
+}
+
+// 5. Parse TypeScript to extract method signatures
+function parseServiceInterface(filePath, interfaceName) {
+    const sourceFile = ts.createSourceFile(filePath, sourceCode, ts.ScriptTarget.Latest, true);
+
+    // Visit AST nodes to find interface and extract methods
+    // Returns: { methods: [...], usedEnums: [...] }
+}
+
+// 6. Generate Zod schemas for each parameter type
+function generateZodType(paramType, isOptional, paramName) {
+    // Handle arrays: Type[] -> z.array(...)
+    // Handle primitives: string -> z.string()
+    // Handle GraphQL types: IUserInput -> UserInputSchema()
+    // Handle enums: TokenType -> z.nativeEnum(TokenType)
+    // Handle const enums: ConfigurationScope -> ConfigurationScopeSchema()
+    // Default: z.object({}).passthrough()
+}
+```
+
+**Configuration Properties Used**:
+
+- `serviceSchemas.servicesDir`: Where to find service interface files
+- `serviceSchemas.outputFile`: Where to write generated schemas
+- `serviceSchemas.skipServices`: Services to exclude from generation
+- `serviceSchemas.knownEnums`: Regular enums to import
+- `serviceSchemas.constEnumSchemas`: Const enums to use schema functions for
+- `serviceSchemas.graphqlSchemasPath`: Source of GraphQL Zod schemas to import
+
+**What gets generated**:
+
+```typescript
+// Example generated service schema (from IAccountService interface)
+export const AccountServiceSchemas = {
+    /** Moleculer service topic/name - safe for minification */
+    topic: 'AccountService' as const, // Auto-derived from IAccountService
+
+    findAccountById: z.object({
+        id: z.string(),
+    }),
+    createAccount: z.object({
+        account: AccountInputSchema, // From GraphQL schemas
+    }),
+    updateUserAccount: z.object({
+        userId: z.string(),
+        input: UserAccountUpdateInputSchema, // From GraphQL schemas
+    }),
+};
+```
+
+### Benefits of Centralized Configuration
+
+1. **Single Source of Truth**: All code generation config in one file
+2. **Easy Customization**: Change paths, add services, modify schemas without editing scripts
+3. **Automatic Path Resolution**: No manual relative path calculations needed
+4. **Type Safety**: Generated schemas provide runtime validation for Moleculer actions
+5. **Consistency**: Same configuration used across all code generation tools
+6. **Plugin Publishing Ready**: Clean separation of plugin code and project configuration
+
+### Configuration Migration Notes
+
+**Recent Changes** (October 2025):
+
+1. **Plugin renamed**: `@adminide-stack/graphql-codegen-zod-schemas` → `@common-stack/graphql-codegen-zod-schemas`
+2. **Version requirement**: Must use `^7.2.1-alpha.21` or higher
+3. **Plugin path changed**: `./packages/graphql-codegen-zod-schemas/dist/graphql.js` → `@common-stack/codegen-zod/graphql`
+4. **Service schema config moved**: Separate `service-schemas.config.js` → `cdecode-config.json` (serviceSchemas section)
+5. **Automatic path calculation**: Import paths now derived from file paths (no separate `graphqlSchemasImportPath` needed)
+
+**If updating from older configuration**:
+
+1. **Install/upgrade the plugin**:
+
+    ```bash
+    yarn add -D @common-stack/graphql-codegen-zod-schemas@^7.2.1-alpha.21
+    ```
+
+2. **Update plugin reference** in `cdecode-config.json`:
+
+    ```json
+    {
+        "plugins": ["@common-stack/codegen-zod/graphql"]
+    }
+    ```
+
+3. **Move service schema config** to `serviceSchemas` section of `cdecode-config.json`:
+
+    ```json
+    {
+        "serviceSchemas": {
+            "servicesDir": "packages/common/src/services",
+            "outputFile": "packages/common/src/generated/service-schemas.ts",
+            "graphqlSchemasPath": "packages/common/src/generated/generated-zod-schemas.ts",
+            ...
+        }
+    }
+    ```
+
+4. **Remove deprecated properties**:
+    - Delete `graphqlSchemasImportPath` from serviceSchemas (now calculated automatically)
+    - Delete `service-schemas.config.js` file if it exists
+
+5. **Verify the setup**:
+    ```bash
+    yarn generateGraphql
+    yarn build
+    ```
+
+**Breaking Changes**:
+
+- Old plugin path `./packages/graphql-codegen-zod-schemas/dist/graphql.js` will no longer work
+- Service schema generation now requires configuration in `cdecode-config.json`
+- Minimum version requirement: `@common-stack/graphql-codegen-zod-schemas@^7.2.1-alpha.21`
+
+---
+
+## Version
+
+- **v1.2.0** (2025-10-26): Added configuration and code generation documentation, plugin rename updates
+- **v1.1.0** (2024-10-24): Added container module pattern and DI registration guidance
+- **v1.0.0** (2024-10-24): Initial LLM prompt template based on 4 implemented examples