Entity Model & Public IDs

Public ID rule

No raw database IDs are ever exposed externally. Every entity has a prefixed public ID in the format {prefix}_{16 hex chars}.

Public IDs appear in:

All API responses
All frontend URLs (/customers/cus_abc123)
All cross-entity references in the UI

Entity prefixes

Prefix	Entity	Example
`cus_`	Customer (User)	`cus_a1b2c3d4e5f6a7b8`
`emp_`	Employer	`emp_a1b2c3d4e5f6a7b8`
`can_`	Candidate	`can_a1b2c3d4e5f6a7b8`
`ord_`	Order	`ord_a1b2c3d4e5f6a7b8`
`pol_`	Policy	`pol_a1b2c3d4e5f6a7b8`
`res_`	Residency Application	`res_a1b2c3d4e5f6a7b8`
`wrk_`	Work Permit Application	`wrk_a1b2c3d4e5f6a7b8`
`tur_`	Turquoise Card Application	`tur_a1b2c3d4e5f6a7b8`
`cit_`	Citizenship Application	`cit_a1b2c3d4e5f6a7b8`
`rea_`	Real Estate Transaction	`rea_a1b2c3d4e5f6a7b8`
`doc_`	Document	`doc_a1b2c3d4e5f6a7b8`
`tsk_`	Task	`tsk_a1b2c3d4e5f6a7b8`
`pay_`	Payment	`pay_a1b2c3d4e5f6a7b8`
`ren_`	Renewal	`ren_a1b2c3d4e5f6a7b8`
`sta_`	Staff Member	`sta_a1b2c3d4e5f6a7b8`

Core entities

Customer (User)

The central entity. Every order, policy, application, task, communication, and renewal is linked to a customer.

Key fields: name, surname, email, phone, nationality, assigned_agent

Order

A customer-initiated service request. Orders are the entry point for most workflows.

Key fields: service_type, status, WorkflowStatus, linked applications

Policy

An issued insurance policy. Can have renewals and documents attached.

Key fields: policy_type, policy_number, insurer, start_date, end_date, premium_amount

Applications

Workflow-specific entities linked to orders:

ResidencyApplication — residence permit workflows
WorkPermitApplication — work permit workflows
TurquoiseCardApplication — Turquoise Card applications
CitizenshipApplication — citizenship applications
RealEstateTransaction — property purchase transactions

Task

An actionable item assigned to a staff member. Has priority, status, due date, and SLA hours.

Priorities: LOW · MEDIUM · HIGH · URGENT
Statuses: OPEN · IN_PROGRESS · COMPLETED · CANCELLED · OVERDUE

Renewal

Tracks expiry and renewal timing for permits and policies.

Key fields: service_type, due_date, days_until_due, status
Threshold alerts: 90 · 60 · 30 · 14 · 7 days before expiry

Communication

Every customer interaction logged in one place.

Types: WHATSAPP · EMAIL · SMS · INTERNAL_NOTE · CALL_LOG
Directions: INBOUND · OUTBOUND · INTERNAL

TimelineEvent

The immutable audit log of everything that happened. See Timeline Architecture.

Document

A file attached to a customer, order, or application.

Types: PASSPORT · RESIDENCE_PERMIT · TAPU · INSURANCE_POLICY · WORK_PERMIT · BIOMETRIC · OTHER
Statuses: PENDING · VERIFIED · REJECTED · EXPIRED

ID resolution pattern

When an API receives an ID, it checks whether it’s a public ID (prefixed) or a raw DB ID:

// If the ID starts with the entity prefix, look up by public_id
// Otherwise, treat as internal DB ID
function resolveUserId(id: string) {
  return id.startsWith('cus_')
    ? { public_id: id }
    : { id };
}

This ensures backward compatibility while migrating to public IDs throughout.