Skip to main content

People collection – Velocity ID

Canonical identifier: Velocity ID​

Every person in the people collection has a Velocity ID as their Firestore document ID.

  • Format: vel_ + 12 URL-safe alphanumeric characters (e.g. vel_a1b2c3d4e5f6).
  • Generated by: generateVelocityId() from @/lib/utils/velocity-id.
  • Used everywhere: URLs (/engineers/{velocityId}), APIs, projectTeam.personId, engineerAllocations.engineerId, work-arrangements, etc.

New people are always created with a Velocity ID (Team UI, CSV import, scripts). No email or Jira account id is used as the document ID for new records.

Lookups (backward compatibility)​

APIs still resolve a person when the request uses an old identifier (for existing links or pre-migration data):

  1. Document ID – people.doc(identifier) (Velocity ID or legacy id before migration).
  2. Email – if the identifier contains @.
  3. Jira / external id – if not found, match by jiraAccountId or externalAccounts[].externalId.

So /engineers/vel_abc123 is canonical; /engineers/user@gamuda.tech or /engineers/23758 continue to work until you run the migration and update links.

Migrating existing data​

If you have existing people whose document IDs are not Velocity IDs (e.g. email or numeric/Jira id), run the migration once:

cd apps/web
npx tsx scripts/migrate-people-to-velocity-id.ts              # dry run
npx tsx scripts/migrate-people-to-velocity-id.ts --execute    # apply

The script:

  • Finds every people doc whose id does not start with vel_.
  • Generates a new Velocity ID, creates a new document with that id, updates all references (projectTeam, engineerAllocations, work-arrangements, work-arrangement-quotas), then deletes the old document.

After migration, every person has a Velocity ID and all references point to it.