Merge pull request 'Refresh root README for current app and shared packages' (#19) from docs-18 into main
Reviewed-on: #19
This commit was merged in pull request #19.
This commit is contained in:
tech committed
commit
61ccfc1844
2 files changed
+155
-18
No files matched your search
@@ -1,43 +1,171 @@
|
|||||||
# SXCHNGE
|
# 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
|
## Repository structure
|
||||||
|
|
||||||
| Folder | Purpose | Status |
|
| Location | Purpose |
|
||||||
| --- | --- | --- |
|
| --- | --- |
|
||||||
| [`website/`](website/README.md) | Existing Astro public website, assets, brand references, and Sites configuration | Implemented |
|
| [`website/`](website/README.md) | Astro public website, assets, brand references and hosting configuration |
|
||||||
| [`frontend/`](frontend/README.md) | Consumer application and Flutter packages | Theme, shared auth, localized app, verification and routing implemented |
|
| [`frontend/app/`](frontend/app/README.md) | Flutter consumer app with a web runner |
|
||||||
| [`backend/`](backend/README.md) | Product BFF integrating with Sendico | Prepared for implementation |
|
| [`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
|
```sh
|
||||||
cd website
|
cd website
|
||||||
npm ci
|
npm ci
|
||||||
npm run dev -- --background --host 127.0.0.1
|
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 test
|
||||||
npm run check
|
npm run check
|
||||||
npm run build
|
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
|
## 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.
|
- sxchnge will own consumer registration/sessions, onboarding and exchange UX,
|
||||||
- Sendico remains authoritative for payment execution, KYC records and verification, policy decisions, and limit enforcement.
|
and mappings to stable, organization-scoped Sendico customer references.
|
||||||
- The sxchnge organization, backend integration principal, and individual customer references are distinct identities. Consumers must not share the integration account's customer identity.
|
- Sendico remains authoritative for payment execution, KYC records and
|
||||||
- The BFF should use a supported API contract rather than copying Sendico's existing BFF or depending on its local internal modules.
|
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).
|
||||||
@@ -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.
|
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`.
|
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.
|
||||||
Reference in new issue
Block a user