Preserve explicit model and provider architecture (#30)

README.md

@@ -160,6 +160,16 @@ Before backend integration, agree on the customer, KYC, eligibility/limits and
 customer-scoped payment contracts for one complete transaction flow. These are
 intended boundaries, not claims that the required operations already exist.
 
+## Client architecture
+
+Keep **DTO → mapper → service → data model → provider → UI** boundaries in every
+feature and shared package. Services return mapped domain models; providers sit
+on services and expose loading/error/data state. Widgets render models and call
+provider actions. DTO serialization and backend calls belong below this boundary.
+Shared packages own reusable domain logic for web and mobile; stub replacements
+must preserve the same contracts. See the standing rules in `AGENTS.md` and
+`frontend/AGENTS.md`.
+
 ## Contribution workflow
 
 Follow [`AGENTS.md`](AGENTS.md) and the applicable scoped guidelines, including