feat: add schema-aligned db types and test factory primitives

backend/src/api/public/v1/members/createMember.ts

@@ -3,7 +3,7 @@ import { z } from 'zod'
 
 import { captureApiChange, memberCreateAction, memberEditIdentitiesAction } from '@crowd/audit-logs'
 import { getProperDisplayName } from '@crowd/common'
-import { insertManyMemberIdentities, createMember as insertMember } from '@crowd/data-access-layer'
+import { createMember as insertMember, insertMemberIdentities } from '@crowd/data-access-layer'
 import { MemberIdentityType } from '@crowd/types'
 
 import { optionsQx } from '@/database/sequelizeQueryExecutor'
@@ -49,7 +49,7 @@ export async function createMember(req: Request, res: Response): Promise<void> {
         manuallyCreated: true,
       })
 
-      const dbIdentities = await insertManyMemberIdentities(
+      const dbIdentities = await insertMemberIdentities(
         tx,
         identities.map((identity) => ({
           ...identity,

backend/src/api/public/v1/members/identities/createMemberIdentity.ts

@@ -7,7 +7,7 @@ import {
   MemberField,
   findMemberById,
   findMemberIdentitiesByValue,
-  createMemberIdentity as insertMemberIdentity,
+  insertMemberIdentities,
   touchMemberUpdatedAt,
   updateMemberIdentity,
 } from '@crowd/data-access-layer'
@@ -69,20 +69,23 @@ export async function createMemberIdentity(req: Request, res: Response): Promise
             alreadyExisted = true
             result = exactMatch
           } else {
-            result = await insertMemberIdentity(
+            const [created] = await insertMemberIdentities(
               tx,
-              {
-                memberId,
-                platform: data.platform,
-                value: normalizedValue,
-                type: data.type,
-                source: data.source,
-                verified: data.verified,
-                verifiedBy: data.verifiedBy,
-              },
+              [
+                {
+                  memberId,
+                  platform: data.platform,
+                  value: normalizedValue,
+                  type: data.type,
+                  source: data.source,
+                  verified: data.verified,
+                  verifiedBy: data.verifiedBy,
+                },
+              ],
               true,
               true,
             )
+            result = created
           }
 
           // A verified identity confirms the same value for this member, so keep same-value

backend/src/api/public/v1/members/project-affiliations/patchProjectAffiliation.ts

@@ -85,14 +85,16 @@ export async function patchProjectAffiliation(req: Request, res: Response): Prom
         if (affiliations.length > 0) {
           await insertMemberSegmentAffiliations(
             tx,
-            memberId,
-            projectId,
             affiliations.map((a) => ({
+              memberId,
+              segmentId: projectId,
               organizationId: a.organizationId,
               dateStart: a.dateStart.toISOString(),
               dateEnd: a.dateEnd?.toISOString() ?? null,
+              verified: true,
               verifiedBy: verifiedBy!,
             })),
+            true,
           )
         }
       })

backend/src/database/repositories/member/memberAffiliationsRepository.ts

@@ -2,7 +2,7 @@ import { OrganizationField, queryOrgs } from '@crowd/data-access-layer'
 import {
   deleteMemberSegmentAffiliations,
   fetchMemberAffiliations,
-  insertMemberAffiliations,
+  insertMemberSegmentAffiliations,
 } from '@crowd/data-access-layer/src/member_segment_affiliations'
 import { fetchManySegments } from '@crowd/data-access-layer/src/segments'
 import { IMemberAffiliation, IOrganization, SegmentData } from '@crowd/types'
@@ -89,8 +89,17 @@ class MemberAffiliationsRepository {
       await deleteMemberSegmentAffiliations(qx, { memberId })
 
       if (data?.length > 0) {
-        //  Insert multiple member affiliations
-        await insertMemberAffiliations(qx, memberId, data)
+        await insertMemberSegmentAffiliations(
+          qx,
+          data.map((item) => ({
+            memberId,
+            segmentId: item.segmentId,
+            organizationId: item.organizationId,
+            dateStart: item.dateStart || null,
+            dateEnd: item.dateEnd || null,
+          })),
+          true,
+        )
       }
 
       await SequelizeRepository.commitTransaction(transaction)

backend/src/database/repositories/memberRepository.ts

@@ -18,11 +18,11 @@ import {
 import { BotDetectionService, CommonMemberService } from '@crowd/common_services'
 import {
   OrganizationField,
-  createMemberIdentity,
   deleteMemberIdentities,
   deleteMemberIdentitiesByCombinations,
   findAlreadyExistingVerifiedIdentities,
   getLastActivitiesForMembers,
+  insertMemberIdentities,
   queryActivityRelations,
   queryOrgs,
   updateVerifiedFlag,
@@ -33,7 +33,7 @@ import { addMemberNoMerge, removeMemberToMerge } from '@crowd/data-access-layer/
 import {
   deleteMemberSegmentAffiliations,
   findMemberAffiliations,
-  insertMemberAffiliations,
+  insertMemberSegmentAffiliations,
 } from '@crowd/data-access-layer/src/member_segment_affiliations'
 import {
   MemberField,
@@ -159,8 +159,9 @@ class MemberRepository {
     const subprojectIds = await getSegmentSubprojectIds(qx, currentSegments)
 
     if (data.identities) {
-      for (const i of data.identities as IMemberIdentity[]) {
-        await createMemberIdentity(qx, {
+      await insertMemberIdentities(
+        qx,
+        (data.identities as IMemberIdentity[]).map((i) => ({
           memberId: record.id,
           platform: i.platform,
           type: i.type,
@@ -169,15 +170,16 @@ class MemberRepository {
           integrationId: i.integrationId || null,
           verified: i.verified,
           source: i.source,
-        })
-      }
+        })),
+      )
     } else if (data.username) {
       const username: PlatformIdentities = mapUsernameToIdentities(data.username)
 
+      const identitiesToInsert = []
       for (const platform of Object.keys(username) as PlatformType[]) {
         const identities: any[] = username[platform]
         for (const identity of identities) {
-          await createMemberIdentity(qx, {
+          identitiesToInsert.push({
             memberId: record.id,
             platform,
             value: identity.value ? identity.value : identity.username,
@@ -189,6 +191,10 @@ class MemberRepository {
           })
         }
       }
+
+      if (identitiesToInsert.length > 0) {
+        await insertMemberIdentities(qx, identitiesToInsert)
+      }
     }
 
     await includeMemberToSegments(qx, record.id, subprojectIds)
@@ -1049,8 +1055,9 @@ class MemberRepository {
     }
 
     if (data.identitiesToCreate && data.identitiesToCreate.length > 0) {
-      for (const i of data.identitiesToCreate) {
-        await createMemberIdentity(qx, {
+      await insertMemberIdentities(
+        qx,
+        data.identitiesToCreate.map((i) => ({
           memberId: record.id,
           platform: i.platform,
           value: i.value,
@@ -1059,8 +1066,8 @@ class MemberRepository {
           integrationId: i.integrationId || null,
           verified: i.verified !== undefined ? i.verified : !!manualChange,
           source: i.source,
-        })
-      }
+        })),
+      )
     }
 
     if (data.identitiesToUpdate && data.identitiesToUpdate.length > 0) {
@@ -1094,6 +1101,7 @@ class MemberRepository {
         const platformsToDelete: string[] = []
         const valuesToDelete: string[] = []
         const typesToDelete: MemberIdentityType[] = []
+        const identitiesToInsert = []
 
         for (const platform of platforms) {
           const identities = data.username[platform]
@@ -1112,7 +1120,7 @@ class MemberRepository {
               (identity.username && identity.username !== '') ||
               (identity.value && identity.value !== '')
             ) {
-              await createMemberIdentity(qx, {
+              identitiesToInsert.push({
                 memberId: record.id,
                 platform,
                 value: identity.value ? identity.value : identity.username,
@@ -1126,6 +1134,10 @@ class MemberRepository {
           }
         }
 
+        if (identitiesToInsert.length > 0) {
+          await insertMemberIdentities(qx, identitiesToInsert)
+        }
+
         if (platformsToDelete.length > 0) {
           await deleteMemberIdentitiesByCombinations(qx, {
             memberId: record.id,
@@ -1207,7 +1219,17 @@ class MemberRepository {
           return
         }
 
-        await insertMemberAffiliations(qx, memberId, data)
+        await insertMemberSegmentAffiliations(
+          qx,
+          data.map((item) => ({
+            memberId,
+            segmentId: item.segmentId,
+            organizationId: item.organizationId,
+            dateStart: item.dateStart || null,
+            dateEnd: item.dateEnd || null,
+          })),
+          true,
+        )
       }),
     )
   }

backend/src/database/repositories/organizationRepository.ts

@@ -16,7 +16,6 @@ import {
   IDbOrganization,
   OrgIdentityField,
   OrganizationField,
-  addOrgIdentity,
   addOrgsToSegments,
   cleanUpOrgIdentities,
   cleanupForOganization,
@@ -27,6 +26,7 @@ import {
   findManyOrgAttributes,
   findOrgAttributes,
   findOrgById,
+  insertOrganizationIdentities,
   markOrgAttributeDefault,
   queryOrgIdentities,
   updateOrgIdentityVerifiedFlag,
@@ -619,16 +619,22 @@ class OrganizationRepository {
   ): Promise<void> {
     const qx = SequelizeRepository.getQueryExecutor(options)
 
-    await addOrgIdentity(qx, {
-      organizationId,
-      platform: identity.platform,
-      source: identity.source,
-      sourceId: identity.sourceId || null,
-      value: identity.value,
-      type: identity.type,
-      verified: identity.verified,
-      integrationId: identity.integrationId || null,
-    })
+    await insertOrganizationIdentities(
+      qx,
+      [
+        {
+          organizationId,
+          platform: identity.platform,
+          source: identity.source,
+          sourceId: identity.sourceId || null,
+          value: identity.value,
+          type: identity.type,
+          verified: identity.verified,
+          integrationId: identity.integrationId || null,
+        },
+      ],
+      false,
+    )
   }
 
   static async getIdentities(

backend/src/services/member/memberIdentityService.ts

@@ -3,7 +3,7 @@ import lodash from 'lodash'
 
 import { captureApiChange, memberEditIdentitiesAction } from '@crowd/audit-logs'
 import { Error404, Error409 } from '@crowd/common'
-import { createMemberIdentity, findIdentitiesForMembers } from '@crowd/data-access-layer'
+import { findIdentitiesForMembers, insertMemberIdentities } from '@crowd/data-access-layer'
 import {
   deleteMemberIdentity,
   fetchMemberIdentities,
@@ -77,7 +77,7 @@ export default class MemberIdentityService extends LoggerBase {
           }
 
           // Create member identity
-          await createMemberIdentity(qx, { ...data, memberId })
+          await insertMemberIdentities(qx, [{ ...data, memberId }])
 
           await touchMemberUpdatedAt(qx, memberId)
 
@@ -151,9 +151,10 @@ export default class MemberIdentityService extends LoggerBase {
           }
 
           // Create member identities
-          for (const identity of data) {
-            await createMemberIdentity(qx, { ...identity, memberId })
-          }
+          await insertMemberIdentities(
+            qx,
+            data.map((identity) => ({ ...identity, memberId })),
+          )
 
           await touchMemberUpdatedAt(qx, memberId)
 

docs/adr/0006-database-schema-types-as-source-of-truth.md

@@ -0,0 +1,61 @@
+# ADR-0006: Database schema types as the source of truth
+
+**Date**: 2026-07-09
+**Status**: accepted
+**Deciders**: Yeganathan S
+
+## Context
+
+Working with entity types in CDP is messy. The same concepts appear as overlapping shapes across `@crowd/types`, DAL inputs, merge helpers, and API/domain models — often incomplete relative to the database, with inconsistent nullability and no single source of truth. That makes it hard to change data access safely, reuse types across packages, and keep tests aligned with production.
+
+We need a durable way to model persisted data that the rest of the codebase can build on, without inventing yet another parallel type family per feature.
+
+## Decision
+
+Treat the database schema as the source of truth for persisted entity shapes. Introduce a dedicated `db/` area under `@crowd/types` for schema-aligned row types, and derive narrower types (create/update payloads, factory options, domain views) from those via composition (`Pick`, `Partial`, `Omit`, intersections) rather than hand-maintaining duplicates.
+
+These types live in `@crowd/types`, not in the data-access layer: they are shared vocabulary for backend, workers, libraries, and test utilities. DAL remains responsible for queries and persistence; it consumes and returns these types instead of owning the canonical shapes.
+
+This applies to entities generally (members, identities, organizations, and others as we touch them), not only the first tables we migrate.
+
+## Conventions
+
+These rules exist so people (and tools) do not confuse the row type with write payloads, or nullability with “field may be omitted.”
+
+1. **One row type per table** — describes the entity as stored. Field nullability matches the schema. Database defaults do not make read fields optional.
+2. **Write payloads are derived from the row type** — use `Pick`, `Partial`, `Omit`, and intersections instead of duplicating the full interface.
+3. **Nullability ≠ optionality** — `| null` means the column can store null; `?` / `Partial` means the caller may omit the key. Both can appear; they mean different things.
+4. **System-owned fields stay off write payloads** — things like tenant id, audit timestamps, and soft-delete markers are set by persistence code, not by every caller.
+5. **Layers that supply defaults may widen further** — e.g. a test factory can take a partial write payload and fill required fields before calling DAL. That does not change the row type or the DAL contract.
+
+## Alternatives Considered
+
+### Alternative 1: Keep defining types ad hoc next to each feature
+- **Pros**: Fast locally; no cross-package coordination.
+- **Cons**: Duplicates and drift continue; nullability and field sets disagree across call sites.
+- **Why not**: That is the current pain. It does not scale as more packages share the same entities.
+
+### Alternative 2: Own canonical entity types inside `@crowd/data-access-layer`
+- **Pros**: Types sit next to SQL; easy for DAL authors to update.
+- **Cons**: Anything that needs a row shape (test-kit, common services, workers, backend) must depend on DAL or re-copy types.
+- **Why not**: Row shapes are shared contracts, not DAL implementation details. Putting them in `@crowd/types` keeps the dependency graph thin and matches how other shared models already live.
+
+### Alternative 3: Generate types from the schema (e.g. introspection tooling)
+- **Pros**: Always in sync with migrations; less manual work.
+- **Cons**: Tooling and review process are not in place; generated output can be noisy and hard to evolve with domain naming.
+- **Why not**: Manual schema-aligned types are enough to establish the pattern now. Generation can be revisited once the convention is stable.
+
+## Consequences
+
+### Positive
+- One place to look for “what does this table look like in TypeScript.”
+- Downstream APIs and tests extend from the same base instead of inventing parallel models.
+- Clearer package boundaries: `@crowd/types` for shapes, DAL for access, factories/services for composition.
+
+### Negative
+- Existing aliases and legacy shapes (`MemberRow`, feature-local inputs, etc.) will coexist during migration.
+- Authors must update `db/` types when migrations change columns or nullability.
+
+### Risks
+- **Partial adoption** — mitigated by migrating types when a table is touched (factories, DAL hardening, new features), not a big-bang rewrite.
+- **Drift from schema** — mitigated by checking live schema (or migrations) when adding or changing `db/` types; optional codegen later.