docs: architecture, guidelines, domain designs, progressive code index

docs/domains/platform.md

@@ -0,0 +1,39 @@
+# Domain: Accounts, Content, Shops, Identity
+
+## Customer accounts (`modules/account/`)
+
+Three buckets per customer: `available` and `frozen` (monetary, per currency)
+plus `points` (no currency). Balances change only through
+`credit`/`debit`/`freeze`/`release`, each appending one immutable
+`customer_account_entries` row in the same transaction as the business write.
+The ledger is the audit trail; balances are never set absolutely. Credits in
+a currency the customer never held lazily create the zero row
+(`ensure_monetary_account`).
+
+Planned on this foundation: wallet top-up/withdrawal and merchant settlement
+(`openspec/changes/add-wallet-settlement`).
+
+## Storefront content (`modules/content/`)
+
+Four ordered home-content kinds (banners, promos, quick links, floor
+adverts), platform-managed by whole-list replacement (`PUT
+/admin/content/{kind}` reindexes positions atomically). Quick-link glyphs are
+inline SVG path data.
+
+## Shops (`modules/shop/`)
+
+Platform creates/suspends shops; shop profiles are a side table with
+bilingual address/notice/after-sale and platform-owned scores. Merchants edit
+their own profile via `PUT /api/shop/profile` — scores are platform-only and
+the merchant upsert never touches them.
+
+## Identity (`modules/identity/`, `src/auth.rs`)
+
+Email+password register/login, JWT bearer tokens. `AuthUser` carries
+`id/role/shop_id`; `require(&[roles])` for RBAC, `own_shop()` /
+`require_shop()` for tenant scoping (cross-shop resources return 404).
+`ensure_accounts` runs inside the registration transaction.
+
+## Key files
+
+See `docs/code_index/platform.md`.