diff --git a/.agents/skills/ux-design/SKILL.md b/.agents/skills/ux-design/SKILL.md index 9a72d17..1645605 100644 --- a/.agents/skills/ux-design/SKILL.md +++ b/.agents/skills/ux-design/SKILL.md @@ -10,6 +10,10 @@ before reporting it complete. Rendering correctly is only one part of completion ## Establish the flow +- Prefer the simplest interface that lets users complete their task confidently. + When options meet the same need, choose fewer concepts, choices, and controls. + Add complexity only for a concrete user need; preserve essential information, + accessibility, and recovery rather than hiding them to make a screen look minimal. - Identify the user's primary task, successful outcome, and shortest appropriate path to that outcome before choosing layouts or controls. - Inspect comparable product flows, components, navigation, terminology, and @@ -95,6 +99,8 @@ performed and any gaps; do not mark applicable unmet criteria as complete. - [ ] Are interactive elements recognizable, and can the user tell what is happening and what will happen next? - [ ] Are steps appropriate, with unnecessary interaction and cognitive load removed? +- [ ] Is this the simplest usable solution, with each added concept, choice, or + control serving a concrete user need? - [ ] Does the flow follow existing product patterns and consistent terminology, with a concrete reason for any departure? - [ ] Can users recover from errors, with input and context preserved where appropriate? diff --git a/.gitignore b/.gitignore index 16d54bb..7030e4f 100644 --- a/.gitignore +++ b/.gitignore @@ -22,3 +22,6 @@ pnpm-debug.log* # jetbrains setting folder .idea/ + +# Local editor configuration +/.vscode/ diff --git a/.vscode/extensions.json b/.vscode/extensions.json deleted file mode 100644 index 22a1505..0000000 --- a/.vscode/extensions.json +++ /dev/null @@ -1,4 +0,0 @@ -{ - "recommendations": ["astro-build.astro-vscode"], - "unwantedRecommendations": [] -} diff --git a/.vscode/launch.json b/.vscode/launch.json deleted file mode 100644 index 61ac24d..0000000 --- a/.vscode/launch.json +++ /dev/null @@ -1,12 +0,0 @@ -{ - "version": "0.2.0", - "configurations": [ - { - "command": "npm run dev -- --background", - "cwd": "${workspaceFolder}/website", - "name": "Development server", - "request": "launch", - "type": "node-terminal" - } - ] -} diff --git a/README.md b/README.md index 10d61e4..398e9c5 100644 --- a/README.md +++ b/README.md @@ -1,43 +1,171 @@ # SXCHNGE -Product repository for the sxchnge public website, consumer frontend, and backend for frontend (BFF). +Product repository for the sxchnge public website, Flutter consumer app, reusable +packages, and planned backend for frontend (BFF). + +## Current state + +The consumer app includes responsive login/signup, English and Russian +localization, email verification and recovery screens, and URL-based navigation +with `go_router`. Its interface uses the shared theme's colors and typography. + +**Authentication, email verification and analytics use dummy services.** No real +account or session is created, no email is delivered, and no analytics data is +transmitted. The backend is documentation only. Session/KYC access guards and +Sendico integration are not implemented. ## Repository structure -| Folder | Purpose | Status | -| --- | --- | --- | -| [`website/`](website/README.md) | Existing Astro public website, assets, brand references, and Sites configuration | Implemented | -| [`frontend/`](frontend/README.md) | Consumer application and Flutter packages | Theme, shared auth, localized app, verification and routing implemented | -| [`backend/`](backend/README.md) | Product BFF integrating with Sendico | Prepared for implementation | +| Location | Purpose | +| --- | --- | +| [`website/`](website/README.md) | Astro public website, assets, brand references and hosting configuration | +| [`frontend/app/`](frontend/app/README.md) | Flutter consumer app with a web runner | +| [`sxchnge_theme`](frontend/packages/sxchnge_theme/README.md) | Reusable light/dark themes and bundled Onest font | +| [`sxchnge_auth`](frontend/packages/sxchnge_auth/README.md) | Shared login/signup/verification contracts, providers and dummy services | +| [`sxchnge_analytics`](frontend/packages/sxchnge_analytics/README.md) | Typed journey events, recorder and bounded in-memory dummy analytics | +| [`backend/`](backend/README.md) | Planned BFF and Sendico integration boundaries | +| [`.agents/skills/`](.agents/skills) | Repository agent skills | +| [`docs/`](docs/implementation.md) | Implementation records and UX measurement contracts | -Each application owns its dependencies and deployment configuration. The frontend includes the reusable `sxchnge_theme` Flutter package; the backend currently contains documentation only. +Each application owns its dependencies and build configuration. Shared Dart and +Flutter packages can be reused by a future mobile app; mobile runners are not +currently included. Local `.vscode/` configuration is ignored. -## Website development +## Run the consumer app -Run the existing website commands from its new folder: +Requires Flutter **3.47.0 or later** with Dart **3.13.0 or later** (below Dart 4), matching +the application's package constraints, and Chrome for this run command. + +```sh +cd frontend/app +flutter pub get +flutter gen-l10n +flutter run -d chrome +``` + +Build the web app from the same directory: + +```sh +flutter build web --no-wasm-dry-run +``` + +Output is `frontend/app/build/web/`. To inspect that build locally, from the +repository root: + +```sh +python3 -m http.server 5123 --bind 127.0.0.1 --directory frontend/app/build/web +``` + +Open [the local app](http://127.0.0.1:5123/). The language selector supports EN/RU +and saves the language preference. Edit translations in `frontend/app/lib/l10n/` +and regenerate with `flutter gen-l10n`; do not edit generated translations. + +## Preview email verification + +Signup leads to the simulated email-sent screen. Its demo confirmation button +previews completion. Direct confirmation URLs use hash routing: + +| URL suffix | Preview outcome | +| --- | --- | +| `/#/verification-sent` | Request an email; a direct visit asks for the address | +| `/#/verify-email?token=demo-valid` | Simulated verification complete | +| `/#/verify-email?token=demo-expired` | Expired link with recovery | +| `/#/verify-email?token=demo-internal` | Internal error with primary retry | +| `/#/verify-email` or an unknown token | Invalid confirmation | + +Signup email stays transient and is excluded from serialized browser history. +The sent recipient is read-only until **Change email** is selected. All current +routes are public; these previews do not establish authentication or authorization. + +## Analytics and PostHog preparation + +The app accepts an injectable `AnalyticsService` and defaults to +`DummyAnalyticsService`. It keeps up to 500 semantic events in memory and never +captures form contents, confirmation tokens or raw errors. Events cover submitted +auth journeys, service outcomes, retries and known abandonment; simulated outcomes +are distinguished from real conversion. + +A future PostHog adapter can replace the sink. No PostHog SDK or credentials are +configured. Read the [auth journey contract](docs/ux/auth-journeys.md) for event +properties, attempt and timing rules, metric definitions, privacy requirements, +and cross-device/termination measurement limitations. + +## Run the public website + +Requires Node.js **22.12.0 or later** and npm, matching `website/package.json`. +From the repository root: ```sh cd website npm ci npm run dev -- --background --host 127.0.0.1 +``` + +Manage the background server from `website/`: + +```sh +npm exec astro dev status +npm exec astro dev logs +npm exec astro dev stop +``` + +Website builds go to `website/dist/`. Use `website/` as the working directory +for hosting tools; the existing hosting identity lives in +`website/.openai/hosting.json`. The website and consumer app are separate builds. + +## Validate changes + +From the repository root, run all shared-package and app tests: + +```sh +make test-frontend +``` + +From each changed Flutter package, run formatting and analysis. For example: + +```sh +cd frontend/app +dart format --output=none --set-exit-if-changed lib test +flutter analyze +``` + +Validate the website independently: + +```sh +cd website npm run test npm run check npm run build ``` -From `website/`, manage the background server with `npm exec astro dev status`, `npm exec astro dev logs`, and `npm exec astro dev stop`. Build output is `website/dist/`. Use `website/` as the working directory for website hosting tools; its existing Sites identity is preserved in `website/.openai/hosting.json`. +Rendering and passing tests do not alone establish UX completion. Review +usability, accessibility and journey measurement under the repository's UX rules. ## Product boundaries -The intended integration is: consumer frontend → sxchnge BFF → supported Sendico API. +The intended integration is: **consumer app → sxchnge BFF → supported Sendico API**. -- sxchnge owns consumer registration and sessions, the onboarding and exchange experience, and mapping authenticated consumers to stable organization-scoped Sendico customer references. -- Sendico remains authoritative for payment execution, KYC records and verification, policy decisions, and limit enforcement. -- The sxchnge organization, backend integration principal, and individual customer references are distinct identities. Consumers must not share the integration account's customer identity. -- The BFF should use a supported API contract rather than copying Sendico's existing BFF or depending on its local internal modules. +- sxchnge will own consumer registration/sessions, onboarding and exchange UX, + and mappings to stable, organization-scoped Sendico customer references. +- Sendico remains authoritative for payment execution, KYC records and + verification, policy decisions and limit enforcement. +- The sxchnge organization, backend integration principal and individual customer + references are distinct identities. Consumers must not share the integration + account's customer identity. +- The BFF should use a supported API contract rather than copying Sendico's BFF + or depending on its local internal modules. Integration credentials belong in + the backend. -Before implementing the product, define one complete transaction flow and agree on the Sendico customer, KYC, eligibility/limits, and customer-scoped payment contracts. These are intended boundaries, not claims that the required Sendico operations already exist. +Before backend integration, agree on the customer, KYC, eligibility/limits and +customer-scoped payment contracts for one complete transaction flow. These are +intended boundaries, not claims that the required operations already exist. -## Delivery record +## Contribution workflow -See [the implementation record](docs/implementation.md) for delivered scope, task mapping, validation, and PR dependencies. Repository workflow skills and frontend guidelines are stored locally under `.agents/skills/` and `frontend/AGENTS.md`. +Follow [`AGENTS.md`](AGENTS.md) and the applicable scoped guidelines, including +[`frontend/AGENTS.md`](frontend/AGENTS.md). Repository skills belong under +[`.agents/skills/`](.agents/skills). + +Implementation work uses a Gitea task and linked branch, validation, commits, +a push and a PR. Merge only when authorized. Record scope, validation and known +limitations in the task and [implementation record](docs/implementation.md). diff --git a/docs/implementation.md b/docs/implementation.md index 9be8a31..fe8ffde 100644 --- a/docs/implementation.md +++ b/docs/implementation.md @@ -133,3 +133,32 @@ 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. + +## 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.