187 lines
11 KiB
Markdown
187 lines
11 KiB
Markdown
# 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.
|
|
|
|
## Limits usage display — task #22
|
|
|
|
- Branch `limits-22`, stacked on `kyc-20` / PR #21 (merge #21 first).
|
|
- Added explicit used/committed and reserved fields through DTO, mapper, service
|
|
and model. Remaining is independently supplied by the backend stand-in.
|
|
- Daily/monthly cards show used, reserved, available, cap and upgrade amounts,
|
|
with a labeled theme-based occupied-capacity indicator and exhausted text.
|
|
Dummy fixtures contain nonzero activity; usage survives tier increases.
|
|
- UX review: EN/RU labels explain pending holds, no color-only information,
|
|
320px/1.6-scale widget checks, actual browser visual verification, zero and
|
|
over-cap ratio handling. Existing KYC telemetry is sufficient; no usage amounts
|
|
are sent to analytics.
|
|
- Validation passed: all 91 frontend tests, analyze app and sxchnge_kyc,
|
|
format check of all 9 affected Dart files, web build and diff checks.
|
|
- Delivery: [PR #23](https://git.sendico.io/tech/sxchnge/pulls/23), unmerged. Merge #21 first and retarget #23 to main.
|