Front Extensibility: Introduce Front Component Entity (#17175)

As part of the extensibility effort, we are introducing a new engine entity called "Front Component". This represents a dynamic react component that will be rendered in CommandMenu actions or in PageLayout widgets This PR introduce the entity and all the necessary boilerplate to make it syncable and cachable in the engine
2026-01-16 17:23:46 +01:00
parent fe0d84c97e
commit 5fc4e810f7
68 changed files with 2042 additions and 5 deletions
@@ -0,0 +1,18 @@
+import { Field, InputType } from '@nestjs/graphql';
+
+import { IsNotEmpty, IsOptional, IsString, IsUUID } from 'class-validator';
+
+import { UUIDScalarType } from 'src/engine/api/graphql/workspace-schema-builder/graphql-types/scalars';
+
+@InputType()
+export class CreateFrontComponentInput {
+  @IsUUID()
+  @IsOptional()
+  @Field(() => UUIDScalarType, { nullable: true })
+  id?: string;
+
+  @IsString()
+  @IsNotEmpty()
+  @Field()
+  name: string;
+}
@@ -0,0 +1,31 @@
+import { Field, HideField, ObjectType } from '@nestjs/graphql';
+
+import { IsDateString, IsNotEmpty, IsString, IsUUID } from 'class-validator';
+
+import { UUIDScalarType } from 'src/engine/api/graphql/workspace-schema-builder/graphql-types/scalars';
+
+@ObjectType('FrontComponent')
+export class FrontComponentDTO {
+  @IsUUID()
+  @IsNotEmpty()
+  @Field(() => UUIDScalarType)
+  id: string;
+
+  @IsString()
+  @Field()
+  name: string;
+
+  @HideField()
+  workspaceId: string;
+
+  @Field(() => UUIDScalarType)
+  applicationId: string;
+
+  @IsDateString()
+  @Field()
+  createdAt: Date;
+
+  @IsDateString()
+  @Field()
+  updatedAt: Date;
+}
@@ -0,0 +1,37 @@
+import { Field, InputType } from '@nestjs/graphql';
+
+import { Type } from 'class-transformer';
+import {
+  IsNotEmpty,
+  IsOptional,
+  IsString,
+  IsUUID,
+  ValidateNested,
+} from 'class-validator';
+
+import { UUIDScalarType } from 'src/engine/api/graphql/workspace-schema-builder/graphql-types/scalars';
+
+@InputType()
+export class UpdateFrontComponentInputUpdates {
+  @IsOptional()
+  @IsString()
+  @Field({ nullable: true })
+  name?: string;
+}
+
+@InputType()
+export class UpdateFrontComponentInput {
+  @IsUUID()
+  @IsNotEmpty()
+  @Field(() => UUIDScalarType, {
+    description: 'The id of the front component to update',
+  })
+  id: string;
+
+  @Type(() => UpdateFrontComponentInputUpdates)
+  @ValidateNested()
+  @Field(() => UpdateFrontComponentInputUpdates, {
+    description: 'The front component fields to update',
+  })
+  update: UpdateFrontComponentInputUpdates;
+}
@@ -0,0 +1,27 @@
+import {
+  Column,
+  CreateDateColumn,
+  Entity,
+  PrimaryGeneratedColumn,
+  UpdateDateColumn,
+} from 'typeorm';
+
+import { SyncableEntityRequired } from 'src/engine/workspace-manager/types/syncable-entity-required.interface';
+
+@Entity('frontComponent')
+export class FrontComponentEntity
+  extends SyncableEntityRequired
+  implements Required<FrontComponentEntity>
+{
+  @PrimaryGeneratedColumn('uuid')
+  id: string;
+
+  @Column({ nullable: false })
+  name: string;
+
+  @CreateDateColumn({ type: 'timestamptz' })
+  createdAt: Date;
+
+  @UpdateDateColumn({ type: 'timestamptz' })
+  updatedAt: Date;
+}
@@ -0,0 +1,40 @@
+import { type MessageDescriptor } from '@lingui/core';
+import { msg } from '@lingui/core/macro';
+import { assertUnreachable } from 'twenty-shared/utils';
+
+import { CustomException } from 'src/utils/custom-exception';
+
+export enum FrontComponentExceptionCode {
+  FRONT_COMPONENT_NOT_FOUND = 'FRONT_COMPONENT_NOT_FOUND',
+  FRONT_COMPONENT_ALREADY_EXISTS = 'FRONT_COMPONENT_ALREADY_EXISTS',
+  INVALID_FRONT_COMPONENT_INPUT = 'INVALID_FRONT_COMPONENT_INPUT',
+}
+
+const getFrontComponentExceptionUserFriendlyMessage = (
+  code: FrontComponentExceptionCode,
+) => {
+  switch (code) {
+    case FrontComponentExceptionCode.FRONT_COMPONENT_NOT_FOUND:
+      return msg`Front component not found.`;
+    case FrontComponentExceptionCode.FRONT_COMPONENT_ALREADY_EXISTS:
+      return msg`A front component with this name already exists.`;
+    case FrontComponentExceptionCode.INVALID_FRONT_COMPONENT_INPUT:
+      return msg`Invalid front component input.`;
+    default:
+      assertUnreachable(code);
+  }
+};
+
+export class FrontComponentException extends CustomException<FrontComponentExceptionCode> {
+  constructor(
+    message: string,
+    code: FrontComponentExceptionCode,
+    { userFriendlyMessage }: { userFriendlyMessage?: MessageDescriptor } = {},
+  ) {
+    super(message, code, {
+      userFriendlyMessage:
+        userFriendlyMessage ??
+        getFrontComponentExceptionUserFriendlyMessage(code),
+    });
+  }
+}
@@ -0,0 +1,29 @@
+import { Module } from '@nestjs/common';
+
+import { ApplicationModule } from 'src/engine/core-modules/application/application.module';
+import { WorkspaceManyOrAllFlatEntityMapsCacheModule } from 'src/engine/metadata-modules/flat-entity/services/workspace-many-or-all-flat-entity-maps-cache.module';
+import { FlatFrontComponentModule } from 'src/engine/metadata-modules/flat-front-component/flat-front-component.module';
+import { FrontComponentResolver } from 'src/engine/metadata-modules/front-component/front-component.resolver';
+import { FrontComponentService } from 'src/engine/metadata-modules/front-component/front-component.service';
+import { FrontComponentGraphqlApiExceptionInterceptor } from 'src/engine/metadata-modules/front-component/interceptors/front-component-graphql-api-exception.interceptor';
+import { PermissionsModule } from 'src/engine/metadata-modules/permissions/permissions.module';
+import { WorkspaceMigrationBuilderGraphqlApiExceptionInterceptor } from 'src/engine/workspace-manager/workspace-migration/interceptors/workspace-migration-builder-graphql-api-exception.interceptor';
+import { WorkspaceMigrationModule } from 'src/engine/workspace-manager/workspace-migration/workspace-migration.module';
+
+@Module({
+  imports: [
+    WorkspaceManyOrAllFlatEntityMapsCacheModule,
+    WorkspaceMigrationModule,
+    ApplicationModule,
+    PermissionsModule,
+    FlatFrontComponentModule,
+  ],
+  providers: [
+    FrontComponentService,
+    FrontComponentResolver,
+    FrontComponentGraphqlApiExceptionInterceptor,
+    WorkspaceMigrationBuilderGraphqlApiExceptionInterceptor,
+  ],
+  exports: [FrontComponentService],
+})
+export class FrontComponentModule {}
@@ -0,0 +1,71 @@
+import { UseGuards, UseInterceptors } from '@nestjs/common';
+import { Args, Mutation, Query, Resolver } from '@nestjs/graphql';
+
+import { PermissionFlagType } from 'twenty-shared/constants';
+
+import { UUIDScalarType } from 'src/engine/api/graphql/workspace-schema-builder/graphql-types/scalars';
+import { WorkspaceEntity } from 'src/engine/core-modules/workspace/workspace.entity';
+import { AuthWorkspace } from 'src/engine/decorators/auth/auth-workspace.decorator';
+import { NoPermissionGuard } from 'src/engine/guards/no-permission.guard';
+import { SettingsPermissionGuard } from 'src/engine/guards/settings-permission.guard';
+import { WorkspaceAuthGuard } from 'src/engine/guards/workspace-auth.guard';
+import { CreateFrontComponentInput } from 'src/engine/metadata-modules/front-component/dtos/create-front-component.input';
+import { FrontComponentDTO } from 'src/engine/metadata-modules/front-component/dtos/front-component.dto';
+import { UpdateFrontComponentInput } from 'src/engine/metadata-modules/front-component/dtos/update-front-component.input';
+import { FrontComponentService } from 'src/engine/metadata-modules/front-component/front-component.service';
+import { FrontComponentGraphqlApiExceptionInterceptor } from 'src/engine/metadata-modules/front-component/interceptors/front-component-graphql-api-exception.interceptor';
+import { WorkspaceMigrationBuilderGraphqlApiExceptionInterceptor } from 'src/engine/workspace-manager/workspace-migration/interceptors/workspace-migration-builder-graphql-api-exception.interceptor';
+
+@UseGuards(WorkspaceAuthGuard)
+@UseInterceptors(
+  WorkspaceMigrationBuilderGraphqlApiExceptionInterceptor,
+  FrontComponentGraphqlApiExceptionInterceptor,
+)
+@Resolver(() => FrontComponentDTO)
+export class FrontComponentResolver {
+  constructor(private readonly frontComponentService: FrontComponentService) {}
+
+  @Query(() => [FrontComponentDTO])
+  @UseGuards(NoPermissionGuard)
+  async frontComponents(
+    @AuthWorkspace() workspace: WorkspaceEntity,
+  ): Promise<FrontComponentDTO[]> {
+    return await this.frontComponentService.findAll(workspace.id);
+  }
+
+  @Query(() => FrontComponentDTO, { nullable: true })
+  @UseGuards(NoPermissionGuard)
+  async frontComponent(
+    @Args('id', { type: () => UUIDScalarType }) id: string,
+    @AuthWorkspace() workspace: WorkspaceEntity,
+  ): Promise<FrontComponentDTO | null> {
+    return await this.frontComponentService.findById(id, workspace.id);
+  }
+
+  @Mutation(() => FrontComponentDTO)
+  @UseGuards(SettingsPermissionGuard(PermissionFlagType.APPLICATIONS))
+  async createFrontComponent(
+    @Args('input') input: CreateFrontComponentInput,
+    @AuthWorkspace() workspace: WorkspaceEntity,
+  ): Promise<FrontComponentDTO> {
+    return await this.frontComponentService.create(input, workspace.id);
+  }
+
+  @Mutation(() => FrontComponentDTO)
+  @UseGuards(SettingsPermissionGuard(PermissionFlagType.APPLICATIONS))
+  async updateFrontComponent(
+    @Args('input') input: UpdateFrontComponentInput,
+    @AuthWorkspace() workspace: WorkspaceEntity,
+  ): Promise<FrontComponentDTO> {
+    return await this.frontComponentService.update(input, workspace.id);
+  }
+
+  @Mutation(() => FrontComponentDTO)
+  @UseGuards(SettingsPermissionGuard(PermissionFlagType.APPLICATIONS))
+  async deleteFrontComponent(
+    @Args('id', { type: () => UUIDScalarType }) id: string,
+    @AuthWorkspace() workspace: WorkspaceEntity,
+  ): Promise<FrontComponentDTO> {
+    return await this.frontComponentService.delete(id, workspace.id);
+  }
+}
@@ -0,0 +1,237 @@
+import { Injectable } from '@nestjs/common';
+
+import { isDefined } from 'twenty-shared/utils';
+
+import { ApplicationService } from 'src/engine/core-modules/application/application.service';
+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 { findFlatEntityByIdInFlatEntityMaps } from 'src/engine/metadata-modules/flat-entity/utils/find-flat-entity-by-id-in-flat-entity-maps.util';
+import { fromCreateFrontComponentInputToFlatFrontComponentToCreate } from 'src/engine/metadata-modules/flat-front-component/utils/from-create-front-component-input-to-flat-front-component-to-create.util';
+import { fromDeleteFrontComponentInputToFlatFrontComponentOrThrow } from 'src/engine/metadata-modules/flat-front-component/utils/from-delete-front-component-input-to-flat-front-component-or-throw.util';
+import { fromFlatFrontComponentToFrontComponentDto } from 'src/engine/metadata-modules/flat-front-component/utils/from-flat-front-component-to-front-component-dto.util';
+import { fromUpdateFrontComponentInputToFlatFrontComponentToUpdateOrThrow } from 'src/engine/metadata-modules/flat-front-component/utils/from-update-front-component-input-to-flat-front-component-to-update-or-throw.util';
+import { type CreateFrontComponentInput } from 'src/engine/metadata-modules/front-component/dtos/create-front-component.input';
+import { type FrontComponentDTO } from 'src/engine/metadata-modules/front-component/dtos/front-component.dto';
+import { type UpdateFrontComponentInput } from 'src/engine/metadata-modules/front-component/dtos/update-front-component.input';
+import {
+  FrontComponentException,
+  FrontComponentExceptionCode,
+} from 'src/engine/metadata-modules/front-component/front-component.exception';
+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 FrontComponentService {
+  constructor(
+    private readonly workspaceMigrationValidateBuildAndRunService: WorkspaceMigrationValidateBuildAndRunService,
+    private readonly workspaceManyOrAllFlatEntityMapsCacheService: WorkspaceManyOrAllFlatEntityMapsCacheService,
+    private readonly applicationService: ApplicationService,
+  ) {}
+
+  async findAll(workspaceId: string): Promise<FrontComponentDTO[]> {
+    const { flatFrontComponentMaps } =
+      await this.workspaceManyOrAllFlatEntityMapsCacheService.getOrRecomputeManyOrAllFlatEntityMaps(
+        {
+          workspaceId,
+          flatMapsKeys: ['flatFrontComponentMaps'],
+        },
+      );
+
+    return Object.values(flatFrontComponentMaps.byId)
+      .filter(isDefined)
+      .sort((a, b) => a.name.localeCompare(b.name))
+      .map(fromFlatFrontComponentToFrontComponentDto);
+  }
+
+  async findById(
+    id: string,
+    workspaceId: string,
+  ): Promise<FrontComponentDTO | null> {
+    const { flatFrontComponentMaps } =
+      await this.workspaceManyOrAllFlatEntityMapsCacheService.getOrRecomputeManyOrAllFlatEntityMaps(
+        {
+          workspaceId,
+          flatMapsKeys: ['flatFrontComponentMaps'],
+        },
+      );
+
+    const flatFrontComponent = findFlatEntityByIdInFlatEntityMaps({
+      flatEntityId: id,
+      flatEntityMaps: flatFrontComponentMaps,
+    });
+
+    if (!isDefined(flatFrontComponent)) {
+      return null;
+    }
+
+    return fromFlatFrontComponentToFrontComponentDto(flatFrontComponent);
+  }
+
+  async create(
+    input: CreateFrontComponentInput,
+    workspaceId: string,
+  ): Promise<FrontComponentDTO> {
+    const { workspaceCustomFlatApplication } =
+      await this.applicationService.findWorkspaceTwentyStandardAndCustomApplicationOrThrow(
+        { workspaceId },
+      );
+
+    const flatFrontComponentToCreate =
+      fromCreateFrontComponentInputToFlatFrontComponentToCreate({
+        createFrontComponentInput: input,
+        workspaceId,
+        applicationId: workspaceCustomFlatApplication.id,
+      });
+
+    const validateAndBuildResult =
+      await this.workspaceMigrationValidateBuildAndRunService.validateBuildAndRunWorkspaceMigration(
+        {
+          allFlatEntityOperationByMetadataName: {
+            frontComponent: {
+              flatEntityToCreate: [flatFrontComponentToCreate],
+              flatEntityToDelete: [],
+              flatEntityToUpdate: [],
+            },
+          },
+          workspaceId,
+          isSystemBuild: false,
+        },
+      );
+
+    if (isDefined(validateAndBuildResult)) {
+      throw new WorkspaceMigrationBuilderException(
+        validateAndBuildResult,
+        'Multiple validation errors occurred while creating front component',
+      );
+    }
+
+    const { flatFrontComponentMaps: recomputedFlatFrontComponentMaps } =
+      await this.workspaceManyOrAllFlatEntityMapsCacheService.getOrRecomputeManyOrAllFlatEntityMaps(
+        {
+          workspaceId,
+          flatMapsKeys: ['flatFrontComponentMaps'],
+        },
+      );
+
+    return fromFlatFrontComponentToFrontComponentDto(
+      findFlatEntityByIdInFlatEntityMapsOrThrow({
+        flatEntityId: flatFrontComponentToCreate.id,
+        flatEntityMaps: recomputedFlatFrontComponentMaps,
+      }),
+    );
+  }
+
+  async update(
+    input: UpdateFrontComponentInput,
+    workspaceId: string,
+  ): Promise<FrontComponentDTO> {
+    const { flatFrontComponentMaps: existingFlatFrontComponentMaps } =
+      await this.workspaceManyOrAllFlatEntityMapsCacheService.getOrRecomputeManyOrAllFlatEntityMaps(
+        {
+          workspaceId,
+          flatMapsKeys: ['flatFrontComponentMaps'],
+        },
+      );
+
+    const flatFrontComponentToUpdate =
+      fromUpdateFrontComponentInputToFlatFrontComponentToUpdateOrThrow({
+        flatFrontComponentMaps: existingFlatFrontComponentMaps,
+        updateFrontComponentInput: input,
+      });
+
+    const validateAndBuildResult =
+      await this.workspaceMigrationValidateBuildAndRunService.validateBuildAndRunWorkspaceMigration(
+        {
+          allFlatEntityOperationByMetadataName: {
+            frontComponent: {
+              flatEntityToCreate: [],
+              flatEntityToDelete: [],
+              flatEntityToUpdate: [flatFrontComponentToUpdate],
+            },
+          },
+          workspaceId,
+          isSystemBuild: false,
+        },
+      );
+
+    if (isDefined(validateAndBuildResult)) {
+      throw new WorkspaceMigrationBuilderException(
+        validateAndBuildResult,
+        'Multiple validation errors occurred while updating front component',
+      );
+    }
+
+    const { flatFrontComponentMaps: recomputedFlatFrontComponentMaps } =
+      await this.workspaceManyOrAllFlatEntityMapsCacheService.getOrRecomputeManyOrAllFlatEntityMaps(
+        {
+          workspaceId,
+          flatMapsKeys: ['flatFrontComponentMaps'],
+        },
+      );
+
+    return fromFlatFrontComponentToFrontComponentDto(
+      findFlatEntityByIdInFlatEntityMapsOrThrow({
+        flatEntityId: input.id,
+        flatEntityMaps: recomputedFlatFrontComponentMaps,
+      }),
+    );
+  }
+
+  async delete(id: string, workspaceId: string): Promise<FrontComponentDTO> {
+    const { flatFrontComponentMaps: existingFlatFrontComponentMaps } =
+      await this.workspaceManyOrAllFlatEntityMapsCacheService.getOrRecomputeManyOrAllFlatEntityMaps(
+        {
+          workspaceId,
+          flatMapsKeys: ['flatFrontComponentMaps'],
+        },
+      );
+
+    const flatFrontComponentToDelete =
+      fromDeleteFrontComponentInputToFlatFrontComponentOrThrow({
+        flatFrontComponentMaps: existingFlatFrontComponentMaps,
+        frontComponentId: id,
+      });
+
+    const validateAndBuildResult =
+      await this.workspaceMigrationValidateBuildAndRunService.validateBuildAndRunWorkspaceMigration(
+        {
+          allFlatEntityOperationByMetadataName: {
+            frontComponent: {
+              flatEntityToCreate: [],
+              flatEntityToDelete: [flatFrontComponentToDelete],
+              flatEntityToUpdate: [],
+            },
+          },
+          workspaceId,
+          isSystemBuild: false,
+        },
+      );
+
+    if (isDefined(validateAndBuildResult)) {
+      throw new WorkspaceMigrationBuilderException(
+        validateAndBuildResult,
+        'Multiple validation errors occurred while deleting front component',
+      );
+    }
+
+    return fromFlatFrontComponentToFrontComponentDto(
+      flatFrontComponentToDelete,
+    );
+  }
+
+  async findByIdOrThrow(
+    id: string,
+    workspaceId: string,
+  ): Promise<FrontComponentDTO> {
+    const frontComponent = await this.findById(id, workspaceId);
+
+    if (!isDefined(frontComponent)) {
+      throw new FrontComponentException(
+        'Front component not found',
+        FrontComponentExceptionCode.FRONT_COMPONENT_NOT_FOUND,
+      );
+    }
+
+    return frontComponent;
+  }
+}
@@ -0,0 +1,24 @@
+import {
+  type CallHandler,
+  type ExecutionContext,
+  Injectable,
+  type NestInterceptor,
+} from '@nestjs/common';
+
+import { type Observable, catchError } from 'rxjs';
+
+import { frontComponentGraphqlApiExceptionHandler } from 'src/engine/metadata-modules/front-component/utils/front-component-graphql-api-exception-handler.util';
+
+@Injectable()
+export class FrontComponentGraphqlApiExceptionInterceptor
+  implements NestInterceptor
+{
+  intercept(
+    _context: ExecutionContext,
+    next: CallHandler,
+  ): Observable<unknown> {
+    return next
+      .handle()
+      .pipe(catchError(frontComponentGraphqlApiExceptionHandler));
+  }
+}
@@ -0,0 +1,29 @@
+import { assertUnreachable } from 'twenty-shared/utils';
+
+import {
+  ConflictError,
+  NotFoundError,
+  UserInputError,
+} from 'src/engine/core-modules/graphql/utils/graphql-errors.util';
+import {
+  FrontComponentException,
+  FrontComponentExceptionCode,
+} from 'src/engine/metadata-modules/front-component/front-component.exception';
+
+export const frontComponentGraphqlApiExceptionHandler = (error: Error) => {
+  if (error instanceof FrontComponentException) {
+    switch (error.code) {
+      case FrontComponentExceptionCode.FRONT_COMPONENT_NOT_FOUND:
+        throw new NotFoundError(error);
+      case FrontComponentExceptionCode.INVALID_FRONT_COMPONENT_INPUT:
+        throw new UserInputError(error);
+      case FrontComponentExceptionCode.FRONT_COMPONENT_ALREADY_EXISTS:
+        throw new ConflictError(error);
+      default: {
+        return assertUnreachable(error.code);
+      }
+    }
+  }
+
+  throw error;
+};