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.