Simplify and enhance v2 type devxp (#15032)

# Introduction
This PR introduces a huge type refactor that will leverage dynamic intra
entity optimistic flat maps update in the future and also a more
granular cache invalidation enhancing performances

close https://github.com/twentyhq/core-team-issues/issues/1717
close https://github.com/twentyhq/core-team-issues/issues/1716
close https://github.com/twentyhq/core-team-issues/issues/1643

## What's done

### Comparators centralization
Comparator is now done through global configuration as const for each
metadata names
Thanks to 

Note:
Definition of standard is evolving, standard is now scoped to an app.
Meaning that a manifest should be able to update its own standards
objects but on other app standards ones ? Each synchronizable entities
will have a standardOverrides ?

## Typing refactor

### `AllFlatEntityTypesByMetadataName`

**Single source of truth for the complete type ecosystem**, mapping each
metadata name to its entity types, flat entities, and migration actions:

```typescript
export type AllFlatEntityTypesByMetadataName = {
  fieldMetadata: {
    actions: { created: CreateFieldAction; updated: UpdateFieldAction; deleted: DeleteFieldAction; };
    flatEntity: FlatFieldMetadata;
    entity: FieldMetadataEntity;
  };
  objectMetadata: { /* ... */ };
  // ... all 10 metadata types
};
```

### `ALL_METADATA_NAME_MANY_TO_ONE_RELATIONS`

**Explicitly declares database relationships** between entities with
compile-time validation:

```typescript
export const ALL_METADATA_NAME_MANY_TO_ONE_RELATIONS = {
  viewField: {
    view: 'viewId',
    fieldMetadata: 'fieldMetadataId',
  },
  cronTrigger: {
    serverlessFunction: 'serverlessFunctionId',
  },
  // ... all relations
} as const satisfies MetadataNameAndRelations;
```

### `ALL_FLAT_ENTITY_CONFIGURATION`

**Centralizes comparison and serialization logic** for each metadata
type:

```typescript
export const ALL_FLAT_ENTITY_CONFIGURATION = {
  fieldMetadata: {
    propertiesToCompare: ['name', 'type', 'label', 'defaultValue', /* ... */],
    propertiesToStringify: ['options', 'settings', 'defaultValue'],
  },
  objectMetadata: {
    propertiesToCompare: ['nameSingular', 'namePlural', 'isActive', /* ... */],
    propertiesToStringify: [],
  },
  // ... all metadata types
} as const satisfies AllFlatEntityConfiguration;
```

## Combined Impact

These three configurations work together to create a **strongly-typed,
centrally-managed metadata system**:

1. **`AllFlatEntityTypesByMetadataName`** defines *what exists*
2. **`ALL_METADATA_NAME_MANY_TO_ONE_RELATIONS`** defines *how they
relate*
3. **`ALL_FLAT_ENTITY_CONFIGURATION`** defines *how to compare and
serialize them*

**Result:** Builders and validators become thin wrappers around
type-safe, configuration-driven logic instead of containing scattered,
error-prone manual implementations.

## What's next

### StandardOverrides standardization
Every metadata entity can be a standard one for a workspace if it's an
installed app, which means it might not expose the whole entity api to
be editable through an import dynamically
The standard overrides logic should not be applied to Fields and Objects
but to every entities

At the moment we have a logic of `EDITABLE_PROPERTIES` through the api,
and also `STANDARD_OVERRIDEDABLE_PROPERTIES`
This should be configuration centered like `propertiesToCompare` and
`propertiesToStringify`.
Scoping this PR to two last for the moment. As update dispatch to
standardOverrides could be considered as a side effect prefer waiting to
start the side effect refactor

### Granular Optimistic deprecation
With this new grain at runtime we will be able to add a flat entity and
dispatch its addition to related flat maps, so we don't have to describe
an optimistic method for each flat entity operations

See `addFlatEntityToFlatEntityAndRelatedEntityMapsOrThrow`

Note: Still in wip and included in this PR but about to create a new one
to integrate these utils and remove existing methods

### ValidateBuildAndRun dynamic args typed defintion
We should restrain the devxp to send expected flat maps entity as at
least from to or dependency as we now have the grain both a type lvl and
runtime to do so
It should not be possible in the devxp to forgot adding the views to the
v2 builder when passing the view field anymore ( that would lead to
permanent validation error in view field integrity checks )

## Conclusion
Thanks for reading and reviewing !
Any suggestions are more than welcomed ! ( same as for questions too ! )

packages/twenty-server/src/engine/metadata-modules/flat-entity/constant/all-flat-entity-maps-properties.constant.ts

@@ -0,0 +1,14 @@
+import { type AllFlatEntityMaps } from 'src/engine/metadata-modules/flat-entity/types/all-flat-entity-maps.type';
+
+export const ALL_FLAT_ENTITY_MAPS_PROPERTIES = [
+  'flatObjectMetadataMaps',
+  'flatViewFieldMaps',
+  'flatViewMaps',
+  'flatIndexMaps',
+  'flatServerlessFunctionMaps',
+  'flatDatabaseEventTriggerMaps',
+  'flatCronTriggerMaps',
+  'flatRouteTriggerMaps',
+  'flatFieldMetadataMaps',
+  'flatViewFilterMaps',
+] as const satisfies (keyof AllFlatEntityMaps)[];

packages/twenty-server/src/engine/metadata-modules/flat-entity/constant/all-flat-entity-properties-to-compare-and-stringify.constant.ts

@@ -0,0 +1,91 @@
+import { FLAT_CRON_TRIGGER_EDITABLE_PROPERTIES } from 'src/engine/metadata-modules/cron-trigger/constants/flat-cron-trigger-editable-properties.constant';
+import { FLAT_DATABASE_EVENT_TRIGGER_EDITABLE_PROPERTIES } from 'src/engine/metadata-modules/database-event-trigger/constants/flat-database-event-trigger-editable-properties.constant';
+import { type AllMetadataName } from 'src/engine/metadata-modules/flat-entity/types/all-metadata-name.type';
+import { type MetadataFlatEntity } from 'src/engine/metadata-modules/flat-entity/types/metadata-flat-entity.type';
+import { FLAT_FIELD_METADATA_EDITABLE_PROPERTIES } from 'src/engine/metadata-modules/flat-field-metadata/constants/flat-field-metadata-editable-properties.constant';
+import { FLAT_VIEW_FIELD_EDITABLE_PROPERTIES } from 'src/engine/metadata-modules/flat-view-field/constants/flat-view-field-editable-properties.constant';
+import { FLAT_VIEW_FILTER_EDITABLE_PROPERTIES } from 'src/engine/metadata-modules/flat-view-filter/constants/flat-view-filter-editable-properties.constant';
+import { FLAT_VIEW_EDITABLE_PROPERTIES } from 'src/engine/metadata-modules/flat-view/constants/flat-view-editable-properties.constant';
+import { FLAT_ROUTE_TRIGGER_EDITABLE_PROPERTIES } from 'src/engine/metadata-modules/route-trigger/constants/flat-route-trigger-editable-properties.constant';
+import { FLAT_SERVERLESS_FUNCTION_EDITABLE_PROPERTIES } from 'src/engine/metadata-modules/serverless-function/constants/flat-serverless-function-editable-properties.constant';
+
+type OneFlatEntityConfiguration<T extends AllMetadataName> = {
+  propertiesToCompare: (keyof MetadataFlatEntity<T>)[];
+  propertiesToStringify: (keyof MetadataFlatEntity<T>)[];
+};
+export const ALL_FLAT_ENTITY_PROPERTIES_TO_COMPARE_AND_STRINGIFY = {
+  fieldMetadata: {
+    propertiesToCompare: [
+      ...FLAT_FIELD_METADATA_EDITABLE_PROPERTIES,
+      'standardOverrides',
+    ],
+    propertiesToStringify: [
+      'options',
+      'settings',
+      'standardOverrides',
+      'defaultValue',
+    ],
+  },
+  objectMetadata: {
+    propertiesToCompare: [
+      'description',
+      'icon',
+      'isActive',
+      'isLabelSyncedWithName',
+      'labelPlural',
+      'labelSingular',
+      'namePlural',
+      'nameSingular',
+      'standardOverrides',
+      'labelIdentifierFieldMetadataId',
+    ],
+    propertiesToStringify: ['standardOverrides'],
+  },
+  view: {
+    propertiesToCompare: ['key', 'deletedAt', ...FLAT_VIEW_EDITABLE_PROPERTIES],
+    propertiesToStringify: [],
+  },
+  viewField: {
+    propertiesToCompare: [...FLAT_VIEW_FIELD_EDITABLE_PROPERTIES, 'deletedAt'],
+    propertiesToStringify: [],
+  },
+  index: {
+    propertiesToCompare: [
+      'indexType',
+      'indexWhereClause',
+      'flatIndexFieldMetadatas',
+      'isUnique',
+      'name',
+    ],
+    propertiesToStringify: ['flatIndexFieldMetadatas'],
+  },
+  serverlessFunction: {
+    propertiesToCompare: [
+      ...FLAT_SERVERLESS_FUNCTION_EDITABLE_PROPERTIES,
+      'deletedAt',
+    ],
+    propertiesToStringify: [],
+  },
+  cronTrigger: {
+    propertiesToCompare: [...FLAT_CRON_TRIGGER_EDITABLE_PROPERTIES],
+    propertiesToStringify: ['settings'],
+  },
+  databaseEventTrigger: {
+    propertiesToCompare: [...FLAT_DATABASE_EVENT_TRIGGER_EDITABLE_PROPERTIES],
+    propertiesToStringify: ['settings'],
+  },
+  routeTrigger: {
+    propertiesToCompare: [...FLAT_ROUTE_TRIGGER_EDITABLE_PROPERTIES],
+    propertiesToStringify: [],
+  },
+  viewFilter: {
+    propertiesToCompare: [
+      'viewId',
+      'deletedAt',
+      ...FLAT_VIEW_FILTER_EDITABLE_PROPERTIES,
+    ],
+    propertiesToStringify: ['value'],
+  },
+} as const satisfies {
+  [P in AllMetadataName]: OneFlatEntityConfiguration<P>;
+};

packages/twenty-server/src/engine/metadata-modules/flat-entity/constant/all-metadata-many-to-one-relations.constant.ts

@@ -0,0 +1,62 @@
+import { type ExtractPropertiesThatEndsWithId } from 'twenty-shared/types';
+
+import { type AllMetadataName } from 'src/engine/metadata-modules/flat-entity/types/all-metadata-name.type';
+import { type MetadataEntity } from 'src/engine/metadata-modules/flat-entity/types/metadata-entity.type';
+
+type PropertyNameToRelationName<T extends string> = T extends `${infer Name}Id`
+  ? Name
+  : never;
+
+type ExtractEntityRelations<TEntity extends MetadataEntity<AllMetadataName>> = {
+  [K in ExtractPropertiesThatEndsWithId<
+    TEntity,
+    'id' | 'workspaceId'
+  > as PropertyNameToRelationName<K>]: K;
+};
+
+type MetadataRelatedMetadataNames<T extends AllMetadataName> = Extract<
+  keyof ExtractEntityRelations<MetadataEntity<T>>,
+  AllMetadataName
+>;
+
+type MetadataNameAndRelations = {
+  [T in AllMetadataName]: MetadataRelatedMetadataNames<T> extends never
+    ? Record<string, never>
+    : Record<MetadataRelatedMetadataNames<T>, string> & {
+        [K in Exclude<
+          AllMetadataName,
+          MetadataRelatedMetadataNames<T>
+        >]?: string;
+      };
+};
+
+export const ALL_METADATA_NAME_MANY_TO_ONE_RELATIONS = {
+  fieldMetadata: {
+    objectMetadata: 'objectMetadataId',
+  },
+  objectMetadata: {},
+  view: {
+    objectMetadata: 'objectMetadataId',
+  },
+  viewField: {
+    view: 'viewId',
+    fieldMetadata: 'fieldMetadataId',
+  },
+  index: {
+    objectMetadata: 'objectMetadataId',
+  },
+  serverlessFunction: {},
+  cronTrigger: {
+    serverlessFunction: 'serverlessFunctionId',
+  },
+  databaseEventTrigger: {
+    serverlessFunction: 'serverlessFunctionId',
+  },
+  routeTrigger: {
+    serverlessFunction: 'serverlessFunctionId',
+  },
+  viewFilter: {
+    view: 'viewId',
+    fieldMetadata: 'fieldMetadataId',
+  },
+} as const satisfies MetadataNameAndRelations;

packages/twenty-server/src/engine/metadata-modules/flat-entity/constant/all-metadata-name.constant.ts

@@ -0,0 +1,12 @@
+export const ALL_METADATA_NAME = {
+  fieldMetadata: 'fieldMetadata',
+  objectMetadata: 'objectMetadata',
+  view: 'view',
+  viewField: 'viewField',
+  index: 'index',
+  serverlessFunction: 'serverlessFunction',
+  cronTrigger: 'cronTrigger',
+  databaseEventTrigger: 'databaseEventTrigger',
+  routeTrigger: 'routeTrigger',
+  viewFilter: 'viewFilter',
+} as const;

packages/twenty-server/src/engine/metadata-modules/flat-entity/constant/all-metadata-required-metadata-for-validation.constant.ts

@@ -0,0 +1,46 @@
+import { type AllMetadataName } from 'src/engine/metadata-modules/flat-entity/types/all-metadata-name.type';
+import { type MetadataManyToOneRelatedMetadataNames } from 'src/engine/metadata-modules/flat-entity/types/metadata-many-to-one-related-metadata-names.type';
+
+type MetadataRequiredForValidation = {
+  [T in AllMetadataName]: Record<
+    MetadataManyToOneRelatedMetadataNames<T>,
+    true
+  > & {
+    [K in Exclude<AllMetadataName, T>]?: true;
+  };
+};
+
+export const ALL_METADATA_REQUIRED_METADATA_FOR_VALIDATION = {
+  fieldMetadata: {
+    objectMetadata: true,
+  },
+  objectMetadata: {
+    fieldMetadata: true,
+  },
+  view: {
+    objectMetadata: true,
+  },
+  viewField: {
+    view: true,
+    fieldMetadata: true,
+    objectMetadata: true,
+  },
+  index: {
+    objectMetadata: true,
+    fieldMetadata: true,
+  },
+  serverlessFunction: {},
+  cronTrigger: {
+    serverlessFunction: true,
+  },
+  databaseEventTrigger: {
+    serverlessFunction: true,
+  },
+  routeTrigger: {
+    serverlessFunction: true,
+  },
+  viewFilter: {
+    view: true,
+    fieldMetadata: true,
+  },
+} as const satisfies MetadataRequiredForValidation;

packages/twenty-server/src/engine/metadata-modules/flat-entity/constant/empty-all-flat-entity-maps.constant.ts

@@ -0,0 +1,15 @@
+import { EMPTY_FLAT_ENTITY_MAPS } from 'src/engine/metadata-modules/flat-entity/constant/empty-flat-entity-maps.constant';
+import { type AllFlatEntityMaps } from 'src/engine/metadata-modules/flat-entity/types/all-flat-entity-maps.type';
+
+export const EMPTY_ALL_FLAT_ENTITY_MAPS = {
+  flatObjectMetadataMaps: EMPTY_FLAT_ENTITY_MAPS,
+  flatFieldMetadataMaps: EMPTY_FLAT_ENTITY_MAPS,
+  flatIndexMaps: EMPTY_FLAT_ENTITY_MAPS,
+  flatViewFieldMaps: EMPTY_FLAT_ENTITY_MAPS,
+  flatViewMaps: EMPTY_FLAT_ENTITY_MAPS,
+  flatServerlessFunctionMaps: EMPTY_FLAT_ENTITY_MAPS,
+  flatCronTriggerMaps: EMPTY_FLAT_ENTITY_MAPS,
+  flatDatabaseEventTriggerMaps: EMPTY_FLAT_ENTITY_MAPS,
+  flatRouteTriggerMaps: EMPTY_FLAT_ENTITY_MAPS,
+  flatViewFilterMaps: EMPTY_FLAT_ENTITY_MAPS,
+} as const satisfies AllFlatEntityMaps;

packages/twenty-server/src/engine/metadata-modules/flat-entity/constant/empty-flat-entity-maps.constant.ts

@@ -0,0 +1,7 @@
+import { type FlatEntityMaps } from 'src/engine/metadata-modules/flat-entity/types/flat-entity-maps.type';
+import { type FlatEntity } from 'src/engine/metadata-modules/flat-entity/types/flat-entity.type';
+
+export const EMPTY_FLAT_ENTITY_MAPS = {
+  byId: {},
+  idByUniversalIdentifier: {},
+} as const satisfies FlatEntityMaps<FlatEntity>;

packages/twenty-server/src/engine/metadata-modules/flat-entity/exceptions/flat-entity-maps.exception.ts

@@ -0,0 +1,15 @@
+import { CustomException } from 'src/utils/custom-exception';
+
+export class FlatEntityMapsException extends CustomException {
+  code: FlatEntityMapsExceptionCode;
+
+  constructor(message: string, code: FlatEntityMapsExceptionCode) {
+    super(message, code);
+  }
+}
+
+export enum FlatEntityMapsExceptionCode {
+  ENTITY_ALREADY_EXISTS = 'ENTITY_ALREADY_EXISTS',
+  ENTITY_NOT_FOUND = 'ENTITY_NOT_FOUND',
+  ENTITY_MALFORMED = 'ENTITY_MALFORMED',
+}

packages/twenty-server/src/engine/metadata-modules/flat-entity/services/workspace-many-or-all-flat-entity-maps-cache.module.ts

@@ -0,0 +1,11 @@
+import { Module } from '@nestjs/common';
+
+import { WorkspaceManyOrAllFlatEntityMapsCacheService } from 'src/engine/metadata-modules/flat-entity/services/workspace-many-or-all-flat-entity-maps-cache.service';
+import { WorkspaceFlatMapCacheModule } from 'src/engine/workspace-flat-map-cache/workspace-flat-map-cache.module';
+
+@Module({
+  imports: [WorkspaceFlatMapCacheModule],
+  providers: [WorkspaceManyOrAllFlatEntityMapsCacheService],
+  exports: [WorkspaceManyOrAllFlatEntityMapsCacheService],
+})
+export class WorkspaceManyOrAllFlatEntityMapsCacheModule {}

packages/twenty-server/src/engine/metadata-modules/flat-entity/services/workspace-many-or-all-flat-entity-maps-cache.service.ts

@@ -0,0 +1,111 @@
+import { Injectable, Logger } from '@nestjs/common';
+
+import { isDefined } from 'twenty-shared/utils';
+
+import { ALL_FLAT_ENTITY_MAPS_PROPERTIES } from 'src/engine/metadata-modules/flat-entity/constant/all-flat-entity-maps-properties.constant';
+import { AllFlatEntityMaps } from 'src/engine/metadata-modules/flat-entity/types/all-flat-entity-maps.type';
+import { WorkspaceFlatMapCacheRegistryService } from 'src/engine/workspace-flat-map-cache/services/workspace-flat-map-cache-registry.service';
+import { WorkspaceFlatMapCacheService } from 'src/engine/workspace-flat-map-cache/services/workspace-flat-map-cache.service';
+
+@Injectable()
+export class WorkspaceManyOrAllFlatEntityMapsCacheService {
+  private readonly logger = new Logger(
+    WorkspaceManyOrAllFlatEntityMapsCacheService.name,
+  );
+
+  constructor(
+    private readonly cacheRegistry: WorkspaceFlatMapCacheRegistryService,
+  ) {}
+
+  private async executeActionForManyOrAllFlatEntity<
+    K extends (keyof AllFlatEntityMaps)[] = (keyof AllFlatEntityMaps)[],
+  >({
+    action,
+    flatMapsKeys,
+  }: {
+    flatMapsKeys: K | undefined;
+    action: (args: {
+      service: WorkspaceFlatMapCacheService<AllFlatEntityMaps[K[number]]>;
+      flatMapKey: K[number];
+    }) => Promise<void>;
+  }): Promise<void> {
+    const keysToProcess = isDefined(flatMapsKeys)
+      ? flatMapsKeys
+      : ALL_FLAT_ENTITY_MAPS_PROPERTIES;
+
+    for (const flatMapKey of keysToProcess) {
+      try {
+        const service = this.cacheRegistry.getCacheServiceOrThrow(
+          flatMapKey as K[number],
+        );
+
+        await action({
+          flatMapKey: flatMapKey,
+          service,
+        });
+      } catch (error) {
+        this.logger.error(
+          `Failed to run action on flat entity maps of ${flatMapKey}`,
+          error,
+        );
+        throw error;
+      }
+    }
+  }
+
+  public async getOrRecomputeManyOrAllFlatEntityMaps<
+    T extends (keyof AllFlatEntityMaps)[] = (keyof AllFlatEntityMaps)[],
+  >({
+    flatMapsKeys,
+    workspaceId,
+  }: {
+    workspaceId: string;
+    flatMapsKeys?: T;
+  }): Promise<Pick<AllFlatEntityMaps, T[number]>> {
+    let pickedFlatEntityMaps = {} as Pick<AllFlatEntityMaps, T[number]>;
+
+    await this.executeActionForManyOrAllFlatEntity({
+      action: async ({ service, flatMapKey }) => {
+        const cacheResult = await service.getExistingOrRecomputeFlatMaps({
+          workspaceId,
+        });
+
+        pickedFlatEntityMaps[flatMapKey] = cacheResult;
+      },
+      flatMapsKeys,
+    });
+
+    return pickedFlatEntityMaps;
+  }
+
+  public async invalidateFlatEntityMaps<
+    T extends (keyof AllFlatEntityMaps)[] = (keyof AllFlatEntityMaps)[],
+  >({
+    flatMapsKeys,
+    workspaceId,
+  }: {
+    workspaceId: string;
+    flatMapsKeys?: T;
+  }): Promise<void> {
+    await this.executeActionForManyOrAllFlatEntity({
+      action: async ({ service }) =>
+        await service.invalidateCache({ workspaceId }),
+      flatMapsKeys,
+    });
+  }
+
+  public async flushFlatEntityMaps<
+    T extends (keyof AllFlatEntityMaps)[] = (keyof AllFlatEntityMaps)[],
+  >({
+    flatMapsKeys,
+    workspaceId,
+  }: {
+    workspaceId: string;
+    flatMapsKeys?: T;
+  }): Promise<void> {
+    await this.executeActionForManyOrAllFlatEntity({
+      action: async ({ service }) => await service.flushCache({ workspaceId }),
+      flatMapsKeys,
+    });
+  }
+}

packages/twenty-server/src/engine/metadata-modules/flat-entity/types/all-flat-entities.type.ts

@@ -0,0 +1,4 @@
+import { type AllFlatEntityTypesByMetadataName } from 'src/engine/metadata-modules/flat-entity/types/all-flat-entity-types-by-metadata-name';
+
+export type AllFlatEntities =
+  AllFlatEntityTypesByMetadataName[keyof AllFlatEntityTypesByMetadataName]['flatEntity'];

packages/twenty-server/src/engine/metadata-modules/flat-entity/types/all-flat-entity-by-metadata-engine-name-test.type.ts

@@ -0,0 +1,27 @@
+import { type Expect } from 'twenty-shared/testing';
+
+import { type AllFlatEntityTypesByMetadataName } from 'src/engine/metadata-modules/flat-entity/types/all-flat-entity-types-by-metadata-name';
+import { type FlatEntity } from 'src/engine/metadata-modules/flat-entity/types/flat-entity.type';
+import { type WorkspaceMigrationActionV2 } from 'src/engine/workspace-manager/workspace-migration-v2/workspace-migration-builder-v2/types/workspace-migration-action-common-v2';
+
+type ExpectedGenericFlatEntityInformation = {
+  actions: {
+    created: WorkspaceMigrationActionV2 | WorkspaceMigrationActionV2[];
+    deleted: WorkspaceMigrationActionV2 | WorkspaceMigrationActionV2[];
+    updated: WorkspaceMigrationActionV2 | WorkspaceMigrationActionV2[];
+  };
+  flatEntity: FlatEntity;
+};
+
+type ExpectedGenericAllFlatEntityInformationByMetadataEngine = {
+  [P in keyof AllFlatEntityTypesByMetadataName]: ExpectedGenericFlatEntityInformation;
+};
+
+// eslint-disable-next-line unused-imports/no-unused-vars
+type Assertions = [
+  Expect<
+    AllFlatEntityTypesByMetadataName extends ExpectedGenericAllFlatEntityInformationByMetadataEngine
+      ? true
+      : false
+  >,
+];

packages/twenty-server/src/engine/metadata-modules/flat-entity/types/all-flat-entity-maps.type.ts

@@ -0,0 +1,10 @@
+import { type AllFlatEntityTypesByMetadataName } from 'src/engine/metadata-modules/flat-entity/types/all-flat-entity-types-by-metadata-name';
+import { type FlatEntityMaps } from 'src/engine/metadata-modules/flat-entity/types/flat-entity-maps.type';
+import { type MetadataFlatEntity } from 'src/engine/metadata-modules/flat-entity/types/metadata-flat-entity.type';
+import { type MetadataToFlatEntityMapsKey } from 'src/engine/metadata-modules/flat-entity/types/metadata-to-flat-entity-maps-key';
+
+export type AllFlatEntityMaps = {
+  [P in keyof AllFlatEntityTypesByMetadataName as MetadataToFlatEntityMapsKey<P>]: FlatEntityMaps<
+    MetadataFlatEntity<P>
+  >;
+};

packages/twenty-server/src/engine/metadata-modules/flat-entity/types/all-flat-entity-types-by-metadata-name.ts

@@ -0,0 +1,162 @@
+import { type CronTrigger } from 'src/engine/metadata-modules/cron-trigger/entities/cron-trigger.entity';
+import { type FlatCronTrigger } from 'src/engine/metadata-modules/cron-trigger/types/flat-cron-trigger.type';
+import { type DatabaseEventTrigger } from 'src/engine/metadata-modules/database-event-trigger/entities/database-event-trigger.entity';
+import { type FlatDatabaseEventTrigger } from 'src/engine/metadata-modules/database-event-trigger/types/flat-database-event-trigger.type';
+import { type FieldMetadataEntity } from 'src/engine/metadata-modules/field-metadata/field-metadata.entity';
+import { type FlatFieldMetadata } from 'src/engine/metadata-modules/flat-field-metadata/types/flat-field-metadata.type';
+import { type FlatIndexMetadata } from 'src/engine/metadata-modules/flat-index-metadata/types/flat-index-metadata.type';
+import { type FlatObjectMetadata } from 'src/engine/metadata-modules/flat-object-metadata/types/flat-object-metadata.type';
+import { type FlatViewField } from 'src/engine/metadata-modules/flat-view-field/types/flat-view-field.type';
+import { type FlatViewFilter } from 'src/engine/metadata-modules/flat-view-filter/types/flat-view-filter.type';
+import { type FlatView } from 'src/engine/metadata-modules/flat-view/types/flat-view.type';
+import { type IndexMetadataEntity } from 'src/engine/metadata-modules/index-metadata/index-metadata.entity';
+import { type ObjectMetadataEntity } from 'src/engine/metadata-modules/object-metadata/object-metadata.entity';
+import { type RouteTrigger } from 'src/engine/metadata-modules/route-trigger/route-trigger.entity';
+import { type FlatRouteTrigger } from 'src/engine/metadata-modules/route-trigger/types/flat-route-trigger.type';
+import { type ServerlessFunctionEntity } from 'src/engine/metadata-modules/serverless-function/serverless-function.entity';
+import { type FlatServerlessFunction } from 'src/engine/metadata-modules/serverless-function/types/flat-serverless-function.type';
+import { type ViewFieldEntity } from 'src/engine/metadata-modules/view-field/entities/view-field.entity';
+import { type ViewFilterEntity } from 'src/engine/metadata-modules/view-filter/entities/view-filter.entity';
+import { type ViewEntity } from 'src/engine/metadata-modules/view/entities/view.entity';
+import {
+  type CreateCronTriggerAction,
+  type DeleteCronTriggerAction,
+  type UpdateCronTriggerAction,
+} from 'src/engine/workspace-manager/workspace-migration-v2/workspace-migration-builder-v2/builders/cron-trigger/types/workspace-migration-cron-trigger-action-v2.type';
+import {
+  type CreateDatabaseEventTriggerAction,
+  type DeleteDatabaseEventTriggerAction,
+  type UpdateDatabaseEventTriggerAction,
+} from 'src/engine/workspace-manager/workspace-migration-v2/workspace-migration-builder-v2/builders/database-event-trigger/types/workspace-migration-database-event-trigger-action-v2.type';
+import {
+  type CreateFieldAction,
+  type DeleteFieldAction,
+  type UpdateFieldAction,
+} from 'src/engine/workspace-manager/workspace-migration-v2/workspace-migration-builder-v2/builders/field/types/workspace-migration-field-action-v2';
+import {
+  type CreateIndexAction,
+  type DeleteIndexAction,
+} from 'src/engine/workspace-manager/workspace-migration-v2/workspace-migration-builder-v2/builders/index/types/workspace-migration-index-action-v2';
+import {
+  type CreateObjectAction,
+  type DeleteObjectAction,
+  type UpdateObjectAction,
+} from 'src/engine/workspace-manager/workspace-migration-v2/workspace-migration-builder-v2/builders/object/types/workspace-migration-object-action-v2';
+import {
+  type CreateRouteTriggerAction,
+  type DeleteRouteTriggerAction,
+  type UpdateRouteTriggerAction,
+} from 'src/engine/workspace-manager/workspace-migration-v2/workspace-migration-builder-v2/builders/route-trigger/types/workspace-migration-route-trigger-action-v2.type';
+import {
+  type CreateServerlessFunctionAction,
+  type DeleteServerlessFunctionAction,
+  type UpdateServerlessFunctionAction,
+} from 'src/engine/workspace-manager/workspace-migration-v2/workspace-migration-builder-v2/builders/serverless-function/types/workspace-migration-serverless-function-action-v2.type';
+import {
+  type CreateViewFieldAction,
+  type DeleteViewFieldAction,
+  type UpdateViewFieldAction,
+} from 'src/engine/workspace-manager/workspace-migration-v2/workspace-migration-builder-v2/builders/view-field/types/workspace-migration-view-field-action-v2.type';
+import {
+  type CreateViewFilterAction,
+  type DeleteViewFilterAction,
+  type UpdateViewFilterAction,
+} from 'src/engine/workspace-manager/workspace-migration-v2/workspace-migration-builder-v2/builders/view-filter/types/workspace-migration-view-filter-action-v2.type';
+import {
+  type CreateViewAction,
+  type DeleteViewAction,
+  type UpdateViewAction,
+} from 'src/engine/workspace-manager/workspace-migration-v2/workspace-migration-builder-v2/builders/view/types/workspace-migration-view-action-v2.type';
+
+export type AllFlatEntityTypesByMetadataName = {
+  fieldMetadata: {
+    actions: {
+      created: CreateFieldAction;
+      updated: UpdateFieldAction;
+      deleted: DeleteFieldAction;
+    };
+    flatEntity: FlatFieldMetadata;
+    entity: FieldMetadataEntity;
+  };
+  objectMetadata: {
+    actions: {
+      created: CreateObjectAction;
+      updated: UpdateObjectAction;
+      deleted: DeleteObjectAction;
+    };
+    flatEntity: FlatObjectMetadata;
+    entity: ObjectMetadataEntity;
+  };
+  view: {
+    actions: {
+      created: CreateViewAction;
+      updated: UpdateViewAction;
+      deleted: DeleteViewAction;
+    };
+    flatEntity: FlatView;
+    entity: ViewEntity;
+  };
+  viewField: {
+    actions: {
+      created: CreateViewFieldAction;
+      updated: UpdateViewFieldAction;
+      deleted: DeleteViewFieldAction;
+    };
+    flatEntity: FlatViewField;
+    entity: ViewFieldEntity;
+  };
+  index: {
+    actions: {
+      created: CreateIndexAction;
+      updated: [DeleteIndexAction, CreateIndexAction];
+      deleted: DeleteIndexAction;
+    };
+    flatEntity: FlatIndexMetadata;
+    entity: IndexMetadataEntity;
+  };
+  serverlessFunction: {
+    actions: {
+      created: CreateServerlessFunctionAction;
+      updated: UpdateServerlessFunctionAction;
+      deleted: DeleteServerlessFunctionAction;
+    };
+    flatEntity: FlatServerlessFunction;
+    entity: ServerlessFunctionEntity;
+  };
+  cronTrigger: {
+    actions: {
+      created: CreateCronTriggerAction;
+      updated: UpdateCronTriggerAction;
+      deleted: DeleteCronTriggerAction;
+    };
+    flatEntity: FlatCronTrigger;
+    entity: CronTrigger;
+  };
+  databaseEventTrigger: {
+    actions: {
+      created: CreateDatabaseEventTriggerAction;
+      updated: UpdateDatabaseEventTriggerAction;
+      deleted: DeleteDatabaseEventTriggerAction;
+    };
+    flatEntity: FlatDatabaseEventTrigger;
+    entity: DatabaseEventTrigger;
+  };
+  routeTrigger: {
+    actions: {
+      created: CreateRouteTriggerAction;
+      updated: UpdateRouteTriggerAction;
+      deleted: DeleteRouteTriggerAction;
+    };
+    flatEntity: FlatRouteTrigger;
+    entity: RouteTrigger;
+  };
+  viewFilter: {
+    actions: {
+      created: CreateViewFilterAction;
+      updated: UpdateViewFilterAction;
+      deleted: DeleteViewFilterAction;
+    };
+    flatEntity: FlatViewFilter;
+    entity: ViewFilterEntity;
+  };
+};

packages/twenty-server/src/engine/metadata-modules/flat-entity/types/all-metadata-name.type.ts

@@ -0,0 +1,3 @@
+import { type ALL_METADATA_NAME } from 'src/engine/metadata-modules/flat-entity/constant/all-metadata-name.constant';
+
+export type AllMetadataName = keyof typeof ALL_METADATA_NAME;

packages/twenty-server/src/engine/metadata-modules/flat-entity/types/flat-entity-maps.type.ts

@@ -0,0 +1,6 @@
+import { type FlatEntity } from 'src/engine/metadata-modules/flat-entity/types/flat-entity.type';
+
+export type FlatEntityMaps<T extends FlatEntity> = {
+  byId: Partial<Record<string, T>>;
+  idByUniversalIdentifier: Partial<Record<string, string>>;
+};

packages/twenty-server/src/engine/metadata-modules/flat-entity/types/flat-entity-properties-to-compare.type.ts

@@ -0,0 +1,5 @@
+import { type ALL_FLAT_ENTITY_PROPERTIES_TO_COMPARE_AND_STRINGIFY } from 'src/engine/metadata-modules/flat-entity/constant/all-flat-entity-properties-to-compare-and-stringify.constant';
+import { type AllMetadataName } from 'src/engine/metadata-modules/flat-entity/types/all-metadata-name.type';
+
+export type FlatEntityPropertiesToCompare<T extends AllMetadataName> =
+  (typeof ALL_FLAT_ENTITY_PROPERTIES_TO_COMPARE_AND_STRINGIFY)[T]['propertiesToCompare'][number];

packages/twenty-server/src/engine/metadata-modules/flat-entity/types/flat-entity-properties-to-stringify.type.ts

@@ -0,0 +1,5 @@
+import { type ALL_FLAT_ENTITY_PROPERTIES_TO_COMPARE_AND_STRINGIFY } from 'src/engine/metadata-modules/flat-entity/constant/all-flat-entity-properties-to-compare-and-stringify.constant';
+import { type AllMetadataName } from 'src/engine/metadata-modules/flat-entity/types/all-metadata-name.type';
+
+export type FlatEntityPropertiesToStringify<T extends AllMetadataName> =
+  (typeof ALL_FLAT_ENTITY_PROPERTIES_TO_COMPARE_AND_STRINGIFY)[T]['propertiesToStringify'][number];

packages/twenty-server/src/engine/metadata-modules/flat-entity/types/flat-entity-properties-updates.type.ts

@@ -0,0 +1,11 @@
+import { type AllMetadataName } from 'src/engine/metadata-modules/flat-entity/types/all-metadata-name.type';
+import { type FlatEntityPropertiesToCompare } from 'src/engine/metadata-modules/flat-entity/types/flat-entity-properties-to-compare.type';
+import { type MetadataFlatEntity } from 'src/engine/metadata-modules/flat-entity/types/metadata-flat-entity.type';
+import { type PropertyUpdate } from 'src/engine/workspace-manager/workspace-migration-v2/types/property-update.type';
+
+export type FlatEntityPropertiesUpdates<
+  T extends AllMetadataName,
+  K extends FlatEntityPropertiesToCompare<T> = FlatEntityPropertiesToCompare<T>,
+> = Array<
+  PropertyUpdate<MetadataFlatEntity<T>, Extract<K, keyof MetadataFlatEntity<T>>>
+>;

packages/twenty-server/src/engine/metadata-modules/flat-entity/types/flat-entity.type.ts

@@ -0,0 +1,4 @@
+export interface FlatEntity {
+  id: string;
+  universalIdentifier: string;
+}

packages/twenty-server/src/engine/metadata-modules/flat-entity/types/metadata-entity.type.ts

@@ -0,0 +1,5 @@
+import { type AllFlatEntityTypesByMetadataName } from 'src/engine/metadata-modules/flat-entity/types/all-flat-entity-types-by-metadata-name';
+import { type AllMetadataName } from 'src/engine/metadata-modules/flat-entity/types/all-metadata-name.type';
+
+export type MetadataEntity<T extends AllMetadataName> =
+  AllFlatEntityTypesByMetadataName[T]['entity'];

packages/twenty-server/src/engine/metadata-modules/flat-entity/types/metadata-flat-entity-maps.type.ts

@@ -0,0 +1,7 @@
+import { type AllMetadataName } from 'src/engine/metadata-modules/flat-entity/types/all-metadata-name.type';
+import { type FlatEntityMaps } from 'src/engine/metadata-modules/flat-entity/types/flat-entity-maps.type';
+import { type MetadataFlatEntity } from 'src/engine/metadata-modules/flat-entity/types/metadata-flat-entity.type';
+
+export type MetadataFlatEntityMaps<T extends AllMetadataName> = FlatEntityMaps<
+  MetadataFlatEntity<T>
+>;

packages/twenty-server/src/engine/metadata-modules/flat-entity/types/metadata-flat-entity.type.ts

@@ -0,0 +1,5 @@
+import { type AllFlatEntityTypesByMetadataName } from 'src/engine/metadata-modules/flat-entity/types/all-flat-entity-types-by-metadata-name';
+import { type AllMetadataName } from 'src/engine/metadata-modules/flat-entity/types/all-metadata-name.type';
+
+export type MetadataFlatEntity<T extends AllMetadataName> =
+  AllFlatEntityTypesByMetadataName[T]['flatEntity'];

packages/twenty-server/src/engine/metadata-modules/flat-entity/types/metadata-many-to-one-related-metadata-names.type.ts

@@ -0,0 +1,8 @@
+import { type ALL_METADATA_NAME_MANY_TO_ONE_RELATIONS } from 'src/engine/metadata-modules/flat-entity/constant/all-metadata-many-to-one-relations.constant';
+import { type AllMetadataName } from 'src/engine/metadata-modules/flat-entity/types/all-metadata-name.type';
+
+export type MetadataManyToOneRelatedMetadataNames<T extends AllMetadataName> =
+  Extract<
+    keyof (typeof ALL_METADATA_NAME_MANY_TO_ONE_RELATIONS)[T],
+    AllMetadataName
+  >;

packages/twenty-server/src/engine/metadata-modules/flat-entity/types/metadata-name-and-relations.type.ts

@@ -0,0 +1,24 @@
+import { type AllMetadataName } from 'src/engine/metadata-modules/flat-entity/types/all-metadata-name.type';
+import { type MetadataEntity } from 'src/engine/metadata-modules/flat-entity/types/metadata-entity.type';
+
+type ExtractRelationIdProperties<T> = {
+  [K in keyof T]: K extends `${infer _}Id`
+    ? K extends 'id' | 'workspaceId' | 'standardId'
+      ? never
+      : T[K] extends string | null | undefined
+        ? K
+        : never
+    : never;
+}[keyof T];
+
+type PropertyNameToRelationName<T extends string> = T extends `${infer Name}Id`
+  ? Name
+  : never;
+
+type ExtractEntityRelations<TEntity> = {
+  [K in ExtractRelationIdProperties<TEntity> as PropertyNameToRelationName<K>]: K;
+};
+
+export type MetadataNameAndRelations = {
+  [T in AllMetadataName]: Partial<ExtractEntityRelations<MetadataEntity<T>>>;
+};

packages/twenty-server/src/engine/metadata-modules/flat-entity/types/metadata-related-flat-entity-maps-keys.type.ts

@@ -0,0 +1,6 @@
+import { type AllMetadataName } from 'src/engine/metadata-modules/flat-entity/types/all-metadata-name.type';
+import { type MetadataManyToOneRelatedMetadataNames } from 'src/engine/metadata-modules/flat-entity/types/metadata-many-to-one-related-metadata-names.type';
+import { type MetadataToFlatEntityMapsKey } from 'src/engine/metadata-modules/flat-entity/types/metadata-to-flat-entity-maps-key';
+
+export type MetadataRelatedFlatEntityMapsKeys<T extends AllMetadataName> =
+  MetadataToFlatEntityMapsKey<MetadataManyToOneRelatedMetadataNames<T>>;

packages/twenty-server/src/engine/metadata-modules/flat-entity/types/metadata-related-types.type.ts

@@ -0,0 +1,22 @@
+import { type AllFlatEntityMaps } from 'src/engine/metadata-modules/flat-entity/types/all-flat-entity-maps.type';
+import { type AllMetadataName } from 'src/engine/metadata-modules/flat-entity/types/all-metadata-name.type';
+import { type MetadataRelatedFlatEntityMapsKeys } from 'src/engine/metadata-modules/flat-entity/types/metadata-related-flat-entity-maps-keys.type';
+import { type MetadataToFlatEntityMapsKey } from 'src/engine/metadata-modules/flat-entity/types/metadata-to-flat-entity-maps-key';
+import { type MetadataValidationRelatedMetadataNames } from 'src/engine/metadata-modules/flat-entity/types/metadata-validation-related-metadata-names.type';
+
+export type MetadataFlatEntityAndRelatedFlatEntityMaps<
+  T extends AllMetadataName,
+> = Pick<
+  AllFlatEntityMaps,
+  MetadataRelatedFlatEntityMapsKeys<T> | MetadataToFlatEntityMapsKey<T>
+>;
+
+export type MetadataValidationRelatedFlatEntityMaps<T extends AllMetadataName> =
+  MetadataValidationRelatedMetadataNames<T> extends undefined
+    ? undefined
+    : Pick<
+        AllFlatEntityMaps,
+        MetadataToFlatEntityMapsKey<
+          NonNullable<MetadataValidationRelatedMetadataNames<T>>
+        >
+      >;

packages/twenty-server/src/engine/metadata-modules/flat-entity/types/metadata-to-flat-entity-maps-key.ts

@@ -0,0 +1,4 @@
+import { type AllMetadataName } from 'src/engine/metadata-modules/flat-entity/types/all-metadata-name.type';
+
+export type MetadataToFlatEntityMapsKey<T extends AllMetadataName> =
+  T extends AllMetadataName ? `flat${Capitalize<T>}Maps` : never;

packages/twenty-server/src/engine/metadata-modules/flat-entity/types/metadata-validation-related-metadata-names.type.ts

@@ -0,0 +1,16 @@
+import { type IsEmptyRecord } from 'twenty-shared/types';
+
+import { type ALL_METADATA_REQUIRED_METADATA_FOR_VALIDATION } from 'src/engine/metadata-modules/flat-entity/constant/all-metadata-required-metadata-for-validation.constant';
+import { type AllMetadataName } from 'src/engine/metadata-modules/flat-entity/types/all-metadata-name.type';
+
+export type MetadataValidationRelatedMetadataNames<T extends AllMetadataName> =
+  IsEmptyRecord<
+    (typeof ALL_METADATA_REQUIRED_METADATA_FOR_VALIDATION)[T]
+  > extends true
+    ? undefined
+    : NonNullable<
+        Extract<
+          keyof (typeof ALL_METADATA_REQUIRED_METADATA_FOR_VALIDATION)[T],
+          AllMetadataName
+        >
+      >;

packages/twenty-server/src/engine/metadata-modules/flat-entity/types/metadata-workspace-migration-action.type.ts

@@ -0,0 +1,31 @@
+import { type AllFlatEntityTypesByMetadataName } from 'src/engine/metadata-modules/flat-entity/types/all-flat-entity-types-by-metadata-name';
+import { type AllMetadataName } from 'src/engine/metadata-modules/flat-entity/types/all-metadata-name.type';
+
+export type MetadataWorkspaceMigrationActionsRecord<T extends AllMetadataName> =
+  {
+    [K in 'created' | 'updated' | 'deleted']: MetadataWorkspaceMigrationAction<
+      T,
+      K
+    >[];
+  };
+
+export type MetadataWorkspaceMigrationAction<
+  T extends AllMetadataName,
+  TOperation extends 'created' | 'deleted' | 'updated' =
+    | 'created'
+    | 'deleted'
+    | 'updated',
+> = AllFlatEntityTypesByMetadataName[T]['actions'][TOperation] extends infer Action
+  ? Action extends Array<unknown>
+    ? Action[number]
+    : Action
+  : never;
+
+export type FromWorkspaceMigrationActionToMetadataName<TAction> = {
+  [K in AllMetadataName]: TAction extends AllFlatEntityTypesByMetadataName[K]['actions'][
+    | 'created'
+    | 'deleted'
+    | 'updated']
+    ? K
+    : never;
+}[AllMetadataName];

packages/twenty-server/src/engine/metadata-modules/flat-entity/utils/add-flat-entity-to-flat-entity-and-related-entity-maps-or-throw.util.ts

@@ -0,0 +1,88 @@
+import { ALL_METADATA_NAME_MANY_TO_ONE_RELATIONS } from 'src/engine/metadata-modules/flat-entity/constant/all-metadata-many-to-one-relations.constant';
+import {
+  FlatEntityMapsException,
+  FlatEntityMapsExceptionCode,
+} from 'src/engine/metadata-modules/flat-entity/exceptions/flat-entity-maps.exception';
+import { type AllMetadataName } from 'src/engine/metadata-modules/flat-entity/types/all-metadata-name.type';
+import { type MetadataFlatEntity } from 'src/engine/metadata-modules/flat-entity/types/metadata-flat-entity.type';
+import { type MetadataFlatEntityAndRelatedFlatEntityMaps } from 'src/engine/metadata-modules/flat-entity/types/metadata-related-types.type';
+import { addFlatEntityToFlatEntityMapsOrThrow } from 'src/engine/metadata-modules/flat-entity/utils/add-flat-entity-to-flat-entity-maps-or-throw.util';
+import { findFlatEntityByIdInFlatEntityMapsOrThrow } from 'src/engine/metadata-modules/flat-entity/utils/find-flat-entity-by-id-in-flat-entity-maps-or-throw.util';
+import { getMetadataFlatEntityMapsKey } from 'src/engine/metadata-modules/flat-entity/utils/get-metadata-flat-entity-maps-key.util';
+
+type AddFlatEntityToFlatEntityAndRelatedEntityMapsOrThrowArgs<
+  T extends AllMetadataName,
+> = {
+  metadataName: T;
+  flatEntity: MetadataFlatEntity<T>;
+  flatEntityAndRelatedMaps: MetadataFlatEntityAndRelatedFlatEntityMaps<T>;
+};
+export const addFlatEntityToFlatEntityAndRelatedEntityMapsOrThrow = <
+  T extends AllMetadataName,
+>({
+  metadataName,
+  flatEntity,
+  flatEntityAndRelatedMaps: initialFlatEntityAndRelatedMaps,
+}: AddFlatEntityToFlatEntityAndRelatedEntityMapsOrThrowArgs<T>): MetadataFlatEntityAndRelatedFlatEntityMaps<T> => {
+  const flatEntityMapsKey: keyof MetadataFlatEntityAndRelatedFlatEntityMaps<T> =
+    getMetadataFlatEntityMapsKey(metadataName);
+
+  const updatedFlatEntityMaps = addFlatEntityToFlatEntityMapsOrThrow({
+    flatEntity,
+    flatEntityMaps: initialFlatEntityAndRelatedMaps[flatEntityMapsKey],
+  });
+
+  const manyToOneRelatedMetadataName = Object.entries(
+    ALL_METADATA_NAME_MANY_TO_ONE_RELATIONS[metadataName],
+  );
+
+  return manyToOneRelatedMetadataName.reduce(
+    (flatEntityAndRelatedMaps, [relatedMetadataName, foreignKey]) => {
+      const relatedFlatEntityMapsKey = getMetadataFlatEntityMapsKey(
+        relatedMetadataName as AllMetadataName,
+      );
+      const relatedFLatEntityMetadataMaps =
+        flatEntityAndRelatedMaps[relatedFlatEntityMapsKey];
+
+      const relatedFlatEntity = findFlatEntityByIdInFlatEntityMapsOrThrow({
+        flatEntityId: flatEntity[
+          foreignKey as keyof MetadataFlatEntity<T>
+        ] as string,
+        flatEntityMaps: relatedFLatEntityMetadataMaps,
+      });
+
+      const foreignKeyAggregatorProperty = `${metadataName}Ids`;
+
+      if (
+        !Object.prototype.hasOwnProperty.call(
+          relatedFlatEntity,
+          foreignKeyAggregatorProperty,
+        )
+      ) {
+        throw new FlatEntityMapsException(
+          'Should never occur, invalid cached format',
+          FlatEntityMapsExceptionCode.ENTITY_MALFORMED,
+        );
+      }
+
+      const updatedRelatedFlatEntityMetadataMaps = {
+        ...relatedFlatEntity,
+        [foreignKeyAggregatorProperty]: [
+          ...(relatedFlatEntity[
+            foreignKeyAggregatorProperty as keyof MetadataFlatEntity<T>
+          ] as string[]),
+          flatEntity.id,
+        ],
+      };
+
+      return {
+        ...flatEntityAndRelatedMaps,
+        [relatedFlatEntityMapsKey]: updatedRelatedFlatEntityMetadataMaps,
+      };
+    },
+    {
+      ...initialFlatEntityAndRelatedMaps,
+      [flatEntityMapsKey]: updatedFlatEntityMaps,
+    },
+  );
+};

packages/twenty-server/src/engine/metadata-modules/flat-entity/utils/add-flat-entity-to-flat-entity-maps-or-throw.util.ts

@@ -0,0 +1,36 @@
+import { isDefined } from 'class-validator';
+
+import {
+  FlatEntityMapsException,
+  FlatEntityMapsExceptionCode,
+} from 'src/engine/metadata-modules/flat-entity/exceptions/flat-entity-maps.exception';
+import { type FlatEntityMaps } from 'src/engine/metadata-modules/flat-entity/types/flat-entity-maps.type';
+import { type FlatEntity } from 'src/engine/metadata-modules/flat-entity/types/flat-entity.type';
+
+type AddFlatEntityToFlatEntityMapsOrThrowArgs<T extends FlatEntity> = {
+  flatEntity: T;
+  flatEntityMaps: FlatEntityMaps<T>;
+};
+
+export const addFlatEntityToFlatEntityMapsOrThrow = <T extends FlatEntity>({
+  flatEntity,
+  flatEntityMaps,
+}: AddFlatEntityToFlatEntityMapsOrThrowArgs<T>): FlatEntityMaps<T> => {
+  if (isDefined(flatEntityMaps.byId[flatEntity.id])) {
+    throw new FlatEntityMapsException(
+      'addFlatEntityToFlatEntityMapsOrThrow: flat entity to add already exists',
+      FlatEntityMapsExceptionCode.ENTITY_ALREADY_EXISTS,
+    );
+  }
+
+  return {
+    byId: {
+      ...flatEntityMaps.byId,
+      [flatEntity.id]: flatEntity,
+    },
+    idByUniversalIdentifier: {
+      ...flatEntityMaps.idByUniversalIdentifier,
+      [flatEntity.universalIdentifier]: flatEntity.id,
+    },
+  };
+};

packages/twenty-server/src/engine/metadata-modules/flat-entity/utils/compare-two-flat-entity.util.ts

@@ -0,0 +1,76 @@
+import diff from 'microdiff';
+import { type FromTo } from 'twenty-shared/types';
+import { parseJson } from 'twenty-shared/utils';
+
+import { type AllMetadataName } from 'src/engine/metadata-modules/flat-entity/types/all-metadata-name.type';
+import { type FlatEntityPropertiesToCompare } from 'src/engine/metadata-modules/flat-entity/types/flat-entity-properties-to-compare.type';
+import { type FlatEntityPropertiesUpdates } from 'src/engine/metadata-modules/flat-entity/types/flat-entity-properties-updates.type';
+import { type MetadataFlatEntity } from 'src/engine/metadata-modules/flat-entity/types/metadata-flat-entity.type';
+import { transformFlatEntityForComparison } from 'src/engine/metadata-modules/flat-entity/utils/transform-flat-entity-for-comparison.util';
+
+export const compareTwoFlatEntity = <
+  T extends AllMetadataName,
+  PToCompare extends Extract<
+    FlatEntityPropertiesToCompare<T>,
+    keyof MetadataFlatEntity<T>
+  >,
+  PJsonB extends PToCompare = PToCompare,
+>({
+  fromFlatEntity,
+  toFlatEntity,
+  propertiesToCompare,
+  propertiesToStringify,
+}: FromTo<MetadataFlatEntity<T>, 'flatEntity'> & {
+  propertiesToCompare: readonly PToCompare[];
+  propertiesToStringify: readonly PJsonB[];
+}): FlatEntityPropertiesUpdates<T> => {
+  const [transformedFromFlatEntity, transformedToFlatEntity] = [
+    fromFlatEntity,
+    toFlatEntity,
+  ].map((flatEntity) =>
+    transformFlatEntityForComparison({
+      flatEntity,
+      propertiesToCompare,
+      propertiesToStringify,
+    }),
+  );
+
+  const flatEntityDifferences = diff(
+    transformedFromFlatEntity,
+    transformedToFlatEntity,
+  );
+
+  return flatEntityDifferences.flatMap<FlatEntityPropertiesUpdates<T>[number]>(
+    (difference) => {
+      switch (difference.type) {
+        case 'CHANGE': {
+          const { oldValue, path, value } = difference;
+          const property = path[0] as PToCompare;
+          const isJsonb = propertiesToStringify.includes(
+            property as unknown as PJsonB,
+          );
+
+          if (isJsonb) {
+            return {
+              from: parseJson(oldValue),
+              to: parseJson(value),
+              property,
+            };
+          }
+
+          return {
+            from: oldValue,
+            to: value,
+            property,
+          };
+        }
+        case 'CREATE':
+        case 'REMOVE':
+        default: {
+          // Should never occur, we should only provide null never undefined and so on
+          return [];
+        }
+      }
+    },
+  );
+};

packages/twenty-server/src/engine/metadata-modules/flat-entity/utils/delete-flat-entity-from-flat-entity-maps-or-throw.util.ts

@@ -0,0 +1,40 @@
+import { isDefined, removePropertiesFromRecord } from 'twenty-shared/utils';
+
+import {
+  FlatEntityMapsException,
+  FlatEntityMapsExceptionCode,
+} from 'src/engine/metadata-modules/flat-entity/exceptions/flat-entity-maps.exception';
+import { type FlatEntityMaps } from 'src/engine/metadata-modules/flat-entity/types/flat-entity-maps.type';
+import { type FlatEntity } from 'src/engine/metadata-modules/flat-entity/types/flat-entity.type';
+
+export type DeleteFlatEntityFromFlatEntityMapsOrThrowArgs<
+  T extends FlatEntity,
+> = {
+  entityToDeleteId: string;
+  flatEntityMaps: FlatEntityMaps<T>;
+};
+
+export const deleteFlatEntityFromFlatEntityMapsOrThrow = <
+  T extends FlatEntity,
+>({
+  flatEntityMaps,
+  entityToDeleteId,
+}: DeleteFlatEntityFromFlatEntityMapsOrThrowArgs<T>): FlatEntityMaps<T> => {
+  if (!isDefined(flatEntityMaps.byId[entityToDeleteId])) {
+    throw new FlatEntityMapsException(
+      'deleteFlatEntityFromFlatEntityMapsOrThrow: entity to delete not found',
+      FlatEntityMapsExceptionCode.ENTITY_NOT_FOUND,
+    );
+  }
+
+  const updatedIdByUniversalIdentifierEntries = Object.entries(
+    flatEntityMaps.idByUniversalIdentifier,
+  ).filter(([_universalIdentifier, id]) => id !== entityToDeleteId);
+
+  return {
+    byId: removePropertiesFromRecord(flatEntityMaps.byId, [entityToDeleteId]),
+    idByUniversalIdentifier: Object.fromEntries(
+      updatedIdByUniversalIdentifierEntries,
+    ),
+  };
+};

packages/twenty-server/src/engine/metadata-modules/flat-entity/utils/find-flat-entity-by-id-in-flat-entity-maps-or-throw.util.ts

@@ -0,0 +1,33 @@
+import { t } from '@lingui/core/macro';
+import { isDefined } from 'twenty-shared/utils';
+
+import {
+  FlatEntityMapsException,
+  FlatEntityMapsExceptionCode,
+} from 'src/engine/metadata-modules/flat-entity/exceptions/flat-entity-maps.exception';
+import { type FlatEntityMaps } from 'src/engine/metadata-modules/flat-entity/types/flat-entity-maps.type';
+import { type FlatEntity } from 'src/engine/metadata-modules/flat-entity/types/flat-entity.type';
+
+export type FindFlatEntityByIdInFlatEntityMapsOrThrowArgs<
+  T extends FlatEntity,
+> = {
+  flatEntityMaps: FlatEntityMaps<T>;
+  flatEntityId: string;
+};
+export const findFlatEntityByIdInFlatEntityMapsOrThrow = <
+  T extends FlatEntity,
+>({
+  flatEntityMaps,
+  flatEntityId,
+}: FindFlatEntityByIdInFlatEntityMapsOrThrowArgs<T>): T => {
+  const flatEntity = flatEntityMaps.byId[flatEntityId];
+
+  if (!isDefined(flatEntity)) {
+    throw new FlatEntityMapsException(
+      t`Could not find flat entity in maps`,
+      FlatEntityMapsExceptionCode.ENTITY_NOT_FOUND,
+    );
+  }
+
+  return flatEntity;
+};

packages/twenty-server/src/engine/metadata-modules/flat-entity/utils/find-flat-entity-by-id-in-flat-entity-maps.util.ts

@@ -0,0 +1,15 @@
+import { type FlatEntity } from 'src/engine/metadata-modules/flat-entity/types/flat-entity.type';
+import {
+  findFlatEntityByIdInFlatEntityMapsOrThrow,
+  type FindFlatEntityByIdInFlatEntityMapsOrThrowArgs,
+} from 'src/engine/metadata-modules/flat-entity/utils/find-flat-entity-by-id-in-flat-entity-maps-or-throw.util';
+
+export const findFlatEntityByIdInFlatEntityMaps = <T extends FlatEntity>(
+  args: FindFlatEntityByIdInFlatEntityMapsOrThrowArgs<T>,
+): T | undefined => {
+  try {
+    return findFlatEntityByIdInFlatEntityMapsOrThrow(args);
+  } catch {
+    return undefined;
+  }
+};

packages/twenty-server/src/engine/metadata-modules/flat-entity/utils/find-many-flat-entity-by-id-in-flat-entity-maps-or-throw.util.ts

@@ -0,0 +1,25 @@
+import { isDefined } from 'twenty-shared/utils';
+
+import { type FlatEntityMaps } from 'src/engine/metadata-modules/flat-entity/types/flat-entity-maps.type';
+import { type FlatEntity } from 'src/engine/metadata-modules/flat-entity/types/flat-entity.type';
+import { getSubFlatEntityMapsOrThrow } from 'src/engine/metadata-modules/flat-entity/utils/get-sub-flat-entity-maps-or-throw.util';
+
+export type FindManyFlatEntityByIdInFlatEntityMapsOrThrowArgs<
+  T extends FlatEntity,
+> = {
+  flatEntityMaps: FlatEntityMaps<T>;
+  flatEntityIds: string[];
+};
+export const findManyFlatEntityByIdInFlatEntityMapsOrThrow = <
+  T extends FlatEntity,
+>({
+  flatEntityMaps,
+  flatEntityIds,
+}: FindManyFlatEntityByIdInFlatEntityMapsOrThrowArgs<T>): T[] => {
+  const subFlatEntityMaps = getSubFlatEntityMapsOrThrow<T>({
+    flatEntityIds,
+    flatEntityMaps,
+  });
+
+  return Object.values(subFlatEntityMaps.byId).filter(isDefined);
+};

packages/twenty-server/src/engine/metadata-modules/flat-entity/utils/get-metadata-flat-entity-maps-key.util.ts

@@ -0,0 +1,9 @@
+import { capitalize } from 'twenty-shared/utils';
+
+import { type AllMetadataName } from 'src/engine/metadata-modules/flat-entity/types/all-metadata-name.type';
+import { type MetadataToFlatEntityMapsKey } from 'src/engine/metadata-modules/flat-entity/types/metadata-to-flat-entity-maps-key';
+
+export const getMetadataFlatEntityMapsKey = <T extends AllMetadataName>(
+  metadataName: T,
+): MetadataToFlatEntityMapsKey<T> =>
+  `flat${capitalize(metadataName)}Maps` as MetadataToFlatEntityMapsKey<T>;

packages/twenty-server/src/engine/metadata-modules/flat-entity/utils/get-sub-flat-entity-maps-or-throw.util.ts

@@ -0,0 +1,25 @@
+import { EMPTY_FLAT_ENTITY_MAPS } from 'src/engine/metadata-modules/flat-entity/constant/empty-flat-entity-maps.constant';
+import { type FlatEntityMaps } from 'src/engine/metadata-modules/flat-entity/types/flat-entity-maps.type';
+import { type FlatEntity } from 'src/engine/metadata-modules/flat-entity/types/flat-entity.type';
+import { addFlatEntityToFlatEntityMapsOrThrow } from 'src/engine/metadata-modules/flat-entity/utils/add-flat-entity-to-flat-entity-maps-or-throw.util';
+import { findFlatEntityByIdInFlatEntityMapsOrThrow } from 'src/engine/metadata-modules/flat-entity/utils/find-flat-entity-by-id-in-flat-entity-maps-or-throw.util';
+
+export const getSubFlatEntityMapsOrThrow = <T extends FlatEntity>({
+  flatEntityIds,
+  flatEntityMaps,
+}: {
+  flatEntityMaps: FlatEntityMaps<T>;
+  flatEntityIds: string[];
+}): FlatEntityMaps<T> => {
+  return flatEntityIds.reduce<FlatEntityMaps<T>>((acc, flatEntityId) => {
+    const flatEntity = findFlatEntityByIdInFlatEntityMapsOrThrow({
+      flatEntityId,
+      flatEntityMaps,
+    });
+
+    return addFlatEntityToFlatEntityMapsOrThrow({
+      flatEntity,
+      flatEntityMaps: acc,
+    });
+  }, EMPTY_FLAT_ENTITY_MAPS);
+};

packages/twenty-server/src/engine/metadata-modules/flat-entity/utils/replace-flat-entity-in-flat-entity-maps-or-throw.util.ts

@@ -0,0 +1,25 @@
+import { type FlatEntityMaps } from 'src/engine/metadata-modules/flat-entity/types/flat-entity-maps.type';
+import { type FlatEntity } from 'src/engine/metadata-modules/flat-entity/types/flat-entity.type';
+import { addFlatEntityToFlatEntityMapsOrThrow } from 'src/engine/metadata-modules/flat-entity/utils/add-flat-entity-to-flat-entity-maps-or-throw.util';
+import { deleteFlatEntityFromFlatEntityMapsOrThrow } from 'src/engine/metadata-modules/flat-entity/utils/delete-flat-entity-from-flat-entity-maps-or-throw.util';
+
+export type ReplaceFlatEntityInFlatEntityMapsOrThrowArgs<T extends FlatEntity> =
+  {
+    flatEntity: T;
+    flatEntityMaps: FlatEntityMaps<T>;
+  };
+
+export const replaceFlatEntityInFlatEntityMapsOrThrow = <T extends FlatEntity>({
+  flatEntity,
+  flatEntityMaps,
+}: ReplaceFlatEntityInFlatEntityMapsOrThrowArgs<T>): FlatEntityMaps<T> => {
+  const flatEntityMapsToReplace = deleteFlatEntityFromFlatEntityMapsOrThrow({
+    flatEntityMaps,
+    entityToDeleteId: flatEntity.id,
+  });
+
+  return addFlatEntityToFlatEntityMapsOrThrow({
+    flatEntity,
+    flatEntityMaps: flatEntityMapsToReplace,
+  });
+};

packages/twenty-server/src/engine/metadata-modules/flat-entity/utils/transform-flat-entity-for-comparison.util.ts

@@ -0,0 +1,37 @@
+import { type FlatEntity } from 'src/engine/metadata-modules/flat-entity/types/flat-entity.type';
+import { orderObjectProperties } from 'src/engine/workspace-manager/workspace-sync-metadata/comparators/utils/order-object-properties.util';
+
+export function transformFlatEntityForComparison<
+  TFlatEntity extends FlatEntity,
+  PToCompare extends keyof TFlatEntity,
+  PJsonB extends PToCompare,
+>({
+  flatEntity,
+  propertiesToCompare,
+  propertiesToStringify,
+}: {
+  flatEntity: TFlatEntity;
+  propertiesToCompare: readonly PToCompare[];
+  propertiesToStringify: readonly PJsonB[];
+}): Pick<TFlatEntity, PToCompare> {
+  return propertiesToCompare.reduce(
+    (flatEntityAccumulator, propertyToCompare) => {
+      const currentValue = flatEntity[propertyToCompare];
+
+      if (propertiesToStringify.includes(propertyToCompare as PJsonB)) {
+        const orderedValue = orderObjectProperties(currentValue);
+
+        return {
+          ...flatEntityAccumulator,
+          [propertyToCompare]: JSON.stringify(orderedValue),
+        };
+      }
+
+      return {
+        ...flatEntityAccumulator,
+        [propertyToCompare]: currentValue,
+      };
+    },
+    {} as Pick<TFlatEntity, PToCompare>,
+  );
+}