sxchnge/docs/implementation.md

Product implementation record

Reusable UX guidance — task #10

Task #10, branch skills-10, delivered in PR #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.
2. auth-4 into theme-1: shared auth and verification package. Related tasks: #4, #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, #3, #5, #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	theme-1 → main	d931805
2	#8: Shared auth and verification	auth-4 → theme-1	27424ed
3	#9: Localized app and routing	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 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 records event semantics, metrics, privacy constraints, windows, validation and limitations.

Delivery: PR #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 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, branch editor-14.

Root README refresh

Task #18, delivered in PR #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, 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, 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, unmerged. Merge #21 first and retarget #23 to main.

UX simplicity preference

Task #26, delivered in PR #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, 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 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.