# SXCHNGE

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

| 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 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.

## Run the consumer app

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
```

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 app → sxchnge BFF → supported Sendico API**.

- 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 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.

## Contribution workflow

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).

## Identity verification preview

Open `/#/identity` or select **Explore verification & limits** from login or email
confirmation. The optional flow covers passport and selfie selection, review,
submission, pending review, approval, correction requests and denial in EN/RU.
Use sample images only: photos are never uploaded and drafts are not persisted.

The shared [sxchnge_kyc package](frontend/packages/sxchnge_kyc/README.md) provides
identity and limits services/providers for web and future mobile clients. Limits
are fetched through `LimitsProvider → LimitsService`; fixture amounts and simulated
review decisions demonstrate the future backend contract. Higher limits apply
only when returned by that service. Production review/storage/support and financial
authorization are not connected. See the [UX plan](docs/ux/kyc.md) for state, error,
privacy and measurement details.