# IDs

Every entity in the Lavanda platform is addressed by an **ID**. Across our services these IDs are
backed by a mix of underlying datatypes:

- **BigInt** — sequential 64-bit integers, common on older records in the PMS.
- **NanoId** — short, URL-safe, randomly generated strings (e.g. `V1StGXR8_Z5jdHi6B-myT`).
- **UUIDv4** — 128-bit random identifiers (e.g. `9f290d93-3d97-4b3f-8a1e-2b6c4d5e6f70`).
- **Other schemes** — additional formats may be introduced over time as new domains and services
  come online.

## The ID value is stable — the datatype is not

An ID, once assigned to an entity, **will not change**. The record you fetched yesterday keeps the
same identifier tomorrow.

What **is** subject to change is the *datatype* used to represent that identifier. As entities are
migrated between services, or as domains are re-modelled, an entity that started life with a
**BigInt** ID may later be represented as a **NanoId** or a **UUIDv4**. This can happen at any time
and without a breaking-change announcement, because from the consumer's perspective the identifier
is still just an opaque token.

This is also why every identifier field in our GraphQL schema uses the `ID` scalar rather than
`String` or `Int` — the `ID` scalar is intentionally opaque and serialises as a string on the wire.

## Model every ID as a string

For forwards compatibility, **all API and webhook consumers must model IDs as strings.**

- **Do** store IDs in `string` / `text` columns and string-typed fields.
- **Do** treat an ID as an opaque token: compare it for equality, pass it back verbatim in
  subsequent requests, and use it as a map key.
- **Don't** parse an ID into an integer, assume it is numeric, or assume a fixed length or format.
- **Don't** rely on IDs being sequential, sortable, or monotonically increasing — NanoIds and
  UUIDs carry no ordering guarantees.
- **Don't** generate, derive, or validate IDs on the client side against a specific format.

A consumer that stores a BigInt ID in a numeric column will break the moment that entity's ID
becomes a NanoId or UUID. A consumer that treats every ID as an opaque string keeps working through
any future datatype migration with no changes required.

## Summary

| Aspect | Guarantee |
| --- | --- |
| The ID **value** | Stable — never changes for a given entity |
| The ID **datatype** | May change at any time (BigInt → NanoId → UUIDv4 → …) |
| How to **model** it | Always as an opaque **string** |