👥 User Management - Reference Implementation

This module is the definitive reference implementation for GoGrab Space modules, demonstrating all capabilities of the module system.

📋 Module Information

🏗️ Architecture

Complete Directory Structure

libs/core/user-management/
├── src/
│   ├── lib/
│   │   ├── components/           # UI Components
│   │   │   ├── user-list/
│   │   │   ├── user-card/
│   │   │   ├── user-detail/
│   │   │   ├── user-form/
│   │   │   └── user-filters/
│   │   ├── embeddables/          # Embeddable Widgets
│   │   │   └── user-list-widget/
│   │   ├── actions/              # Public Actions
│   │   │   ├── navigate-to-user.action.ts
│   │   │   ├── create-user.action.ts
│   │   │   ├── update-user.action.ts
│   │   │   ├── delete-user.action.ts
│   │   │   └── bulk-update-roles.action.ts
│   │   ├── services/             # Module Services
│   │   │   ├── user-api.service.ts
│   │   │   └── user.service.ts
│   │   ├── data/                 # Data Layer
│   │   │   └── repositories/
│   │   │       ├── user.repository.ts
│   │   │       └── role.repository.ts
│   │   ├── state/                # State Management (NGXS)
│   │   │   ├── user.state.ts
│   │   │   └── user.actions.ts
│   │   ├── events/               # Domain Events
│   │   │   └── user.events.ts
│   │   ├── models/               # Types & Interfaces
│   │   │   ├── user.model.ts
│   │   │   └── user-api.model.ts
│   │   ├── mocks/                # Mock Data
│   │   │   ├── user-mock-api.ts
│   │   │   └── user-mock-data.ts
│   │   ├── user-management.module.ts
│   │   └── user-management.routes.ts
│   ├── index.ts
│   └── test-setup.ts

🎯 Key Features

1. Complete CRUD Operations

• Create: Full user creation with role assignment
• Read: List, detail views with filtering
• Update: Individual and bulk updates
• Delete: Soft/hard delete with confirmation

2. Embeddable Widget

UserListWidgetComponent - A compact, reusable widget for embedding in dashboards.

Inputs:

Outputs:

Usage:

<lib-user-list-widget
  [limit]="5"
  [roleFilter]="'admin'"
  (userSelected)="handleUserSelected($event)"
/>

3. Public Actions (5 Total)

All actions use @PublicAction decorator and implement ExecutableAction<T>:

1. NavigateToUserAction (users:navigate-to-user)

   • Navigate to user detail or edit page
   • Category: navigation

2. CreateUserAction (users:create-user)

   • Create new user with validation
   • Category: crud

3. UpdateUserAction (users:update-user)

   • Update existing user
   • Category: crud

4. DeleteUserAction (users:delete-user)

   • Delete user (soft/hard)
   • Category: crud

5. BulkUpdateRolesAction (users:bulk-update-roles)

   • Batch role assignment
   • Category: workflow

💡 Implementation Patterns

RxJS-First Architecture

// All actions use Observable-based execution
execute(params: Input, context: ActionContext): Observable<Output> {
  return this.validate(params).pipe(
    switchMap(isValid => {
      if (!isValid) return of({ success: false, error: 'Invalid params' });
      
      return this.userService.createUser(params).pipe(
        tap(() => this.logger.info('User created')),
        map(user => ({ success: true, userId: user.id })),
        catchError(err => of({ success: false, error: err.message }))
      );
    })
  );
}

State Management (NGXS)

@State<UserStateModel>({ name: 'users', defaults: initialState })
export class UserState {
  @Action(UserActions.LoadUsers)
  loadUsers(ctx: StateContext<UserStateModel>) {
    return this.userService.getUsers().pipe(
      tap(users => ctx.patchState({ users, loading: false }))
    );
  }
}

🧪 Testing

Test Coverage

• ✅ 131 tests passing
• ✅ 100% action coverage
• ✅ Integration with NGXS
• ✅ Mock API functional

Example Test

describe('CreateUserAction', () => {
  it('should create user successfully', async () => {
    const result = await lastValueFrom(
      action.execute({ email: '[email protected]', ... }, context)
    );
    
    expect(result.success).toBe(true);
    expect(result.userId).toBeDefined();
  });
});

📚 Related Documentation

• Module Creation Guide
• Action System Architecture
• Embeddable Components Best Practices

Last Updated: December 3, 2025 Status: ✅ Production Reference Session ID: 3