281 lines
17 KiB
Markdown
281 lines
17 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, now consolidated under `.agents/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.
|
|
|
|
## Consolidated skill location
|
|
|
|
Task [#16](https://git.sendico.io/tech/sxchnge/issues/16) consolidates all four
|
|
repository skills under `.agents/skills/`. UX Design and UX Observability moved
|
|
without content changes; root policy links and this record now use that location.
|
|
The old root `skills/` directory is removed. Validation compares moved content
|
|
byte-for-byte, checks all four skill paths and updated UX links, and runs
|
|
`git diff --check`. No runtime tests are needed for this move.
|
|
|
|
Delivery: [PR #17](https://git.sendico.io/tech/sxchnge/pulls/17), branch `skills-16`.
|
|
## 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.
|
|
|
|
## Exchange workspace UX plan — task #24
|
|
|
|
- Plan-only scope confirmed by the user; no application code changed.
|
|
- [Exchange workspace plan](ux/exchange-workspace.md) defines accounts, top-up,
|
|
exchange, payout, Activity, Limits and Settings; account-owned language replaces
|
|
repeated page selectors in the proposed interface.
|
|
- Includes authoritative quotes/status/limits, idempotent recovery, account-profile
|
|
language persistence, accessible/responsive behavior and semantic funnel metrics.
|
|
- Standalone documentation branch `exchange-shell-24` from main. Future interface
|
|
implementation should incorporate KYC PR #21 and usage PR #23.
|
|
- Validation: documentation links and diff checks; no runtime changes or tests.
|
|
- Delivery: [PR #25](https://git.sendico.io/tech/sxchnge/pulls/25), committed and pushed; not merged.
|
|
## 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.
|
|
|
|
## UX simplicity preference
|
|
|
|
Task [#26](https://git.sendico.io/tech/sxchnge/issues/26), delivered in
|
|
[PR #27](https://git.sendico.io/tech/sxchnge/pulls/27) on `skills-26`, makes
|
|
simplicity an explicit preference in the UX Design skill and its review checklist.
|
|
Prefer fewer concepts, choices, and controls when they serve the same need; retain
|
|
essential information, accessibility, and recovery. Documentation only.
|
|
Validation: skill-creator `quick_validate.py` passed in an isolated environment
|
|
with PyYAML (the system Python lacked it); `git diff --check` passed. No runtime
|
|
tests were needed. The PR is not merged.
|
|
|
|
## Exchange workspace — task #28
|
|
|
|
- Branch `workspace-28`, stacked on `limits-22` / PR #23. Merge KYC #21 first,
|
|
then limits #23, then retarget this workspace contribution to main. The approved
|
|
plan from #24/#25 is included and updated for the user's available-only direction.
|
|
- Implemented Accounts, Activity/detail, Limits and Settings in a responsive
|
|
go_router shell, with top-up, exchange and payout input/review/status flows.
|
|
One action group follows the selected currency; all colors use theme roles.
|
|
Only available balances are displayed. Status explains credit timing, outgoing
|
|
amount plus fee, completion and full return after failure.
|
|
- Shared `sxchnge_wallet` service/providers own coherent demo balances, quotes,
|
|
idempotent submissions, reconciliation, history, account language and live
|
|
snapshot refresh. The limits adapter reuses the KYC DTO/mapper and refreshes
|
|
usage when operations change. Widgets consume provider models.
|
|
- Language is in account settings, with failed-save feedback and retry. Public
|
|
auth and verified-email screens enter the workspace. KYC remains optional;
|
|
the demo service enforces its basic/verified outgoing caps at submission.
|
|
- UX review: EN/RU at 320px with 1.6 text scaling; available-only presentation;
|
|
field preservation after errors; explicit draft discard; quote expiry;
|
|
loading/stale/empty states; operation outcome explanations; accessible labels,
|
|
semantic status announcements and focus after quote/errors. Browser walkthrough
|
|
verifies quote amounts and service-confirmed credit with the exchange handoff.
|
|
Native mobile and dedicated VoiceOver/TalkBack testing remain release QA.
|
|
- Measurement review: typed draft/quote/submission/settlement steps with scoped
|
|
journey IDs, safe failure enums, simulated flag and deduplicated terminal
|
|
outcomes. No financial amounts, recipients or account IDs in events. Pending
|
|
app closure is not draft abandonment. Real PostHog delivery and cross-session
|
|
server outcomes remain integration work.
|
|
- Validation passed: `make test-frontend` (115 tests), `flutter analyze` in app,
|
|
sxchnge_wallet, sxchnge_analytics and sxchnge_kyc; format check of all 36 changed
|
|
Dart files; `flutter build web`; `git diff --check`. Review fixes included
|
|
narrow Russian layouts, limit-provider typing, automatic pending refresh,
|
|
single-use quotes and ambiguous-response recovery. No security scan requested.
|
|
- Demo limits: opening EUR 75, fixed rates/fees and three currencies, no real
|
|
payment methods/bank validation/storage/auth enforcement. Account preferences,
|
|
history and balances reset on reload. No receipt export, date pagination,
|
|
notification preferences or security settings beyond an honest capability note.
|
|
Backend adapters must supply these before production use; see the wallet README.
|
|
- Delivery: [PR #29](https://git.sendico.io/tech/sxchnge/pulls/29), pushed and
|
|
unmerged. Task and PR have frontend label, tech owner and SXCHNGE project.
|
|
Browser demo walkthrough also completed exchange and payout, confirming source
|
|
currency handoffs and exact fee/debit/receipt values on the result screen.
|
|
|
|
### Workspace copy cleanup — follow-up to #28
|
|
|
|
At the user's request, removed repeated demo/preview banners from the workspace,
|
|
transaction forms, auth, email confirmation, identity and limits. Confirmation
|
|
and result copy now uses ordinary product wording in EN/RU; the mobile wordmark
|
|
remains without the extra note. Removed unused localization entries and duplicate
|
|
email-state copy. Existing journey measurement, simulation flags, service behavior,
|
|
funds explanations and recovery controls are unchanged. Development constraints
|
|
belong in this record and package README, not repeated throughout the product UI.
|
|
|
|
Delivery continues in [PR #29](https://git.sendico.io/tech/sxchnge/pulls/29) on
|
|
`workspace-28`. This copy change does not connect real authentication, email,
|
|
payment, support or backoffice services.
|
|
Validation: all 115 frontend tests, app analysis, app Dart formatting, web build
|
|
and diff checks pass. Updated existing copy expectations; telemetry tests still
|
|
verify simulated events never count as real business success. No new click events
|
|
were needed for this presentation-only cleanup.
|