Skip to content

Open source personal finance application

docs: drop legacy local_ id rationale from tech-decisions

Ilya Komichevd0cfb8bdb59b
diff --git a/docs/content/en/3.reference/05.tech-decisions.md b/docs/content/en/3.reference/05.tech-decisions.md
index ef85adc0..171b9164 100644
--- a/docs/content/en/3.reference/05.tech-decisions.md
+++ b/docs/content/en/3.reference/05.tech-decisions.md
@@ -39,12 +39,12 @@ All Pinia stores use `shallowRef<Map | null>` instead of `ref` for the items col
**Why:**
`ref` would deep-track every nested property of potentially thousands of transaction/wallet/category objects. `shallowRef` only tracks the top-level reference. The explicit "create new object" pattern on write is a deliberate trade-off: slightly more verbose stores, significantly lower reactivity overhead.
-## Client-generated UUIDs (no `local_` prefix, no remapping)
+## Client-generated UUIDs (no remapping)
-Every new entity gets a UUID generated on the client (`crypto.randomUUID()` or equivalent) before the local write. That UUID is the permanent ID - there is no temporary `local_` prefix and no remapping after server acknowledgement.
+Every new entity gets a UUID generated on the client (`crypto.randomUUID()` or equivalent) before the local write. That UUID is the permanent ID - the client owns it for the entire offline lifecycle and it is never remapped.
-**Why no `local_` IDs:**
-The previous backend used a temporary `local_abc123` prefix, then remapped to a server-assigned ID after the mutation succeeded. This required tracking pending ID remaps across all stores and cascading updates (e.g., trns referencing a newly-created wallet). With PowerSync, the client owns the ID permanently: Supabase schema uses `text` PKs with `default gen_random_uuid()::text`, so whatever UUID the client generates is accepted as-is. No remapping, no cascade complexity.
+**Why:**
+PowerSync queues a write locally and uploads it later, so the ID must be stable before the server ever sees the row. Supabase schema uses `text` PKs with `default gen_random_uuid()::text`, so whatever UUID the client generates is accepted as-is. No server round-trip to assign IDs, no remapping, no cascade updates to rows that reference a newly-created entity.
**Why no FK constraints in Postgres:**
PowerSync upload order is not guaranteed. A transaction referencing a wallet may be uploaded before the wallet itself. FK constraints would reject valid data. Referential integrity is enforced by app logic instead.
diff --git a/docs/content/ru/3.reference/05.tech-decisions.md b/docs/content/ru/3.reference/05.tech-decisions.md
index 150cb466..c4cb9445 100644
--- a/docs/content/ru/3.reference/05.tech-decisions.md
+++ b/docs/content/ru/3.reference/05.tech-decisions.md
@@ -39,12 +39,12 @@ OPFS (Origin Private File System) быстрее, но требует `SharedArr
**Почему:**
`ref` глубоко отслеживал бы каждое вложенное свойство потенциально тысяч объектов транзакций/кошельков/категорий. `shallowRef` отслеживает только ссылку верхнего уровня. Явный паттерн «создать новый объект» при записи - осознанный компромисс: чуть более многословные сторы, значительно меньшие накладные расходы реактивности.
-## Клиентские UUID (без префикса `local_`, без ремапинга)
+## Клиентские UUID (без ремапинга)
-Каждая новая сущность получает UUID, сгенерированный на клиенте (`crypto.randomUUID()` или аналог) до локальной записи. Этот UUID является постоянным ID - нет временного префикса `local_` и нет ремапинга после подтверждения от сервера.
+Каждая новая сущность получает UUID, сгенерированный на клиенте (`crypto.randomUUID()` или аналог) до локальной записи. Этот UUID является постоянным ID - клиент владеет им весь офлайн-цикл, и он никогда не переназначается.
-**Почему не `local_` ID:**
-В прошлом использовался временный префикс `local_abc123`, который потом переназначался на серверный ID после успешной мутации. Это требовало отслеживания ожидающих ремапов ID во всех сторах и каскадных обновлений (например, транзакции, ссылающиеся на новый кошелёк). С PowerSync клиент владеет ID навсегда: схема Supabase использует `text` PK с `default gen_random_uuid()::text`, поэтому любой UUID, сгенерированный клиентом, принимается как есть. Нет ремапинга, нет каскадной сложности.
+**Почему:**
+PowerSync ставит запись в очередь локально и загружает её позже, поэтому ID должен быть стабильным ещё до того, как строку увидит сервер. Схема Supabase использует `text` PK с `default gen_random_uuid()::text`, поэтому любой UUID, сгенерированный клиентом, принимается как есть. Нет обращения к серверу за выдачей ID, нет ремапинга, нет каскадных обновлений строк, ссылающихся на новую сущность.
**Почему нет FK-ограничений в Postgres:**
Порядок загрузки PowerSync не гарантирован. Транзакция, ссылающаяся на кошелёк, может быть загружена раньше самого кошелька. FK-ограничения отклонили бы валидные данные. Ссылочная целостность обеспечивается логикой приложения.