Syncable Entity: Integration (Step 5/6)

Purpose: Wire everything together, register in modules, create services and resolvers.

When to use: After completing Steps 1-4 (all previous steps). Required before testing.

Quick Start

This step:

Registers services in 3 NestJS modules
Creates service layer (returns flat entities)
Creates resolver layer (converts flat → DTO)
Uses exception interceptor for GraphQL

Key principle: Services return flat entities, resolvers transpile flat → DTO.

Step 1: Register in Builder Module

File: src/engine/workspace-manager/workspace-migration/workspace-migration-builder/workspace-migration-builder.module.ts

import { WorkspaceMigrationMyEntityActionsBuilderService } from 'src/engine/workspace-manager/workspace-migration/workspace-migration-builder/builders/my-entity/workspace-migration-my-entity-actions-builder.service';

@Module({
  imports: [
    // ... existing imports
  ],
  providers: [
    // ... existing providers
    WorkspaceMigrationMyEntityActionsBuilderService,
  ],
  exports: [
    // ... existing exports
    WorkspaceMigrationMyEntityActionsBuilderService,
  ],
})
export class WorkspaceMigrationBuilderModule {}

Important: Add to both providers AND exports (builder needs to be exported for orchestrator).

Step 2: Register in Validators Module

File: src/engine/workspace-manager/workspace-migration/workspace-migration-builder/validators/workspace-migration-builder-validators.module.ts

import { FlatMyEntityValidatorService } from 'src/engine/workspace-manager/workspace-migration/workspace-migration-builder/validators/services/flat-my-entity-validator.service';

@Module({
  imports: [
    // ... existing imports
  ],
  providers: [
    // ... existing providers
    FlatMyEntityValidatorService,
  ],
  exports: [
    // ... existing exports
    FlatMyEntityValidatorService,
  ],
})
export class WorkspaceMigrationBuilderValidatorsModule {}

Step 3: Register Action Handlers

File: src/engine/workspace-manager/workspace-migration/workspace-migration-runner/action-handlers/workspace-schema-migration-runner-action-handlers.module.ts

import { CreateMyEntityActionHandlerService } from 'src/engine/workspace-manager/workspace-migration/workspace-migration-runner/action-handlers/my-entity/services/create-my-entity-action-handler.service';
import { UpdateMyEntityActionHandlerService } from 'src/engine/workspace-manager/workspace-migration/workspace-migration-runner/action-handlers/my-entity/services/update-my-entity-action-handler.service';
import { DeleteMyEntityActionHandlerService } from 'src/engine/workspace-manager/workspace-migration/workspace-migration-runner/action-handlers/my-entity/services/delete-my-entity-action-handler.service';

@Module({
  imports: [
    // ... existing imports
  ],
  providers: [
    // ... existing providers
    CreateMyEntityActionHandlerService,
    UpdateMyEntityActionHandlerService,
    DeleteMyEntityActionHandlerService,
  ],
  exports: [
    // ... existing exports (action handlers typically not exported)
  ],
})
export class WorkspaceSchemaMigrationRunnerActionHandlersModule {}

Note: Action handlers are typically only in providers, not exports.

Step 4: Create Service Layer

File: src/engine/metadata-modules/my-entity/my-entity.service.ts

import { Injectable } from '@nestjs/common';
import { isDefined } from 'twenty-shared/utils';

import { type FlatMyEntity } from 'src/engine/metadata-modules/flat-my-entity/types/flat-my-entity.type';
import { WorkspaceManyOrAllFlatEntityMapsCacheService } from 'src/engine/metadata-modules/flat-entity/services/workspace-many-or-all-flat-entity-maps-cache.service';
import { findFlatEntityByIdInFlatEntityMapsOrThrow } from 'src/engine/metadata-modules/flat-entity/utils/find-flat-entity-by-id-in-flat-entity-maps-or-throw.util';
import { fromCreateMyEntityInputToUniversalFlatMyEntity } from 'src/engine/metadata-modules/flat-my-entity/utils/from-create-my-entity-input-to-universal-flat-my-entity.util';
import { WorkspaceMigrationBuilderException } from 'src/engine/workspace-manager/workspace-migration/exceptions/workspace-migration-builder-exception';
import { WorkspaceMigrationValidateBuildAndRunService } from 'src/engine/workspace-manager/workspace-migration/services/workspace-migration-validate-build-and-run-service';

@Injectable()
export class MyEntityService {
  constructor(
    private readonly workspaceMigrationValidateBuildAndRunService: WorkspaceMigrationValidateBuildAndRunService,
    private readonly workspaceManyOrAllFlatEntityMapsCacheService: WorkspaceManyOrAllFlatEntityMapsCacheService,
  ) {}

  async create(input: CreateMyEntityInput, workspaceId: string): Promise<FlatMyEntity> {
    // 1. Transform input to universal flat entity
    const universalFlatMyEntityToCreate = fromCreateMyEntityInputToUniversalFlatMyEntity({
      input,
      workspaceId,
    });

    // 2. Validate, build, and run
    const result =
      await this.workspaceMigrationValidateBuildAndRunService.validateBuildAndRunWorkspaceMigration(
        {
          allFlatEntityOperationByMetadataName: {
            myEntity: {
              flatEntityToCreate: [universalFlatMyEntityToCreate],
              flatEntityToDelete: [],
              flatEntityToUpdate: [],
            },
          },
          workspaceId,
          isSystemBuild: false,
        },
      );

    // 3. Throw if validation failed
    if (isDefined(result)) {
      throw new WorkspaceMigrationBuilderException(
        result,
        'Validation errors occurred while creating entity',
      );
    }

    // 4. Return freshly cached flat entity
    const { flatMyEntityMaps } =
      await this.workspaceManyOrAllFlatEntityMapsCacheService.getOrRecomputeManyOrAllFlatEntityMaps(
        {
          workspaceId,
          flatMapsKeys: ['flatMyEntityMaps'],
        },
      );

    return findFlatEntityByIdInFlatEntityMapsOrThrow({
      flatEntityId: universalFlatMyEntityToCreate.id,
      flatEntityMaps: flatMyEntityMaps,
    });
  }
}

Service pattern:

Transform input → universal flat entity
Call validateBuildAndRunWorkspaceMigration
Throw if validation errors
Return flat entity (not DTO)

Step 5: Create Resolver Layer

File: src/engine/metadata-modules/my-entity/my-entity.resolver.ts

import { UseInterceptors } from '@nestjs/common';
import { Args, Mutation, Resolver } from '@nestjs/graphql';

import { WorkspaceMigrationGraphqlApiExceptionInterceptor } from 'src/engine/workspace-manager/workspace-migration/interceptors/workspace-migration-graphql-api-exception.interceptor';
import { MyEntityService } from 'src/engine/metadata-modules/my-entity/my-entity.service';
import { fromFlatMyEntityToMyEntityDto } from 'src/engine/metadata-modules/my-entity/utils/from-flat-my-entity-to-my-entity-dto.util';

@Resolver(() => MyEntityDto)
@UseInterceptors(WorkspaceMigrationGraphqlApiExceptionInterceptor)
export class MyEntityResolver {
  constructor(private readonly myEntityService: MyEntityService) {}

  @Mutation(() => MyEntityDto)
  async createMyEntity(
    @Args('input') input: CreateMyEntityInput,
    @Workspace() { id: workspaceId }: Workspace,
  ): Promise<MyEntityDto> {
    // Service returns flat entity
    const flatMyEntity = await this.myEntityService.create(input, workspaceId);
    
    // Resolver converts flat entity to DTO
    return fromFlatMyEntityToMyEntityDto(flatMyEntity);
  }

  @Mutation(() => MyEntityDto)
  async updateMyEntity(
    @Args('id') id: string,
    @Args('input') input: UpdateMyEntityInput,
    @Workspace() { id: workspaceId }: Workspace,
  ): Promise<MyEntityDto> {
    const flatMyEntity = await this.myEntityService.update(id, input, workspaceId);
    return fromFlatMyEntityToMyEntityDto(flatMyEntity);
  }

  @Mutation(() => Boolean)
  async deleteMyEntity(
    @Args('id') id: string,
    @Workspace() { id: workspaceId }: Workspace,
  ) {
    await this.myEntityService.delete(id, workspaceId);
    return true;
  }
}

Resolver responsibilities:

Receives flat entities from service
Converts flat → DTO using conversion utility
Returns DTOs to GraphQL API
Uses exception interceptor for error formatting

Step 6: Flat-to-DTO Conversion

File: src/engine/metadata-modules/my-entity/utils/from-flat-my-entity-to-my-entity-dto.util.ts

import { type FlatMyEntity } from 'src/engine/metadata-modules/flat-my-entity/types/flat-my-entity.type';
import { type MyEntityDto } from 'src/engine/metadata-modules/my-entity/dtos/my-entity.dto';

export const fromFlatMyEntityToMyEntityDto = (
  flatMyEntity: FlatMyEntity,
): MyEntityDto => {
  return {
    id: flatMyEntity.id,
    name: flatMyEntity.name,
    label: flatMyEntity.label,
    description: flatMyEntity.description,
    isCustom: flatMyEntity.isCustom,
    createdAt: flatMyEntity.createdAt,
    updatedAt: flatMyEntity.updatedAt,
    // Convert foreign key IDs to relation objects if needed
    // parentEntity: flatMyEntity.parentEntityId ? { id: flatMyEntity.parentEntityId } : null,
  };
};

Layer Responsibilities

Layer	Input	Output	Responsibility
Service	Input DTO	Flat Entity	Business logic, validation orchestration
Resolver	Service result	DTO	Flat → DTO conversion, GraphQL exposure

Service Layer:

Works with flat entities internally
Returns FlatMyEntity type
No knowledge of DTOs or GraphQL types

Resolver Layer:

Receives flat entities from service
Converts flat entities to DTOs
Returns DTOs to GraphQL API

Exception Interceptor

The WorkspaceMigrationGraphqlApiExceptionInterceptor automatically handles:

FlatEntityMapsException → Converts to GraphQL errors (NotFoundError, etc.)
WorkspaceMigrationBuilderException → Formats validation errors with i18n
WorkspaceMigrationRunnerException → Formats runner errors

What it does:

Catches exceptions and formats for API responses
Translates error messages based on user locale
Ensures consistent error structure for frontend

Checklist

Before moving to Step 6 (Testing):

Builder registered in builder module (providers + exports)
Validator registered in validators module (providers + exports)
All 3 action handlers registered in action handlers module (providers)
Service layer created
Service returns flat entities (not DTOs)
Resolver layer created
Resolver uses exception interceptor
Resolver converts flat → DTO
Flat-to-DTO conversion utility created

Next Step

Once integration is complete, proceed to (MANDATORY): Syncable Entity: Integration Testing (Step 6/6)

For complete workflow, see @creating-syncable-entity rule.

syncable-entity-integration