From fc0644341d13c239d2af4ee72eb4a23789be84e1 Mon Sep 17 00:00:00 2001 From: Stephan D Date: Sat, 12 Sep 2026 08:46:10 +0200 Subject: [PATCH 1/2] Refresh root README for current app and shared packages --- README.md | 164 ++++++++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 146 insertions(+), 18 deletions(-) diff --git a/README.md b/README.md index 10d61e4..4ceeebe 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.x** (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). From 51f0e314671984da4a2990081ad14fbd09f2a4c0 Mon Sep 17 00:00:00 2001 From: Stephan D Date: Sat, 12 Sep 2026 08:46:43 +0200 Subject: [PATCH 2/2] Record README delivery and clarify Dart prerequisite --- README.md | 2 +- docs/implementation.md | 9 +++++++++ 2 files changed, 10 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 4ceeebe..398e9c5 100644 --- a/README.md +++ b/README.md @@ -33,7 +33,7 @@ currently included. Local `.vscode/` configuration is ignored. ## Run the consumer app -Requires Flutter **3.47.0 or later** with Dart **3.13.x** (below Dart 4), matching +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 diff --git a/docs/implementation.md b/docs/implementation.md index 356290b..ed6b82f 100644 --- a/docs/implementation.md +++ b/docs/implementation.md @@ -132,3 +132,12 @@ 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.