SXCHNGE

Product repository for the sxchnge public website, Flutter consumer app, reusable packages, and a backend for frontend (BFF) bootstrapped from Sendico.

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.

The default preview uses dummy services. Configuring the existing backend URL and client ID selects authenticated BFF adapters for auth, identity, limits and wallet quotations/payment execution. Optional Sendico configuration and dedicated customer financial resources are required for real operations; analytics still defaults to an in-memory sink. See payment setup and rollout.

Repository structure

Location	Purpose
website/	Astro public website, assets, brand references and hosting configuration
frontend/app/	Flutter consumer app with a web runner
sxchnge_theme	Reusable light/dark themes and bundled Onest font
sxchnge_auth	Shared auth contracts, providers, two-factor page and dummy services
sxchnge_analytics	Typed journey events, recorder and bounded in-memory dummy analytics
backend/	Copied BFF/auth/account foundation and isolated public Sendico contracts
.agents/skills/	Repository agent skills
docs/	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.

Local Docker development

make build && make up

This builds the product images and starts an isolated Vault, authenticated MongoDB replica set and NATS JetStream. First startup intentionally stops after bootstrap until you set api_key in Vault's kv/services/notifications/email/resend secret and the verified sender in infra/local/notifications/runtime.yml. Then rerun make up to start notifications, BFF and the frontend at https://localhost:5126.

All image inputs resolve to current stable releases and are pinned by digest for the build. Services fetch secrets from Vault; Mongo application credentials come from Vault's database plugin. See the local development guide for Vault provisioning, local HTTPS trust, lifecycle commands and verification.

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.

cd frontend/app
flutter pub get
flutter gen-l10n
flutter run -d chrome

Build the web app from the same directory:

flutter build web --no-wasm-dry-run

Output is frontend/app/build/web/. To inspect that build locally, from the repository root:

docker run --rm --pull always -p 127.0.0.1:5123:80 \
  -v "$PWD/frontend/app/build/web:/srv:ro" caddy:alpine caddy file-server --root /srv --listen :80

Open the local app. 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 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:

cd website
npm ci
npm run dev -- --background --host 127.0.0.1

Manage the background server from website/:

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:

make test-frontend

From each changed Flutter package, run formatting and analysis. For example:

cd frontend/app
dart format --output=none --set-exit-if-changed lib test
flutter analyze

Validate the website independently:

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 integration is: consumer app → sxchnge BFF → Sendico public HTTP API. SXCHNGE is one organization in Sendico; its customers are owned locally. Local accounts have no organization tenancy, membership, roles or policy engine.

• sxchnge will own consumer registration/sessions, onboarding and exchange UX, and mappings from local customers to organization-scoped platform resources.
• 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 uses only the public HTTP API. Existing BFF/auth/account components are copied into SXCHNGE-owned code; private transports and sibling module dependencies are not used. 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.

Client architecture

Keep DTO → mapper → service → data model → provider → UI boundaries in every feature and shared package. Services return mapped domain models; providers sit on services and expose loading/error/data state. Widgets render models and call provider actions. DTO serialization and backend calls belong below this boundary. Shared packages own reusable domain logic for web and mobile; stub replacements must preserve the same contracts. See the standing rules in AGENTS.md and frontend/AGENTS.md.

Contribution workflow

Follow AGENTS.md and the applicable scoped guidelines, including frontend/AGENTS.md. Repository skills belong under .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.

Identity verification preview

Open /#/identity or use Limits → Verify identity in the workspace. 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 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 for state, error, privacy and measurement details.

Exchange workspace preview

Choose Explore your accounts on login/email confirmation, or open /#/accounts. Currency cards show only available funds. Select an account, then top up, exchange or pay out through input → review → status. Review shows fees and actual debit and credit; status explains where the money is, including processing and failed returns. Activity, account balances and limits use one coherent demo ledger.

Settings owns English/Russian account language. Limits links to optional KYC; no verification remains a valid account state with basic limits.

The shared wallet package is reusable by mobile clients. Transactions, rates, fees, recipients and profile storage are explicitly simulated and reset on reload. No real money moves. See the workspace UX plan and implementation record for scope and validation.

Two-factor verification

Account Settings → Two-factor verification enables or disables protection with a confirmed code. When enabled, login, top-ups, exchanges and payouts use a shared SXCHNGE-themed challenge page. Money challenges retain the reviewed fees and funds movement; cancelling preserves the transaction draft.

The initial service uses email-code fixtures: 123456 is the local test code. No email is sent and settings reset on reload. Method-aware contracts and page instructions also support authenticator challenges; actual TOTP enrollment, validation and recovery remain backend integration work. See the two-factor UX contract and shared auth package.

Backend integration plan

The BFF architecture and Sendico service audit defines consumer identity, financial-provider boundaries, reusable components, contract gaps and delivery phases. Selected Sendico code has been adapted with recorded provenance; the projects share no runtime modules.

Run make test-backend, make lint-backend or make run-backend from the root. The runtime installs local authentication, verification delivery, identity and wallet transports. Public Sendico adapters support independent customer facts, reviewed identity/limits and quotation/execution through the BFF. Deployment and financial-resource provisioning are separate; backend account-language saving and additional funding/recipient onboarding remain follow-up work. See the backend run guide and payment integration.