# Product implementation record

## Reusable UX guidance — task #10

[Task #10](https://git.sendico.io/tech/sxchnge/issues/10), branch `skills-10`,
delivered in [PR #11](https://git.sendico.io/tech/sxchnge/pulls/11) into `main`,
adds a concise root UX policy linking two independent skills in `skills/`:
UX Design covers usable interfaces and its design review; UX Observability covers
purposeful journey measurement and its observability review. Both preserve product
conventions and avoid prescribing frameworks, vendors, or visual styles.

Validation: both skills passed `quick_validate.py` from the skill-creator skill;
root skill links resolve, scaffold checks and `git diff --check` pass. Manual
review checked the requested principles and checklist coverage, duplication,
contradictions, and actionable wording. The initial validator attempt lacked
PyYAML; rerunning in a temporary virtual environment with PyYAML passed.

This is documentation-only guidance, not an implementation or verification of
product usability or journey instrumentation. Runtime tests and security scans
were not run. No application behavior or analytics events changed.

## Scope

The public Astro website now lives in `website/`, preserving its source, assets,
brand references and hosting identity. `backend/` describes the proposed BFF
boundary; no backend service is implemented.

The frontend includes:

- `sxchnge_theme`: reusable Flutter theme, Onest font/license, light/dark themes,
  and a consumer example. UI uses ColorScheme and TextTheme roles.
- `sxchnge_auth`: shared login, signup, and email-verification contracts,
  models, providers, and deterministic dummy services, reusable on mobile.
- `app`: responsive login/signup, EN/RU localization and saved locale,
  email-sent and verified screens, expired/invalid/internal-error outcomes,
  resend/retry, and centralized go_router navigation.

## Review boundaries and task mapping

The accumulated work was initially left uncommitted across task branches.
Delivery groups the actual final code into three stacked contributions, without
claiming that the earlier intermediate implementations were committed:

1. `theme-1` into `main`: website relocation, repository scaffolding and theme.
   Related task: [#1](https://git.sendico.io/tech/sxchnge/issues/1).
2. `auth-4` into `theme-1`: shared auth and verification package.
   Related tasks: [#4](https://git.sendico.io/tech/sxchnge/issues/4),
   [#5](https://git.sendico.io/tech/sxchnge/issues/5).
3. `routing-6` into `auth-4`: integrated application, root test entry point,
   self-contained frontend guidelines/workflow skills and this delivery record.
   Related tasks: [#2](https://git.sendico.io/tech/sxchnge/issues/2),
   [#3](https://git.sendico.io/tech/sxchnge/issues/3),
   [#5](https://git.sendico.io/tech/sxchnge/issues/5),
   [#6](https://git.sendico.io/tech/sxchnge/issues/6).

Review and merge in that order. Preserve commit ancestry with merge commits,
then retarget the next PR to `main` after its dependency merges. With squash
merges, rebase the remaining stack before merging. PR links are recorded below
once created. Earlier empty task branches are retained for traceability.

## Validation

The frontend suite covers 56 tests: 20 shared auth, 3 theme, 3 theme consumer,
and 30 app tests. Coverage includes validation, localized layouts at 200% text
scale, provider lifecycle/race handling, signup through email confirmation,
resend/retry, token changes, transient history extras and URL route updates.

Commands used for delivery:

- Root: `make test-frontend`.
- Flutter packages: formatting checks and `flutter analyze`.
- App: `flutter build web --no-wasm-dry-run`.
- Website: `npm run test`, `npm run check`, `npm run build`.

The localhost preview was manually checked for confirmation deep-link reload,
return to login, and browser back/forward. Tests and builds are local validation;
no remote CI outcome is implied. Build outputs and dependency caches are ignored.

## Current limitations

Authentication and verification are explicitly simulated. No real account,
session, email delivery, backend token validation or KYC access guard exists.
The three app routes are public; backend authorization remains future work.
`demo-valid`, `demo-expired` and `demo-internal` are preview-only confirmation
values. Other/missing tokens display invalid confirmation. Signup email is
transient and excluded from serialized browser history. Only locale preference
is persisted by the application.

The website and Flutter app are separate applications. The Flutter app currently
has a web runner; the shared packages can be consumed by a future mobile app.

## Published PRs

| Order | PR | Branch → base | Implementation commit |
| --- | --- | --- | --- |
| 1 | [#7: Product layout and theme](https://git.sendico.io/tech/sxchnge/pulls/7) | `theme-1` → `main` | `d931805` |
| 2 | [#8: Shared auth and verification](https://git.sendico.io/tech/sxchnge/pulls/8) | `auth-4` → `theme-1` | `27424ed` |
| 3 | [#9: Localized app and routing](https://git.sendico.io/tech/sxchnge/pulls/9) | `routing-6` → `auth-4` | `10a278c` |

All three implementation commits are pushed. PRs are open, assigned to `tech`,
labeled `frontend`, and associated with the SXCHNGE project. Follow-up documentation
commits are included in PR #9. Task references point to the delivering branches;
older empty branches are historical only. No PR has been merged during delivery.

Delivery validation passed: 56 frontend tests; formatting and all four Flutter
analyses; 3 website tests, Astro check (zero errors/warnings), and website build.
The app web build and browser checks passed during the immediately preceding
routing task; delivery changed documentation and Git organization only.

## Onboarding UX fixes and analytics preparation

Task [#12](https://git.sendico.io/tech/sxchnge/issues/12) corrects the four UX
review findings: measurable submitted journeys, accurate sent recipient state,
primary retry on confirmation errors, and prominent/truthful simulated outcomes.
The new shared `sxchnge_analytics` package supplies typed events, a bounded dummy
sink and a journey recorder; auth service decorators keep collection independent
of widgets. A PostHog adapter can replace the sink later; no actual SDK or data
transmission is included. The [journey contract](ux/auth-journeys.md) records event
semantics, metrics, privacy constraints, windows, validation and limitations.

Delivery: [PR #13](https://git.sendico.io/tech/sxchnge/pulls/13), `onboarding-12`.
Implementation commit `f1cbf64`; 68 tests and affected-package analysis/formatting
plus web build passed. Final browser verification confirms accessible recipient
text and keyboard recovery. No merge or actual PostHog collection was performed.

## Editor configuration cleanup

Task [#14](https://git.sendico.io/tech/sxchnge/issues/14) removes the root VS Code
extension recommendations and launch configuration. Root `.vscode/` is ignored
so personal editor configuration stays local. Development uses the CLI commands
in the README. Validation: no tracked root `.vscode` files, ignore rule verified,
and diff whitespace check passed. Runtime tests are unnecessary for this change.

Delivery: [PR #15](https://git.sendico.io/tech/sxchnge/pulls/15), branch `editor-14`.

## Root README refresh

Task [#18](https://git.sendico.io/tech/sxchnge/issues/18), delivered in
[PR #19](https://git.sendico.io/tech/sxchnge/pulls/19) on `docs-18`, documents
current packages, app/website commands, verification previews, analytics limits,
skill location and contribution workflow. Local links and diff checks pass;
commands and prerequisites were checked against repository configuration.
Documentation only; no runtime tests were run.

## Optional identity verification and backend-owned limits — task #20

- Branch: `kyc-20`, based on `61ccfc1` (main after README PR #19).
- Planned the UX before implementation in [docs/ux/kyc.md](ux/kyc.md), including
  optional basic access, two-photo preparation/review, pending and decision states,
  errors, recovery, privacy and measurement definitions.
- Added the mobile-reusable `sxchnge_kyc` package, injectable identity/photo/limits
  services, transport mappers and providers. Followed Sendico's visible-limits
  ownership boundary; current tier/caps/remaining amounts come from a service.
- Added themed EN/RU `/identity` screens, login/email-confirmation entry points,
  route exit guards, review/replace/discard controls, safe error messages and
  demo-only backoffice decision controls. No real documents are transmitted.
- Reviewed full frontend scope and corrected web image-metadata validation,
  stale-state messaging, cancelled-picker analytics, step focus/scroll behavior,
  duplicate submissions and sensitive image cache cleanup.
- Validation: format check for all 27 changed/new Dart files; analyzer passes for
  app, sxchnge_kyc and sxchnge_analytics; `make test-frontend` passes **86 tests**
  (10 KYC, 7 analytics, 20 auth, 3 theme, 3 consumer example, 43 app). Web build
  passes. Actual browser selection of generated PNG samples reached pending
  review with unchanged basic limits. EN/RU, 320px/1.6 text scale, accessibility
  labels/tap targets, route guards and all decision paths have widget coverage.
- Limits are illustrative backend-stub fixtures. Real authenticated uploads,
  private storage, staff review, support, authoritative limits enforcement and
  server-side review analytics remain integration work. Native mobile and
  VoiceOver/TalkBack checks remain release QA. Security scans were not requested.
- Delivery: [PR #21](https://git.sendico.io/tech/sxchnge/pulls/21), pushed on `kyc-20`; not merged. Final browser review also preserved heading semantics when moving keyboard focus.