docs: capture refactor workflow and project memory

2026-08-29 09:57:58 +03:30
parent 8bff15a0ad
commit 8e634d5739
10 changed files with 380 additions and 0 deletions
@@ -0,0 +1,45 @@
+# Product flows confirmed from staging screenshots
+
+## Wallet and balances
+
+- Portfolio shows total value, available value, locked value, per-asset balance/value/price, and allowed actions.
+- “Locked” is a first-class user-visible balance. GL must expose at least `available`, `locked`, and `total = available + locked` per user/asset, with the lock reason and owning operation.
+- History exposes asset, time, amount, transaction type, state, tracking number, and Kuknos/hash-like reference.
+
+## Transaction gate
+
+Every value-changing request can require configurable 2FA (`SMS`, `TOTP`, or `EMAIL`) and an agreement acceptance. An agreement may be:
+
+- a generated legal contract;
+- transaction-specific terms and conditions; or
+- acceptance of site/platform policy.
+
+The accepted agreement version, content hash, actor, transaction/request ID, timestamp, and 2FA method/result must be immutable audit evidence.
+
+## Trade and ICO
+
+- Secondary market: maker posts an order; taker accepts all or part of its remaining quantity. Contract acceptance precedes settlement.
+- ICO: taker buys only from a specific authorized publisher maker order. Asset/user whitelisting may reject the request before agreement/settlement.
+- Reserved quantities and balances must be locked atomically when an order/request becomes executable, then consumed or released exactly once.
+
+## Money movement
+
+- Kuknos subscription imports observed blockchain transactions/deposits.
+- External bank deposit causes IRT issuance/transfer from the server treasury to the user.
+- IPG flow: create gateway token -> redirect -> confirm callback -> transfer IRT from treasury.
+- IRT withdrawal: create request -> freeze IRT -> 2FA/agreement if required -> admin approve/deny -> finalize state and consume/release lock.
+- Authorized third party: API-token request -> manual/user/admin decision -> lock asset as collateral -> success, denied, or failed result; later release/consume must reference the original lock. Automatic acceptance policy is explicitly a future feature.
+
+## Platform availability rule
+
+- GL is the primary, append-only source of truth and is mandatory for every value-changing workflow.
+- Kuknos is the secondary settlement/verification source of truth. `NORMAL` mode requires both GL and Kuknos.
+- GL/GL-database failure puts transaction admission and transaction workers into a fail-closed halt until health is restored.
+- Kuknos failure also halts transactions unless an authorized operator explicitly selects `KUKNOS_DISABLED` using AdminPanel or configuration. There is no automatic switch.
+- Public health must expose the incident as critical/not-ready, and transitions into, during, and out of the incident must be observable through OpenTelemetry.
+- Non-mutating views can remain available if their data can be labelled consistently and safely.
+
+## Bank and referral
+
+- Bank information maintains verified Sheba/IBAN accounts; the account must belong to the identified user before withdrawal.
+- Referral tracks invitation code/link, referred users, commission share, received/withdrawable reward, and reward withdrawal.