ID Mapping
Data Entity
Description
Maps temporary client-generated IDs (used for offline-created entities) to their server-assigned permanent IDs after synchronization, enabling the mobile app to resolve references in the mutation outbox and local database after sync completes.
Data Structure
| Name | Type | Description | Constraints |
|---|---|---|---|
id |
uuid |
Primary key | PKrequiredunique |
user_id |
uuid |
The user who created the offline entity; scopes mappings to prevent cross-user leakage | required |
entity_type |
enum |
The type of entity this mapping covers | required |
client_id |
string |
Temporary UUID generated client-side before the entity existed on the server | required |
server_id |
uuid |
Permanent server-assigned UUID returned after the mutation was successfully synced | - |
status |
enum |
Current resolution state of this mapping | required |
organization_id |
uuid |
Organization context for tenant scoping and cleanup | required |
created_at |
datetime |
When the client-side entity was first created offline | required |
resolved_at |
datetime |
When the server_id was successfully assigned | - |
retry_count |
integer |
Number of sync attempts made for this mapping; used for backoff and failure detection | required |
last_error |
text |
Last sync error message, stored for debugging failed mappings | - |
Database Indexes
idx_id_mappings_user_id
Columns: user_id
idx_id_mappings_client_id_entity_type
Columns: client_id, entity_type
idx_id_mappings_status
Columns: status
idx_id_mappings_organization_id
Columns: organization_id
Validation Rules
client_id_uuid_format
error
Validation failed
entity_type_valid_enum
error
Validation failed
unique_client_id_per_entity_type
error
Validation failed
user_id_references_existing_user
error
Validation failed
Business Rules
client_id_immutable
client_id must never be changed after creation; it is a stable reference used by the mutation outbox to rewrite foreign keys
resolved_requires_server_id
Status may only be set to 'resolved' when server_id is present and non-null
user_scoped_lookup
All lookups by client_id must include user_id to prevent cross-user ID collisions
outbox_rewrite_on_resolve
When a mapping transitions to 'resolved', the mutation outbox must rewrite all pending mutations that reference the client_id with the server_id before those mutations are dispatched
max_retry_failure
If retry_count exceeds 10, status is automatically set to 'failed' and the user is notified of the unresolvable conflict