82 lines
5.5 KiB
Markdown
82 lines
5.5 KiB
Markdown
# SXCHNGE consumer app
|
|
|
|
Flutter web application using the local `sxchnge_theme` package.
|
|
|
|
## Run
|
|
|
|
From this directory:
|
|
|
|
```sh
|
|
flutter pub get
|
|
flutter run -d chrome
|
|
```
|
|
|
|
## Current scope
|
|
|
|
A responsive login/sign-up preview with a themed brand panel, email and password validation, password visibility controls, keyboard submission, and inline feedback. Sign-up additionally asks for a name and matching password confirmation. The 12-character sign-up minimum is a UI preview policy and must be aligned with the backend when authentication is integrated.
|
|
|
|
Without backend configuration the app uses dummy services. The existing
|
|
`SXCHNGE_API_URL` and `SXCHNGE_CLIENT_ID` select authenticated backend auth,
|
|
identity, limits and wallet adapters. Wallet operations use Sendico through the
|
|
BFF after the provider prerequisites and dedicated customer resource bindings
|
|
are provisioned; they do not use demo balances in backend mode. LoginProvider,
|
|
SignupProvider and shared wallet providers own loading/results/errors.
|
|
SxchngeApp retains explicit service injection for tests and previews. See
|
|
[quotation/payment integration](../../docs/payments.md) for setup, supported
|
|
funding/destinations, authorization, reconciliation and rollout.
|
|
|
|
The interface uses `ColorScheme` and `TextTheme` roles from `sxchnge_theme`; the desktop brand panel installs the package's dark theme locally. Entrance animation respects reduced-motion preferences. The public website remains separate in `website/`.
|
|
|
|
## Validate
|
|
|
|
```sh
|
|
dart format --output=none --set-exit-if-changed lib test
|
|
flutter analyze
|
|
flutter test
|
|
flutter build web
|
|
```
|
|
|
|
From the repository root, `make test-frontend` runs both theme suites and the application tests. Tracker: tech/sxchnge#2, branch `auth-2`.
|
|
|
|
## English and Russian
|
|
|
|
Localization follows Sendico's Flutter pattern: `lib/l10n/en.arb` is the template, `ru.arb` contains Russian translations, and `flutter gen-l10n` writes `lib/generated/i18n/`. Generated Dart files are ignored and untracked. Run `flutter gen-l10n` after a clean checkout and after editing ARB files; `make test-frontend` runs it before tests. Edit ARB files, not generated Dart files. Flutter's Material and Cupertino localizations are included through the generated delegates.
|
|
|
|
The language dropdown is available in both authentication modes. Startup reads `sxchnge_last_locale` using shared preferences; without a saved choice it uses the device language. Russian regional variants resolve to Russian and unsupported languages fall back to English. Preference writes are serialized, and storage failures leave the selected language usable for the current session with a localized notice. Only the language preference is stored; credentials remain transient.
|
|
|
|
Language switching preserves mode and input, translates existing validation errors, and updates the application title. Tracker: tech/sxchnge#3, branch `localization-3`.
|
|
|
|
## Email verification
|
|
|
|
Successful signup opens `/verification-sent` and requests a verification email through the injected `VerificationService`. The screen shows sending, sent and resend errors. Reloading this route asks for the email again; the app does not persist it. A production signup endpoint should avoid sending a duplicate email if this separate send operation is retained.
|
|
|
|
Confirmation links use `/#/verify-email?token=…`. They display checking, verified, expired, invalid (including missing tokens), or internal error. Internal confirmation errors allow retry; invalid and expired links allow requesting a new email. The backend must validate tokens and enforce verification before enabling restricted operations.
|
|
|
|
The default service is a **dummy**: no email is sent or account verified. Preview tokens:
|
|
|
|
- `demo-valid`: verified
|
|
- `demo-expired`: expired
|
|
- `demo-internal`: internal error
|
|
- Any other token or missing token: invalid
|
|
|
|
The sent screen includes a clearly labeled demo confirmation link. All states and actions support EN/RU and theme colors. Tracker: tech/sxchnge#5, branch `verification-5`.
|
|
|
|
## Routing
|
|
|
|
`lib/routing/router.dart` owns the `go_router` route table, with route names in `routes.dart`. `SxchngeApp` creates one router for its lifetime, supplies it to `MaterialApp.router`, and disposes it on teardown. Locale changes preserve the router and current page state.
|
|
|
|
Use `context.goNamed(AppRoutes.… )` for top-level navigation. Existing hash URLs remain compatible: `/`, `/#/verification-sent`, and `/#/verify-email?token=…`. Confirmation query changes re-run verification and discard stale async results. Unknown routes redirect to `/`.
|
|
|
|
The signup email travels as a transient route extra. The router's extra codec deliberately omits extras from serialized browser history, so a restored sent page asks for the email again. Do not add persistent route extras without explicitly updating that policy.
|
|
|
|
These are public routes: no session or KYC guard is added to the dummy authentication flow. Future protected pages should use centralized redirects driven by authoritative session state, with backend access enforcement. Tracker: tech/sxchnge#6, branch `routing-6`.
|
|
|
|
## UX and analytics
|
|
|
|
The app accepts an optional `analyticsService` and defaults to the shared bounded
|
|
in-memory dummy analytics sink. Semantic service events correlate signup, delivery
|
|
and confirmation within this app instance. No analytics data leaves the device.
|
|
See [the journey contract](../../docs/ux/auth-journeys.md) for the schema, metrics,
|
|
PostHog adapter boundary and measurement limitations. Demo outcomes are explicitly
|
|
simulated; recipient editing and internal-error recovery have dedicated controls.
|