Project handoff
Seaven
Flutter app — Clean Architecture (GetIt · GetX).
- Stack
- Flutter · GetIt · GetX · Clean Architecture
Authentication
Dual-token (customer + seller) email/password, Google and Apple sign-in, registration with email-OTP verification, and password recovery — all gated by a GoRouter redirect that also enforces profile setup and ToS consent.
Riverpod · GoRouter · Dio · SharedPreferences
API surface
| Method | Endpoint | Purpose | Auth | Status |
|---|---|---|---|---|
| POST | /auth/customer/emailpass-verified | Authenticate as a customer with email + password and receive a session token (mandatory leg of the dual-login). | — | no status |
| POST | /auth/seller/emailpass-verified | Best-effort seller login using the same credentials — used to detect multi-role users. | — | no status |
| POST | /auth/customer/google-mobile | Exchange a Google OAuth payload (id_token + access_token) for a customer session token. | — | no status |
| POST | /auth/apple/callback | Exchange an Apple Sign-In identity payload for a customer session token. | — | no status |
| POST | /auth/customer/emailpass-verified/register | Create a customer account; backend emails an OTP and does NOT issue a session yet. | — | no status |
| POST | /auth/customer/emailpass-verified/verify | Verify the emailed OTP and finally issue the customer session token. | — | no status |
| POST | /auth/customer/emailpass-verified/reset-password | Trigger a password-reset email for the given address. | — | no status |
| POST | /auth/reset-password/verify | Verify the OTP from the reset email and receive a short-lived reset token. | — | no status |
| POST | /auth/customer/emailpass-verified/update | Set a new password using the short-lived reset token. | — | no status |
| POST | /store/change-password/emailpass-verified | Rotate the authenticated customer's password from the settings screen. | — | no status |
| POST | /auth/password-change/ | Legacy password-change endpoint kept on AuthApiService but no longer wired into any UI. | — | no status |
| POST | /auth/sign-in/email | Legacy single-token email/password sign-in — kept on the old AuthService for AuthRepositoryImpl compatibility, not used by the current Riverpod notifier. | — | no status |
| POST | /fcm/token | Side-channel: upload the FCM push token for the active auth scope so the backend can target push to this device + role. | — | no status |
Presentation layer
Login Screen · features/shared/auth/login/presentation
Single screen offering email/phone + password, plus Google and Apple buttons. Listens to loginNotifierProvider for the per-method loading flags so each button can show its own spinner independently.
- User picks auth method (email or phone) via AuthMethodNotifier.
- Enters credentials → submits → ref.read(loginNotifierProvider.notifier).login(...).
- loginNotifierProvider streams state — isPasswordLoading toggles the submit button spinner.
- On state.isAuthenticated the GoRouter redirect fires and navigates to /home.
- On state.error a SnackBar surfaces the unwrapped exception message.
- Three independent loading flags (password / google / apple) prevent cross-method spinner flicker.
- Apple button is conditionally rendered on iOS only — Android shows Google only.
- Google cancellation must not surface as an error — the notifier returns false but leaves state.error null.
Phone-based password login is part of the UI toggle but the backend currently only supports email — picking 'phone' falls back to email validation messages.
Register + OTP Screens · onboarding_register/presentation/pages
Two-step wizard pages: RegisterStepPage collects email + password and triggers registerNotifier; OtpStepPage receives the email via route extra and verifies the 6-digit code, after which the session is finally persisted.
- RegisterStepPage → registerNotifier.register(email, password).
- On success, wizard pushes OtpStepPage with state.extra = {email}.
- OtpStepPage submits the code → AuthApiService.verify → AuthStorageService.saveSessionOtp persists the token.
- GoRouter redirect bounces to /onboarding_register (or /onboarding_register_seller for pending sellers).
- Hot-reload of OtpStepPage with no route extra crashes — defensive cast is intentional, dev-only failure.
- Re-sending the OTP is rate-limited server-side; UI cools down the button for ~30s without consulting the backend.
- If the user backgrounds the app between register and OTP, the partially-saved pendingRegistrationData (in AuthStorageService) keeps the wizard resumable.
The /register and /otp routes both point into the onboarding-register wizard rather than the legacy auth/register/register.dart screen, which is kept around but unrouted.
Password Recovery Screens · forget_password + change_password presentation
Four screens: ForgetPasswordScreen (request email), ResetPasswordOtpScreen (verify code), ResetPasswordScreen (set new), ChangePasswordScreen (authenticated rotate). Each consumes its dedicated Riverpod notifier and surfaces a single error toast on failure.
- ForgetPasswordScreen → forgotPasswordProvider.sendResetEmail.
- Navigation pushes ResetPasswordOtpScreen with email; on verify it pushes ResetPasswordScreen with {email, token}.
- ResetPasswordScreen submits new password and pops back to login.
- ChangePasswordScreen (settings entry) calls changePasswordProvider directly without OTP.
- Reset-flow routes pass data via state.extra and crash on direct deep-link entry (no deep-link guard).
- ChangePasswordScreen does not require the user's current password to match — backend handles that validation; the screen surfaces server errors as generic messages.
- Both flows treat any non-2xx as 'Something went wrong. Try again!' to avoid enumeration / leaking server state.
Generic error messages are a deliberate design choice — see the matching comment in change_password_notifier.dart.
Domain layer
Login Notifier · presentation/providers · Notifier<LoginState>
Riverpod Notifier orchestrating email/password, Google and Apple sign-in. On password login it issues a 'dual login' (customer + seller endpoints) to discover whether the same credentials also resolve a seller account, then persists both tokens and forces the user role accordingly.
- Screen calls login(email, password); state flips to isLoading + isPasswordLoading.
- AuthApiService.dualLogin posts /auth/customer/emailpass-verified, then /auth/seller/emailpass-verified.
- Seller 401 is swallowed and returned as null — the user is treated as customer-only.
- _persistAuthenticatedSessions saves customer + (optional) seller tokens via AuthStorageService.
- userRoleProvider.notifier.setRole(freelancer|client) forces the active role based on which tokens exist.
- State updates to isAuthenticated = true; the GoRouter redirect then bounces /login → /home.
- Seller endpoint returns 401 → treat as 'not a seller', proceed as customer-only (loginSeller swallows the 401).
- Google/Apple cancellation throws GoogleSignInExceptionCode.canceled / AuthorizationErrorCode.canceled — clear loading flags but do not surface as an error.
- Apple only sends name/email on the first authorization — subsequent logins must rely on the backend mapping by Apple subject ID.
- skipTermsConsent flag short-circuits the (currently commented-out) ToS pre-check; the router still enforces ToS post-login.
- Token may be expired when restored from storage — JwtHelper.isTokenExpired is logged but the UI does not yet trigger a refresh.
The commented-out termsConsentService.getConsentRequirement block is the previous design — ToS is now enforced exclusively by the GoRouter redirect (see auth-routes-guard). Calls are delegated to AuthApiService — see the auth-api-service node for the wire-level inventory.
Register Notifier · auth/register · Notifier<RegisterState>
Posts a new customer to /auth/customer/emailpass-verified/register but deliberately does NOT persist a session — the user is logged in only after they verify the OTP emailed by the backend (see the OTP step in the onboarding-register wizard).
- RegisterStepPage submits → register(email, password).
- AuthApiService.register POSTs the credentials and gets back a RegisterResponse.
- On success state.isVerified flips to true (semantic: 'request accepted, awaiting OTP').
- Wizard advances to OtpStepPage; the actual session is saved by AuthStorageService.saveSessionOtp after /auth/customer/emailpass-verified/verify.
- Backend returns 200 with {type: 'unauthorized'} — surfaced as an Exception (Medusa-style soft failure).
- Email already exists → backend returns a structured error; message is hoisted unchanged into state.error.
- Session is intentionally not saved here — calling save before OTP verification would log the user into an unverified account.
isVerified in RegisterState is misleadingly named — it means 'register call succeeded', not 'email verified'. The actual verification happens in the OTP step.
Forgot Password Notifier · forget_password/presentation/providers
Three coordinated notifiers that drive the email-based reset flow: ForgotPasswordNotifier triggers the reset email, ResetPasswordOtpNotifier verifies the 6-digit code, UpdatePasswordNotifier sets the new password. Each owns its own state and is consumed by a dedicated screen.
- ForgetPasswordScreen → sendResetEmail(email) POSTs /auth/customer/emailpass-verified/reset-password.
- 201 flips emailSent=true; user is navigated to ResetPasswordOtpScreen with the email in extra.
- ResetPasswordOtpScreen verifies the code, receives a short-lived reset token.
- ResetPasswordScreen submits new password + token; backend rotates credentials.
- User is bounced to LoginScreen with the new password.
- Backend returns the same 201 whether the email exists or not (enumeration-safe) — UI must not leak existence.
- Reset token expires server-side; UI surfaces a generic 'Something went wrong' to avoid hinting at expiry.
- If the user navigates back from the OTP screen, the email field must repopulate — state is held by Riverpod, not by route extra.
The seller role has no separate forgot-password flow — backend resets the customer credential and the seller token is invalidated implicitly on next dual-login.
Change Password Notifier · change_password/presentation/providers
Authenticated password rotation from the settings screen. Posts old + new password to /store/change-password/emailpass-verified using the current customer token.
- ChangePasswordScreen calls changePassword(oldPassword, newPassword).
- DioHelper.post fires with authScope='customer' — interceptor attaches the customer bearer token.
- 200 → state.isUpdated = true; the screen pops back to settings with a success snackbar.
- Non-200 / network error → state.error is set with a generic message.
- Backend HTML 500 (rare) — caught and surfaced as 'Server error. Please try again later.' (see auth-api-service _handleBadResponse-like logic inline).
- Wrong old password → 401/403 with message rewritten to 'Current password is incorrect'.
- Successful rotation does not invalidate the local token — the same bearer keeps working until natural expiry.
There are TWO change-password endpoints in the code: this notifier hits /store/change-password/emailpass-verified; AuthApiService.changePassword hits /auth/password-change/. Only the notifier path is wired into the UI today.
Auth State Notifier · core/services/auth_storage.dart · StateNotifier<AuthState>
Global StateNotifier exposing the (isLoggedIn, role) tuple. On construction it inspects persisted tokens and resolves the initial role: seller token present → freelancer, customer-only → client, otherwise guest.
- App boot → AuthStateNotifier ctor calls _loadInitialState.
- _loadInitialState reads isLoggedIn from SharedPreferences and inspects hasSellerRole().
- switchRole(newRole) is invoked when the user toggles between client and freelancer in the UI — only succeeds if a token for that role exists.
- logout() clears the session, deletes the FCM token, and resets state to AuthState(false, guest).
- AuthState overrides == and hashCode so refreshAuthState() does not re-trigger watchers when the (isLoggedIn, role) tuple is unchanged — without this, /store/customers/me would fetch twice on home boot (see explicit comment in code).
- logout swallows NotificationService.deleteToken errors when FCM is not initialized.
- switchRole silently no-ops if the requested role has no stored token — the UI must not assume the call succeeded.
Lives in auth_storage.dart alongside the storage service rather than under features/auth — it is consumed across the whole app (settings, profile, navigation) so its DI scope is core.
Data layer
Auth API Service · core/services/auth_service.dart
Thin Dio wrapper for every auth endpoint. Owns the dual-login dance: loginCustomer is mandatory, loginSeller is best-effort (returns null on 401 instead of throwing) so callers can detect 'user is customer-only' without an exception path.
- dualLogin(request) calls loginCustomer first — any non-401 customer error throws.
- Then calls loginSeller — a 401 is swallowed and returned as null.
- Returns DualLoginResponse{customerToken, sellerToken?} with hasBothRoles / isCustomerOnly helpers.
- register, verify (OTP), loginGoogle, loginApple, changePassword are independent endpoints — no dual handling.
- Every call annotates Options with a RequestTrace (feature/screen/action/authScope) — used by TraceInterceptor in debug mode.
- Apple/Google login both return a DualLoginResponse with sellerToken=null; OAuth users have no seller path yet.
- changePassword has bespoke error mapping for HTML 4xx/5xx responses (DOCTYPE detection) because the Medusa admin path leaks HTML in some failure modes.
There is a legacy AuthService at lib/src/features/shared/auth/login/data/auth_service.dart hitting /auth/sign-in/email — only used by the older AuthRepositoryImpl, not by the current LoginNotifier. Endpoints already exposed via the notifier nodes (login-notifier, register-notifier, change-password-notifier) are NOT duplicated here — only the legacy /auth/sign-in/email is.
Auth Storage Service · core/services/auth_storage.dart · SharedPreferences
Wraps SharedPreferences for everything session-shaped: customer + seller tokens, isLoggedIn flag, profileSetupComplete, ToS acceptance, pending seller registration, and per-(fcm,auth) tokens already synced to backend.
- saveCustomerSession / saveSellerSession write token + isLoggedIn=true.
- getCustomerToken / getSellerToken are used by the Dio auth interceptor on every request.
- savePendingRegistrationData stashes phone/username/firstName/lastName between register and OTP verify.
- savePendingSellerOnboarding holds seller-type + selected services across the 'devenir prestataire' wizard.
- clearSession on logout removes tokens, role, profile-setup flag, ToS flag, and pending onboarding selections.
- FCM tracking key is keyed by (fcmToken, last 20 chars of authToken) so a token rotation forces a re-sync (see _getFcmTrackingKey).
- clearSellerSession is callable independently — used when a user 'unbecomes' a seller without logging out.
- Pending seller onboarding keys persist across app restarts; clearPendingSellerOnboarding must be called on completion to avoid stale carry-over.
No secure storage — tokens live in SharedPreferences. Acceptable for Medusa session tokens (server-revocable) but means a rooted device can exfiltrate them. Local storage keys (no HTTP, SharedPreferences): • 'customer_token' — write: saveCustomerSession / saveSessionOtp — read: getCustomerToken (consumed by DioHelper auth interceptor) — clear: clearSession • 'seller_token' — write: saveSellerSession — read: getSellerToken — clear: clearSession + clearSellerSession • 'is_logged_in' — bool — read: isLoggedIn (consumed by GoRouter redirect + HomeScreen) • 'is_profile_setup_complete' — bool — write: markProfileSetupComplete (post-onboarding) • 'has_accepted_tos' — bool — write: markTosAccepted (after /store/tos/consent succeeds) • 'is_pending_seller_reg' — bool — write: setPendingSellerRegistration — gates the auth redirect to /onboarding_register_seller • 'pending_reg_{phone|username|first_name|last_name}' — String — write: savePendingRegistrationData (between register POST and OTP verify) — consumed by lib/src/features/shared/onboarding_register/presentation/pages/otp_step_page.dart • 'pending_seller_{type|services}' — write: savePendingSellerOnboarding — consumed by lib/src/features/client/devenir_prestataire/devenir_prestataire_screen.dart • 'fcm_sent_<fcmToken>_<authSuffix>' — bool — write/read: markFcmTokenSent / isFcmTokenSent — dedupes /fcm/token uploads
Dio Auth Interceptor · core/network/dio_helper.dart · _authInterceptor
Per-request resolution of which token to attach. Five-step priority: explicit authScope='none' opt-out → caller-supplied Authorization header → explicit scope='seller'|'customer' → path heuristics (/vendor /seller → seller; /store /social /auth/customer → customer) → fall back to persisted active role.
- onRequest reads options.extra['auth_scope'] from the per-call RequestTrace.
- If 'none' → strip Authorization and pass through.
- If caller already set Authorization → respect it but also attach seller_tok header for /vendor paths.
- Otherwise pick scope by extra → path prefix → loadUserRole() (persisted role).
- Attach Bearer token from AuthStorageService; fire-and-forget _checkAndSendFcmToken on first use of that token.
- /vendor paths always also receive a seller_tok header in addition to Authorization — required by the backend's vendor-impersonation middleware.
- FCM sync uses a separate raw Dio instance to avoid interceptor recursion (would otherwise self-call /fcm/token).
- If no token is found for the resolved scope, the request is sent unauthenticated (no early error) — debug log only.
- _fcmSyncInProgress set prevents concurrent FCM sync for the same auth token during burst requests at app start.
The path heuristics are the load-bearing piece — many endpoints don't pass authScope explicitly and rely on this fallback. Adding a new endpoint family means updating _isSellerOnlyPath / _isCustomerOnlyPath.
JWT Helper · core/jwtHelper.dart
Pure utility for decoding the JWT payload (no signature verification, since the client only consumes the token) and computing expiry. Used by LoginNotifier on session restore to log whether the cached token is already past its 5-minute pre-expiry window.
- decodeToken splits the JWT into 3 parts, base64-url decodes the middle segment.
- isTokenExpired compares exp * 1000ms against now() minus a 5-minute safety margin.
- getTokenExpiry returns the raw DateTime for diagnostic use.
- Malformed JWT (not 3 parts) returns null from decodeToken and is treated as expired by isTokenExpired.
- Missing exp claim is also treated as expired — the app prefers to force a re-login over trusting a non-expiring token.
- There is no refresh logic yet — isTokenExpired is logged but not acted upon (LoginNotifier._checkAuthStatus is a TODO).
Despite the camelCase filename (jwtHelper.dart), the class is JwtHelper. Don't rename without updating every import.
Dependency Injection layer
GoRouter Auth Redirect · core/routing/app_router.dart · redirect()
The single redirect function in goRouter performs the entire auth funnel: not-logged-in → /login; logged-in but profileSetupComplete=false → /onboarding_register(_seller); ToS not accepted → /terms; seller-only routes hidden when !hasSellerRole. It is the de-facto auth state machine.
- On every navigation, fetches isLoggedIn, isProfileSetupComplete, hasSellerRole, isPendingSellerRegistration, ToS status.
- Splash route is always allowed through (initial loading screen).
- Unauthenticated + auth route → pass; unauthenticated + anything else → /login.
- Authenticated + incomplete profile → /onboarding_register or /onboarding_register_seller (based on pending flag).
- Authenticated + complete + ToS pending → /terms; if already there → pass.
- Authenticated + on auth/onboarding route → bounce to /home.
- Authenticated + seller-only path + !hasSellerRole → /home.
- _hasConsentedToS is a module-level memoization to stop the redirect spamming /tos/latest on every frame while the user is parked on the ToS screen — without it, the router enters a backend-pinging loop.
- isPendingSellerRegistration picks which onboarding wizard to route to, branching what is otherwise a uniform onboarding flow.
- isEditPrestationRoute uses a regex on /prestation/:id/edit because GoRouter does not expose the route name during the redirect phase.
Every redirect awaits SharedPreferences reads serially — adding more checks here will slow first-frame navigation. The pattern is to push new gates into _verifyTosConsent-style memoized helpers.
Auth Provider Wiring · Riverpod NotifierProviders for the auth feature
There is no GetIt — every auth dependency is a Riverpod Provider declared next to its notifier. authApiServiceProvider and authStorageServiceProvider are the two leaf providers; the notifiers compose them in their build() methods.
- authApiServiceProvider exposes a singleton AuthApiService (wraps Dio).
- authStorageServiceProvider exposes AuthStorageService (wraps SharedPreferences).
- loginNotifierProvider, registerNotifierProvider, forgotPasswordProvider, changePasswordProvider — each ref.read the two leaf providers in build().
- authStateProvider (StateNotifierProvider, legacy API) exposes the global AuthState consumed app-wide.
- userRoleProvider (defined in user_role.dart) is the third global the auth feature mutates — switchRole / setRole / saveUserRole.
- authStateProvider uses the legacy StateNotifierProvider (flutter_riverpod/legacy.dart) while all per-feature notifiers use the modern NotifierProvider — both coexist on Riverpod 3.x.
- build() is called once per notifier lifecycle; ref.read inside build is safe but ref.watch would create a rebuild loop.
- Apple/Google SDKs are constructed lazily inside the notifier methods (not in DI) so dotenv must be loaded first — main.dart guarantees ordering.
The two leaf providers are duplicated as plain class instantiations elsewhere (e.g. NotificationService also constructs AuthStorageService directly) — Riverpod is the canonical wiring but not strictly enforced.
Home & App Shell
The post-login app shell: a ShellRoute that wraps every secondary screen with a persistent bottom nav, an IndexedStack of role-aware tabs, a 4×4 home grid that branches between client and freelancer landing pages, and a radial 'arc' create-menu.
Riverpod · GoRouter ShellRoute · PageView
API surface
| Method | Endpoint | Purpose | Auth | Status |
|---|---|---|---|---|
| GET | /store/tos | Fetch the latest published ToS document (id, version, content URL). | — | no status |
| GET | /store/tos/consent?termsVersion=:v | Check whether the current user has consented to a given ToS version. | — | no status |
| POST | /store/tos/consent | Record the user's consent to a ToS version. | — | no status |
Presentation layer
Home Screen · presentation/home.dart · ConsumerStatefulWidget
Top-level Home screen. Holds the IndexedStack of tab pages and decides which set of tabs to render based on isLoggedIn. AutomaticKeepAliveClientMixin keeps every tab subtree warm so swiping back doesn't rebuild map / messages / profile.
- initState schedules a post-frame callback: refreshAuthState + _checkInitialTos + _checkPendingSeller.
- build watches authStateProvider and bottomNavIndexProvider.
- _buildPages returns [Home, Map, Profile] for guests or [Home, Map, Messages, Profile] for authenticated users.
- Horizontal swipe left pushes /search via context.pushNamed.
- ToS check on first frame redirects to /terms if the consented version is stale.
- Pending-seller redirect: if isPendingSellerRegistration is true on entry, the user is sent to /devenir-prestataire even though they completed initial onboarding.
- ToS check is duplicated here (in addition to the GoRouter redirect) because the redirect's memoization makes it idempotent — the home-screen call is the authoritative re-check after login.
- currentIndex is clamp(0, pages.length - 1) to survive a guest→logged-in transition where the tab count grows mid-session.
Horizontal-drag → /search is intentional but undiscoverable; the visible CTA is the tiny circular icon in HomePage. Don't 'fix' the size without coordinating with design.
Home Page (tab content) · presentation/home_page.dart
The 'Home' tab itself — a 2-page PageView showing FirstPage (primary 16-item grid) and SecondPage (secondary grid). Renders the Stories strip above the grid when isLoggedIn, and a compact search CTA below.
- PageController drives a PageView with [FirstPage, SecondPage].
- onPageChanged updates homeCurrentPageIndicatorProvider so the dot indicator follows.
- Stories widget appears only for authenticated users.
- Tapping the search CTA pushes /search via context.push.
- PageView keeps both pages alive via AutomaticKeepAliveClientMixin on HomePage — switching pages does not refetch stories.
- Indicator color flips on Theme.brightness — required because the white primary brand color is invisible on the light bg.
- When commented-out search CTA returns, the tiny icon-only fallback must keep working for users who haven't pulled the new build.
Large commented-out block at the bottom is the previous full-bar search CTA — kept as design reference, not dead code by accident.
Home Grid (FirstPage / SecondPage) · presentation/widgets/{first,second}_page.dart
Two 4×4 grids of HomeGridItem tiles. FirstPage._prestatireItems and _clientItems are two parallel static lists picked at runtime based on userRoleProvider. Each tile carries a routePath, image asset, requiresLogin flag and optional rolesAllowed filter.
- FirstPage.build reads userRoleProvider and picks the matching item list.
- Each HomeGridItem renders the asset (light/dark variant) + label + 'NEW' badge.
- Tapping a tile checks requiresLogin against the current auth state, then context.push(routePath).
- Items with routePath like '/urgent' / '/concours' point at not-yet-implemented routes — they render but navigate to a 404-style stub.
- imageDark fallback to image when the dark variant is absent — handled by HomeGridItem.
- isNewFeature controls a small 'NEW' chip; never auto-cleared, must be manually set false on each new build.
- Several routes (/urgent, /domicile, /event, /before-after, /formations, /finances, /concours) are placeholders — the team uses them as visible TODOs.
Item lists are static const-ish but use HomeGridItemData (not const due to AppRoute getters); refactoring AppRoute.path to a const string would let the whole list be const.
App Shell Scaffold · presentation/widgets/app_shell_scaffold.dart
ConsumerStatefulWidget wrapping every screen reachable via the ShellRoute with a 5-item BottomNavigationBar (or 3 items for guests). Index 2 is the floating '+' that toggles the arc-menu instead of navigating.
- Watches authStateProvider, arcMenuProvider and bottomNavIndexProvider.
- _buildNavItems returns 3 or 5 items depending on isLoggedIn.
- _onItemTapped: if logged in and index==2 → toggle arcMenuProvider; else update bottomNavIndexProvider and context.goNamed('home').
- When arcMenuProvider is true, draws a BackdropFilter blur layer and the ArcSearchMenu on top.
- navIndex is shifted around the '+' slot for authenticated users (currentIndex < 2 ? currentIndex : currentIndex + 1) so the underlying page list never includes the '+'.
- context.goNamed('home') on tab-tap rather than IndexedStack.setState — required because the user could be on a secondary screen pushed on top of the shell.
- Backdrop blur uses ImageFilter.blur(8,8) + 25% black overlay — tuning this affects perceived perf on low-end Android.
Commented-out 'Mode Prestataire' banner is intentional — toggled off post-design review. Don't delete without checking with product first.
Arc Search Menu · presentation/widgets/curved_icon_menu.dart
Radial 'fan out' menu of quick-create shortcuts that appears when the floating '+' is tapped. Animates with a single AnimationController using easeOutBack, placing items on a 120-radius arc above the nav bar.
- AnimationController(.forward) on initState; animation is consumed by each item's Transform.
- Each _ArcMenuItemData has imagePath, optional imagePathDark, label and an onTap callback.
- Tapping an item closes the menu (arcMenuProvider.notifier.state = false) and pushes its route.
- Tapping outside (the BackdropFilter) closes the menu via the same provider.
- Animation is one-way: there's no reverse on dismiss, the whole subtree just unmounts.
- Items render even before the controller completes — a fast '+' tap then dismiss looks janky without the BackdropFilter masking it.
ItemSize 56 + radius 120 is balanced for a phone of ~390 logical width — tablets will leave dead space at the edges.
Domain layer
HomeGridItemData · models/home_grid_item_model.dart
Lightweight model describing each tile in the home grid: label, routePath, image, optional dark variant, requiresLogin gate, optional rolesAllowed filter and an isNewFeature badge flag.
- Constructed inline in FirstPage._prestatireItems and _clientItems.
- isAllowedFor(role) returns true when rolesAllowed is null or contains the given role.
- HomeGridItem widget consumes the data to render image + label and to gate the tap handler.
- rolesAllowed=null is interpreted as 'any role' — not a 'no roles' sentinel.
- requiresLogin is checked client-side only; deep-linking to the route directly relies on the GoRouter redirect to bounce guests to /login.
There's no equality override — the items lists are recreated on every build but they're const-ish enough that it doesn't cause widget churn.
Home State Providers · provider/provider.dart · StateProvider × 3
Three small StateProvider<int|bool> values backing the shell UI: bottomNavIndexProvider (active tab), homeCurrentPageIndicatorProvider (PageView dot), arcMenuProvider (radial menu open).
- AppShellScaffold reads bottomNavIndexProvider; nav tap writes back.
- HomePage onPageChanged writes homeCurrentPageIndicatorProvider.
- AppShellScaffold toggles arcMenuProvider on the '+' tap and on backdrop tap.
- Providers reset to 0/false when the ProviderScope is torn down (only at app kill) — they survive logout.
- bottomNavIndexProvider is indexed into a list whose length depends on auth state — callers must clamp.
These are legacy StateProviders (flutter_riverpod/legacy.dart) — fine for trivial values, but new state goes through NotifierProvider.
Data layer
isLoggedIn Provider · provider/provider.dart · FutureProvider<bool>
Convenience FutureProvider that reads isLoggedIn from AuthStorageService once. Most of the shell uses authStateProvider directly; this provider is here for places that want a Future<bool> rather than a live AuthState.
- authStorageProvider exposes AuthStorageService() (re-instantiated per provider build).
- isLoggedInProvider reads it and forwards AuthStorageService.isLoggedIn().
- Future resolves once; the provider caches the result until ref.invalidate.
- Stale after logout — code that consumes this must invalidate or prefer authStateProvider for live updates.
- Returns false for the (logged in but tokens cleared) edge case because isLoggedIn flag is what's checked, not the tokens themselves.
Duplicates a slice of AuthStateNotifier's responsibility — keep only one source of truth in new code.
Dependency Injection layer
ShellRoute + Home Route · core/routing/app_router.dart · ShellRoute
Wires the home route and almost every authenticated screen inside a single ShellRoute whose builder is AppShellScaffold. This is what makes the bottom nav persistent across pushes — secondary screens are children of the shell, not pushes on top of the home screen.
- GoRouter is constructed in app_router.dart with the redirect we describe in the auth feature.
- Routes are split: auth/onboarding/splash live OUTSIDE the ShellRoute (no nav bar).
- Home, settings, cart, prestataires, profile, orders, seller dashboards, etc. live INSIDE the ShellRoute and inherit AppShellScaffold.
- Some routes (e.g. /map, /messages) are redirect-only GoRoutes that bounce back to /home so the IndexedStack can switch tabs.
- Pushing onto a ShellRoute child preserves the nav bar; pushing the same route name from outside the shell breaks IndexedStack swap.
- The /add-prestation route lives outside the ShellRoute on purpose — it's a full-screen wizard that should NOT show the nav bar.
- /map and /messages exist as redirect-only routes purely to support deep-linking to a specific bottom-nav tab without a custom URL scheme.
Adding a new top-level screen? Decide first whether it needs the nav bar — placement (inside vs outside ShellRoute) is the deciding factor.
Home ToS / Pending-Seller Bootstrap · presentation/home.dart · _checkInitialTos / _checkPendingSeller
Post-frame side-effects fired the first time HomeScreen mounts: re-check ToS consent (in case the version bumped while logged in), and re-route to /devenir-prestataire if a pending-seller flag is set.
- WidgetsBinding.instance.addPostFrameCallback schedules the work after the first build.
- authStateProvider.notifier.refreshAuthState() reloads (isLoggedIn, role) from storage.
- _checkInitialTos calls TosApiService.getLatestTos + checkConsent; if not consented, context.goNamed(termsOfService).
- _checkPendingSeller reads AuthStorageService.isPendingSellerRegistration; if true, context.goNamed(devenirPrestataire).
- Both checks early-return when isLoggedIn is false — guests don't touch /tos/latest at all.
- If both ToS-stale and pending-seller fire, ToS wins (it's checked first and context.goNamed is async-fire-and-forget).
- Errors are swallowed with a debugPrint — backend outage during ToS check leaves the user on /home rather than blocking them.
Treat this as a redundant safety net — the GoRouter redirect is the primary gate. If you remove either check here, the redirect's memoization (_hasConsentedToS) must be invalidated on login.
Cart
Two-stage cart: an offline-first local cart kept per-user in SharedPreferences during browsing, then a server-side Medusa cart created lazily at checkout. The Medusa cart owns line items, promo codes, shipping and payment sessions.
Riverpod · Medusa Store API · SharedPreferences
API surface
| Method | Endpoint | Purpose | Auth | Status |
|---|---|---|---|---|
| POST | /store/carts | Create a fresh Medusa cart of a given type (provision or physical). | — | no status |
| GET | /store/carts/:cartId | Fetch the current server-side cart (lines, totals, addresses, promotions). | — | no status |
| POST | /store/carts/:cartId/line-items | Add a line item to the cart. | — | no status |
| POST | /store/carts/:cartId/line-items/:lineItemId | Update or delete (quantity=0) a line item. | — | no status |
| POST | /store/carts/:cartId | Patch arbitrary cart fields (shipping address, email, region…). | — | no status |
| GET | /store/shipping-options?cart_id=:id | List shipping options available for the cart's destination + items. | — | no status |
| POST | /store/carts/:cartId/shipping-methods | Attach a chosen shipping method to the cart. | — | no status |
| POST | /store/carts/:cartId/promotions | Apply or clear promo codes on the cart. | — | no status |
| GET | /store/payment-providers?region_id=:id | List payment providers configured for the cart's region. | — | no status |
| POST | /store/payment-collections | Create a payment collection for the cart. | — | no status |
| POST | /store/payment-collections/:id | Resync the amount on an existing payment collection (e.g. after cart change). | — | no status |
| POST | /store/payment-collections/:id/payment-sessions | Initialize a payment session with a chosen provider; returns the Stripe client_secret. | — | no status |
| POST | /store/payment-collections/:id/partial/payment-session | Multi-session partial payment for booking deposits (e.g. deposit + remainder). | — | no status |
| POST | /store/carts/:cartId/set-order | Complete the cart and convert it into an order. | — | no status |
| GET | /store/carts/:cartId/line-items/:lineItemId/questions | Fetch booking-questions for a provision line item. | — | no status |
| POST | /store/carts/:cartId/line-items/:lineItemId/questions/:questionId | Persist a customer's answer to a booking question (option / comment / number / image). | — | no status |
| DELETE | /store/carts/:cartId/line-items/:lineItemId/questions/:questionId | Clear an answer to a booking question. | — | no status |
Presentation layer
Cart Screen · views/cart_screen.dart · ConsumerStatefulWidget
Renders the local cart: list of LocalCartItem rows with qty steppers, a per-row checkbox driven by CartSelectionController, a running total of selected items, and a 'Checkout' button that hands off to CheckoutScreen.
- Watches cartControllerProvider and cartSelectionProvider for state.
- Empty state renders a centered illustration with a 'Continue shopping' CTA.
- Qty stepper calls CartController.updateQuantity; tap-to-remove calls removeItem.
- Promo code input is local-only here — the actual /store/carts/:id/promotions call happens after the backend cart is created in checkout.
- Tapping Checkout pushes the CheckoutScreen, passing only the selected variant IDs (not the full local list).
- PaymentModesData inline list (cash/Paytm/online) is a UI placeholder — the real payment provider list is fetched in CheckoutScreen via fetchPaymentProviders.
- Screen implements TopBarClickListener for the shared top-bar callbacks — back, search, notification icons.
- Hot-reload while the cart is empty re-runs fillData and resets paymentModeList — safe because the list is not user-mutated.
The S.current.cashOnDeliveryLabel-style placeholder rows in fillData are remnants from a previous design where this screen also picked payment methods — keep until the new checkout is fully launched.
Domain layer
LocalCartItem · models/local_cart_item.dart
Per-device cart line. Keyed by variantId, carries productId, title, optional thumbnail, variantTitle, mutable quantity and unitPrice. Round-trips through JSON via encodeList / decodeList for storage.
- addToCart constructs a LocalCartItem and either pushes it onto the list or increments an existing entry's quantity.
- copyWith is used by the controller to immutably bump quantity without losing other fields.
- encodeList serializes the whole list to a JSON string before SharedPreferences write.
- decodeList catches any decoding error and returns []; corrupt local data is silently reset rather than crashing.
- Quantity is marked non-final but the controller always uses copyWith — direct mutation is a footgun that bypasses _saveToStorage.
- totalPrice is computed (no rounding) — float drift accumulates on big quantities but is reconciled when the backend cart is built.
No backend ID field — once the user proceeds to checkout, items are 'translated' into backend line-items by variantId. Local IDs are not preserved server-side.
Cart Controller · controllers/cart_controller.dart · Notifier<List<LocalCartItem>>
Notifier owning the local cart state. Watches currentCustomerIdProvider; when the customer ID changes (login, account switch) it reloads from per-user SharedPreferences. No network calls live here — the backend cart is created later at checkout.
- build() ref.watch(currentCustomerIdProvider) and on a non-null id different from _userId, triggers _loadFromStorage.
- _loadFromStorage reads via LocalStorageService.getLocalCartItems(userId).
- addToCart / updateQuantity / removeItem mutate state, then _saveToStorage persists.
- updateQuantity routes qty<=0 to removeItem.
- clearCart wipes state and clears the per-user key via LocalStorageService.clearLocalCartItems.
- If _userId is null when _saveToStorage runs, it logs and returns without writing — silent no-op when the user isn't loaded yet.
- User switches account in-session → currentCustomerIdProvider changes → previous cart stays in memory until _loadFromStorage replaces it (brief stale window).
- Guest mode has no customerId, so the cart is purely in-memory and is lost on app kill.
The explicit watch+_userId guard exists because Riverpod will rebuild whenever the customerId AsyncValue ticks even if the id is unchanged — without the diff check, every rebuild would re-read storage.
Cart Selection Controller · controllers/cart_selection_controller.dart
Tracks which variantIds the user has ticked for checkout. Derived from cartControllerProvider so it auto-resets to 'all selected' whenever the cart list itself changes.
- build() watches cartControllerProvider and returns cartItems.map(variantId).toSet().
- toggleItem flips one entry; selectAll / deselectAll bulk update.
- CartScreen reads this set to decide which items show a tick + which contribute to the running total.
- Adding a new item to the cart auto-selects it (build re-runs and the new variantId enters the set).
- Removing an item triggers build → the absent variantId silently drops out of the selection.
- Selection is in-memory only; it is not persisted across app kills.
By rebuilding from the cart, selection 'recovers' from edits without the screen having to call selectAll manually — but a screen that 'unticked everything' loses that state on the next cart edit.
Backend Cart Model · models/cart.dart + cart_item.dart
Mirrors the Medusa Cart entity returned by /store/carts/{id}: id, region, currency, line items, totals (total/subtotal/itemTotal/shipping/discount/tax), email, shipping & billing addresses.
- Cart.fromJson maps the Medusa payload into a typed Cart.
- CartItem.fromJson maps a single line-item including thumbnail + variant info.
- CheckoutScreen consumes the Cart to render line items, totals and the address forms.
- currencyCode defaults to 'eur' when missing — Medusa always sends it, but the fallback protects against legacy fixtures.
- shippingAddress / billingAddress are nullable until the user fills them in; CheckoutScreen treats null as 'collect address first'.
- discountTotal and taxTotal are computed server-side; local recomputation drifts because of region-specific tax rules.
The backend cart is the source of truth for prices — never trust the local cart's totalPrice when displaying anything monetary post-checkout-start.
Data layer
Cart Service (Medusa Store API) · core/services/cart_service.dart
Dio-backed client for every cart-shaped endpoint Medusa exposes: create cart (physical vs provision), get/update cart, add/update line items, shipping options + methods, promo codes, payment collections (full and partial), and complete cart.
- createPhysicalCart / createProvisionCart POST /store/carts with metadata.type and an optional region_id; the metadata is what lets the UI keep marketplace and booking carts separate.
- addItemToCart / updateCartItem mutate line items (qty=0 deletes server-side).
- applyPromoCode / removePromoCode use POST … /promotions with the new full list (Medusa-style overwrite semantics).
- fetchShippingOptions + addShippingMethod attach a delivery option.
- fetchPaymentProviders + createPaymentCollection + createPaymentSession build the Stripe path.
- createPartialPaymentSession splits the amount between Stripe (deposit) and 'pp_system_default' (pay-on-site rest) for booking deposits.
- completeCart converts the cart to an order_set after a successful payment.
- create*Cart auto-retries without region_id on 400/422 — backend rejects unknown 'region_id' for some merchant configs; the retry lets the cart still be created.
- Booking-question helpers (getCartItemQuestions / answer / remove) treat 404 as 'no questions configured' rather than an error.
- completeCart accepts three possible shapes (order_set, data, {type:'order'}) because the Medusa response varies by version — the priority order matters.
- removePromoCode currently sends an empty promo_codes list rather than the documented DELETE endpoint; backend behavior has changed across Medusa V2 minors.
Every method opts in to authScope: 'customer' via RequestTrace; never call this with a seller-only token attached.
Local Cart Storage · core/services/local_storage.dart · getLocalCartItems / save / clear
Per-user SharedPreferences slice for the local cart. Keyed by customer id so that multiple accounts on the same device keep separate carts.
- getLocalCartItems(userId) reads the JSON string under the user-scoped key and runs LocalCartItem.decodeList.
- saveLocalCartItems(userId, list) serializes via encodeList and writes the JSON string.
- clearLocalCartItems(userId) removes the key entirely — used by CartController.clearCart and on logout.
- decodeList swallows JSON errors → corrupt storage resets to []. Acceptable because a busted local cart is a recoverable inconvenience.
- Keys are not migrated when a user changes id (server merges accounts) — the old cart becomes orphaned in storage.
- No size cap; a malicious or buggy add loop could grow the JSON beyond what SharedPreferences happily handles on Android.
Consider moving to flutter_secure_storage when persisting any cart that includes a backend-cart id post-checkout-start. Local storage contracts (SharedPreferences): • getLocalCartItems(userId) — read 'local_cart_<userId>' → List<LocalCartItem> (decodeList tolerates corrupt JSON → [] ) — screens: cart_screen.dart, product_details_screen.dart (badge count) • saveLocalCartItems(userId, items) — write encodeList(items) JSON string — screens: cart_screen.dart, product_details_screen.dart (after addToCart / updateQuantity / removeItem) • clearLocalCartItems(userId) — remove key — screens: cart_screen.dart (clearCart) + post-completeCart in checkout_screen.dart
Promo Code Handling · cart_service.applyPromoCode / removePromoCode
Promo codes are managed exclusively on the backend cart — there is no local-cart equivalent. Apply sends the new full code list (Medusa overwrites); remove sends an empty list to clear.
- User enters a promo code on CartScreen or CheckoutScreen.
- If no backend cart yet, the UI creates one first (createPhysicalCart / createProvisionCart).
- applyPromoCode posts {promo_codes: [code]} → response includes the updated discountTotal.
- removePromoCode posts {promo_codes: []} to clear.
- If a promo changes the total, updatePaymentCollectionAmount may need to resync the Stripe collection.
- Multiple stacking promo codes are technically possible — pass them all in promo_codes; UI today only supports one at a time.
- Removing a code that was never applied is a no-op (empty → empty) — UI must not show a 'removed' toast unless the previous state had a code.
- Discount drift vs payment-collection amount is a documented Medusa edge case — updatePaymentCollectionAmount exists specifically to recover.
Backend evolved between Medusa V1 (DELETE per-code) and V2 (POST full list). Keep removePromoCode pinned to the V2 semantic.
Booking Questions on Line Items · cart_service.getCartItemQuestions / answer / remove
When a seller has configured booking questions for a service, those questions attach to the cart line item. Answers (single-select, multi-select, free text, number, image upload) are written back to the line item before checkout proceeds.
- getCartItemQuestions(cartId, lineItemId) returns the question list.
- UI renders a typed input per question (depending on question.type).
- answerCartItemQuestion posts a body shaped by type (selected_option_ids / comment / number / image_file_id).
- removeCartItemAnswer clears a previous answer if the user changes their mind.
- 404 from getCartItemQuestions is treated as 'no questions for this item' — booking proceeds without blocking.
- image_upload answers require a previously-uploaded file id; the upload itself is handled by the file/upload service, not this endpoint.
- Questions are stored per-line-item, so duplicating the same service into the cart twice creates two independent question sets.
Cross-references the seller's booking_questions feature — the seller side defines them, the cart side records answers.
Dependency Injection layer
Cart Provider Wiring · NotifierProviders for the cart feature
Two NotifierProviders are exported: cartControllerProvider (the local cart list) and cartSelectionProvider (the selected variantIds). The backend CartService is plain — instantiated where needed; not provider-wrapped today.
- cartControllerProvider builds with currentCustomerIdProvider as a watched dependency.
- cartSelectionProvider builds with cartControllerProvider as a watched dependency.
- Consumers (CartScreen, CheckoutScreen, AddToCart buttons) ref.watch / ref.read these providers directly.
- CartService is constructed inline in CheckoutController and other consumers — no provider gate.
- Adding a provider for CartService would let tests inject a mock — currently not done.
- Provider disposal is implicit — they live for the app lifetime since nothing else holds a parent scope.
currentCustomerIdProvider lives in profile/personal_info_provider.dart — see the profile feature for its definition.
Cart Route · core/routing/app_router.dart · /cart
Single GoRoute pointing /cart at CartScreen, declared inside the ShellRoute so the nav bar stays visible. Not gated by a custom guard — the global auth redirect already blocks guests from logged-in routes.
- context.go(AppRoute.cart.path) from a home tile or top-bar icon.
- ShellRoute builder wraps CartScreen with AppShellScaffold.
- Back behavior delegates to context.pop() which lands on the previous shell route.
- Deep-link to /cart while not logged in → redirect bounces to /login because the auth guard fires before the route builder.
- Adding a per-tab badge for cart count would consume cartControllerProvider in app_shell_scaffold.
CartScreen is intentionally not a bottom-nav destination — it's reached from home tiles and product details, not from the persistent nav.
Checkout & Payment
End-to-end checkout: builds a server cart from the selected local items, collects address + shipping + answers, runs Stripe PaymentSheet, completes the cart and clears the local items. Handles promo codes and booking deposits via partial payment sessions.
Riverpod · Medusa Store API · flutter_stripe PaymentSheet
API surface
| Method | Endpoint | Purpose | Auth | Status |
|---|---|---|---|---|
| GET | /store/payment-providers?region_id=:id | Resolve the payment providers wired for the cart's region. | — | no status |
| POST | /store/payment-collections | Open a payment collection for the cart. | — | no status |
| POST | /store/payment-collections/:id | Resync the collection amount after cart mutation. | — | no status |
| POST | /store/payment-collections/:id/payment-sessions | Initialize a payment session for a single provider; returns the Stripe client_secret. | — | no status |
| POST | /store/payment-collections/:id/partial/payment-session | Initialize multi-provider partial payments for a booking deposit (deposit + remainder). | — | no status |
| POST | /store/carts/:cartId/set-order | Finalize the cart and convert it into a paid order. | — | no status |
Presentation layer
Checkout Screen · views/checkout_screen.dart
Wizard-like ConsumerStatefulWidget that consumes checkoutControllerProvider and composes the address, shipping, payment-method, booking-questions and policy widgets into a scrollable column. The 'Pay' button calls confirmStripePayment.
- On first build, calls initCheckout with the variantIds passed from CartScreen.
- Renders CheckoutProgressBar at the top reflecting the current step.
- CheckoutAddressSection drives updateShippingAddress on submit.
- CheckoutShippingOptions calls setShippingOption.
- CheckoutPaymentMethods calls setPaymentProvider.
- CheckoutBookingQuestions calls setQuestionAnswer per field.
- Pay button → confirmStripePayment(context, onSuccess) → on success closes to /orders.
- CheckoutExitDialog confirms before back-navigation when state.checkoutCartId != null (data loss warning).
- If state.error is non-null, the screen renders an inline banner with retry buttons.
- Re-entry from order history or notifications must NOT reuse stale state — the screen relies on Riverpod auto-disposing the notifier when removed from the tree (which it currently does NOT — see provider note).
checkoutControllerProvider is a NotifierProvider (not autoDispose) — state survives screen pops. If you change this, the resume-after-back flow needs to be re-tested end-to-end.
Checkout Step Widgets · views/widgets/* (address / shipping / payment / questions / policy)
Five composable sections rendered by CheckoutScreen: address form, shipping option picker, payment method picker, booking question form, and the read-only booking policy block.
- checkout_address_section.dart: form + submit → updateShippingAddress(Address).
- checkout_shipping_options.dart: lists state.availableShippingOptions → setShippingOption.
- checkout_payment_methods.dart: lists state.availablePaymentProviders → setPaymentProvider.
- checkout_booking_questions.dart: renders per-question UI by q['type'] → setQuestionAnswer.
- checkout_booking_policy.dart: read-only display of bookingPolicy from ProvisionService.
- Booking-question types: 'single_select' / 'multi_select' / 'yes_no' (use selected_option_ids), 'free_text' (comment), 'number' (number), 'image_upload' (image_file_id).
- Required-question validation is deferred to confirmStripePayment — the widgets themselves do not block submission.
- Shipping options can come back empty when address is missing or unsupported — UI must guide the user back to address.
Each widget is dumb (props in, callback out) — state lives in CheckoutController only, no per-widget Riverpod providers.
Payment Success Dialog · views/widgets/payment_success_dialog.dart
Modal shown the moment PaymentSheet returns success, while completeCart is still in flight. Displays the (still-cart-id-shaped) order id and blocks user input until the order is finalized.
- showDialog(barrierDismissible: false) is awaited via dialogFuture before the onSuccess callback fires.
- completeCart happens INSIDE the dialog's visible window so the user perceives instant success.
- Calendar provider.refresh is triggered to update any visible booking grids.
- If completeCart fails AFTER PaymentSheet success, money is captured but order is not finalized — dialog stays visible but onSuccess never fires; the snackbar 'Error: $e' surfaces underneath.
- Cart id is shown as 'order id' to the user — the actual order id is only available after completeCart, but UX prefers an immediate ack.
The dialog is dismissed by the controller's onSuccess callback, not by user tap — pulling barrierDismissible to true would break the await flow.
Domain layer
CheckoutState · models/checkout_state.dart
Immutable snapshot of the entire checkout flow: backend cart id + Cart, Stripe clientSecret, selected shipping option / payment provider, promo code, available providers, booking questions + answers, plus the global isLoading / error flags.
- Constructed empty in CheckoutController.build().
- copyWith re-issues every field except error which is intentionally pass-through (so passing error: null clears it).
- Almost every controller method does state.copyWith(isLoading: true) on entry and ...(isLoading: false) on exit.
- removePromoCode rebuilds the state via the full constructor (not copyWith) specifically so it can null out promoCode — copyWith's ?? would keep the old code.
- questionAnswers and bookingQuestions default to const [] / const {} so the screen can render before initCheckout returns.
- availableShippingOptions and availablePaymentProviders are List<dynamic> — typed payment_provider.dart and shipping_option.dart exist but the controller still passes the raw maps through.
Booking-questions live here rather than in a dedicated notifier because validating them must happen at the same instant as confirming payment — splitting state across notifiers would create a race.
CheckoutController · controllers/checkout_controller.dart · Notifier<CheckoutState>
Drives the entire checkout pipeline. Holds a CartService + ProvisionService directly (no DI). Each step (init, address, shipping, payment) mutates CheckoutState via copyWith and exposes a 'shallow-cart safeguard' that refetches the full cart if Medusa returns a stripped response.
- initCheckout: createPhysicalCart → addItemToCart × N → getCart → savePendingCheckout → fetchPaymentProviders + fetchShippingOptions → ProvisionService.getProvisionQuestions/Policy.
- updateShippingAddress: updateCart with shipping_address + email, then fetchShippingOptions for that address.
- setShippingOption / setPaymentProvider: store choice in state (paymentProvider does NOT call backend).
- applyPromoCode / removePromoCode: deferred to CartService; re-fetch full cart on shallow response.
- createPaymentSession: createPaymentCollection → updatePaymentCollectionAmount if the cart total drifted → createPaymentSession(providerId) → pull clientSecret out of payment_sessions list.
- confirmStripePayment: validate required questions → updateCart with booking_answers → init+present PaymentSheet → completeCart → addOrderToHistory → clear local cart entries → clearPendingCheckout.
- Shallow-cart safeguard repeats after every mutating call (updateCart, addShippingMethod, applyPromoCode, removePromoCode) because Medusa sometimes returns the cart without items inlined; we detect by 'previous had items, response has none' and refetch.
- Payment-collection amount drift is reconciled by comparing the existing collection amount with (cart.total * 100) cents and PATCH-ing if needed.
- Booking-question validation runs IN confirmStripePayment, not earlier — required because answers can change up until the moment the user taps Pay.
- StripeException.FailureCode.Canceled is treated as a soft outcome (snack 'Payment Cancelled') rather than an error toast.
- PaymentSheet flow is wrapped in try/catch with a Stripe-specific branch — non-Stripe errors fall through to a generic 'Error: $e' snack.
- TODO in updateShippingAddress: email is hard-coded to 'user@example.com'; this currently breaks email receipts for production users.
Side-effect-heavy method (confirmStripePayment) takes BuildContext and a callback — keep it untestable in isolation; tests are integration-only for now.
Address · models/address.dart
Mirrors Medusa's shipping/billing address shape: first_name, last_name, address_1/2, city, postal_code, province, country_code, phone and a metadata bag.
- Address.fromJson maps the snake-case Medusa payload into camelCase fields.
- toJson re-emits snake-case for updateCart's shipping_address body.
- Empty-string defaults for missing required fields ensure fromJson never throws on partial backend responses.
- metadata is opaque — used by the backend to flag 'address pre-filled from profile' vs 'manually entered', not by the client.
- countryCode optional, but Medusa shipping options key off it — missing it usually returns an empty shipping_options list.
Used by both Cart.shippingAddress / billingAddress and the address picker widget in CheckoutScreen.
Data layer
Cart Payment Endpoints · core/services/cart_service.dart (payment + complete)
Subset of CartService used by checkout: payment-providers, payment-collection, full / partial payment-session, completeCart. The booking-deposit path uses createPartialPaymentSession to split between Stripe and pay-on-site.
- fetchPaymentProviders(regionId) → GET /store/payment-providers.
- createPaymentCollection(cartId) → POST /store/payment-collections.
- updatePaymentCollectionAmount(id, amount) → resync when discounts change.
- createPaymentSession(collectionId, providerId) → full-amount session, returns payment_sessions[].data.client_secret.
- createPartialPaymentSession(collectionId, deposit, rest) → splits providers (pp_partial_stripe-connect, pp_system_default).
- completeCart(cartId) → POST /store/carts/{id}/set-order; returns the order_set wrapping the resulting orders.
- completeCart accepts three response shapes (order_set / data / {type:'order'}) — Medusa versioning, do not reduce.
- createPartialPaymentSession amounts are double-truncated to 2dp before send to avoid Stripe rejecting a floating-point mismatch.
- Provider IDs are stringly typed — magic strings 'pp_system_default' and 'pp_partial_stripe-connect' must match backend config exactly.
These endpoints live in CartService — see the cart feature for the broader API surface; this node names the slice that checkout owns.
Stripe PaymentSheet · package:flutter_stripe · Stripe.instance
Direct integration with flutter_stripe's PaymentSheet. CheckoutController hands a clientSecret to initPaymentSheet and presentPaymentSheet handles every UI/UX detail (card entry, Apple Pay, 3DS).
- Stripe.publishableKey is set once in main.dart from STRIPE_PUBLISHABLE_KEY (.env).
- createPaymentSession returns a clientSecret stored in CheckoutState.
- initPaymentSheet receives the clientSecret + merchantDisplayName.
- presentPaymentSheet awaits user interaction; success → continue, cancel → StripeException(Canceled).
- Style is fixed to ThemeMode.light — even when the app is in dark mode the sheet stays light (Stripe limitation we accepted).
- Cancellation surfaces as a SnackBar, not a state.error — the user can simply retap Pay.
- Re-presenting the sheet after a network error requires a fresh clientSecret — re-call createPaymentSession.
flutter_stripe is imported with `hide Address` so its `Address` type doesn't collide with the local Address model — leave the import as-is. Native SDK contracts (no HTTP; embedded native plugin): • Stripe.instance.initPaymentSheet(SetupPaymentSheetParameters { paymentIntentClientSecret, merchantDisplayName, style: ThemeMode.light }) → void — screen: lib/src/features/shared/checkout/views/checkout_screen.dart • Stripe.instance.presentPaymentSheet() → success | StripeException(FailureCode.Canceled | …) — screen: lib/src/features/shared/checkout/views/checkout_screen.dart • Pre-step: read clientSecret from CheckoutState (populated by /store/payment-collections/{id}/payment-sessions response).
Pending Checkout + Order History · core/services/local_storage.dart · pending checkout + order history
SharedPreferences slice for recovery: savePendingCheckout (after backend cart creation), clearPendingCheckout (on success), addOrderToHistory (after completeCart). Lets the app reopen a half-finished checkout when relaunched mid-payment.
- After initCheckout: savePendingCheckout(cartId, selectedVariantIds).
- After successful completeCart: addOrderToHistory(cartId) and clearPendingCheckout.
- Order history is read by the orders feature to render the user's purchase list independent of backend availability.
- If the app dies between createPaymentSession and presentPaymentSheet, the saved pending-checkout lets us resume on next launch — but only if the backend cart hasn't been cleaned up server-side.
- addOrderToHistory only stores the cart/order id; full order data is re-fetched via OrderService on demand.
- Multiple pending checkouts overwrite each other — the implementation is single-slot.
Multi-cart resume is not supported by design — assumption is the user finishes (or abandons) one checkout at a time. Local storage contracts (SharedPreferences — no HTTP): • savePendingCheckout({ cartId, selectedVariantIds }) — write keys 'pending_checkout_cart_id' + 'pending_checkout_variant_ids' — screen: lib/src/features/shared/checkout/views/checkout_screen.dart (after initCheckout creates the backend cart) • clearPendingCheckout() — remove keys — screen: checkout_screen.dart (post-completeCart success) • addOrderToHistory(cartOrOrderId) — append to 'order_history' list — screen: checkout_screen.dart (after completeCart) — consumed by lib/src/features/shared/orders/views/orders_screen.dart for offline fallback
Dependency Injection layer
Checkout Provider · checkoutControllerProvider · NotifierProvider
Single NotifierProvider for the entire checkout. No autoDispose, so state survives screen pops and lets the resume-from-pending-checkout flow work. CartService and ProvisionService are instantiated inside the notifier — not provider-wrapped.
- CheckoutScreen ref.watch(checkoutControllerProvider) on every state change.
- CheckoutController constructs CartService() and ProvisionService() in field initializers.
- Other consumers (orders feature) ref.read this provider only after a completed checkout to read state.checkoutCart.
- Lack of autoDispose means a stale CheckoutState lingers if the user starts a checkout, leaves the app, and starts a new flow days later — the controller does NOT auto-reset.
- Inline service construction is fine for prod but means tests can't inject mocks without overrideWith.
Switching to AutoDisposeNotifierProvider would simplify reasoning but break the resume-after-back flow — make the swap deliberate.
Orders
Dual-role order listing and detail: customers see /store/orders, sellers see /vendor/orders with embedded customer + split-payment data. Includes PDF receipt generation and a seller cancel path that triggers a full refund.
Riverpod · Medusa Store + Vendor API · pdf
API surface
| Method | Endpoint | Purpose | Auth | Status |
|---|---|---|---|---|
| GET | /store/orders | Customer order list (newest-first). | — | no status |
| GET | /store/orders/:orderId | Customer order detail. | — | no status |
| GET | /vendor/orders?fields=*customer,+payment_status,*split_order_payment&status=:status | Seller order list with embedded customer + split-payment info. | — | no status |
| GET | /vendor/orders/:orderId?fields=*customer,+payment_status,*split_order_payment | Seller order detail with customer + split-payment. | — | no status |
| POST | /vendor/orders/:orderId/cancel | Seller-initiated order cancellation and refund. | — | no status |
Presentation layer
Orders Screen · views/orders_screen.dart
Single screen with role-aware tabs. Customers see All / Pending / Fulfilled / Delivered. Sellers see All / Pending / Canceled. The active provider (customer vs seller) is selected by userRoleProvider.
- _OrdersScreenState builds a TabController with 4 tabs.
- build watches userRoleProvider and the matching list provider.
- _filterOrders applies a per-tab status filter against the list returned by the provider.
- Pull-to-refresh calls the matching controller's refreshOrders.
- isSeller branch uses the seller filter set (pending / canceled) — customer branch uses fulfillment buckets (pending / shipped / delivered).
- Empty-state messaging differs per role — sellers see 'no pending orders', customers see 'no purchases yet'.
- TabController length is hard-coded to 4 — adding a 5th tab requires changing the ctor.
Tab order is fixed in code — the labels come from S.current.* localizations, so changing copy is a single ARB change.
Order Detail Screen · views/order_detail_screen.dart
Shows a single Order. For customers: items, tracking timeline, shipping address, totals, 'view receipt' CTA. For sellers: also customer block, split-payment status, Cancel button with confirmation dialog.
- Reads orderId from the GoRouter path param.
- Consumes orderDetailProvider(orderId).
- Customer flow: TrackingTimeline shows fulfillmentStatus progression; Receipt button pushes ReceiptScreen.
- Seller flow: Cancel button → confirmation dialog → cancelSellerOrderProvider(orderId).future → re-fetch detail.
- Error / loading states are rendered via AsyncValue.when().
- Cancelled orders disable the Cancel button and surface 'Refunded €X' computed from splitOrderPayment.refundedAmount.
- Tracking timeline interprets fulfillment_status into steps: pending → fulfilled → shipped → delivered.
- Seller has no 'view receipt' (no CTA implemented yet) — that's a customer-only flow.
Long screen (~1k lines) with inline subwidgets — pulling them out into widgets/* would simplify cross-role testing.
Order Card + Status Badge · views/widgets/order_card.dart + order_status_badge.dart
List-row widget rendering one order. Customer variant emphasises seller info + tracking; seller variant emphasises customer info + split-payment status badge.
- OrderCard receives an Order and a tap callback (push detail).
- OrderStatusBadge color-maps Medusa statuses (pending → amber, captured → green, refunded → grey, canceled → red).
- Tapping the card calls context.pushNamed(AppRoute.orderDetail, orderId).
- Status badge falls back to 'unknown' grey for any string not in the map — protects against new server statuses.
- Localization is per-status via S.current.statusXxx; missing keys render the raw string.
Card width assumes ~390 logical px phone — tablets need a Wrap container at the screen level to avoid stretched rows.
Domain layer
Order Model + Sub-entities · models/order.dart · Order, OrderItem, OrderAddress, OrderCustomer, SplitOrderPayment
Unified Order shape that absorbs both the Medusa /store/orders response and the seller /vendor/orders response. Customer-facing fields (sellerName/Phone/Photo, startTime/endTime, shipping methods) sit alongside seller-facing fields (customer block, splitOrderPayment).
- Order.fromJson reads the Medusa payload and conditionally populates customer + splitOrderPayment when those keys exist (seller response).
- OrderItem nests variant info needed by OrderCard.
- OrderAddress carries shipping + billing addresses.
- SplitOrderPayment surfaces status / authorized / captured / refunded for seller-side UIs.
- displayIdFormatted formats the human-readable id used in logs and the receipt.
- fromJson is intentionally lenient — parse errors on a single order are caught upstream (in OrderService) and that order is dropped from the list rather than aborting the whole load.
- Seller payload includes product_type='provision' on items which the UI can use to differentiate physical vs booking orders.
- Some customer-side fields (seller info, startTime/endTime) are derived from order metadata.slot — null is normal for non-booking orders.
The CLAUDE.md inside this feature folder documents the seller-orders rollout plan — keep new fields in fromJson tolerant of both response shapes.
Customer Order Controller · controllers/order_controller.dart · AsyncNotifier<List<Order>>
AsyncNotifier that loads the customer's orders on build and exposes refreshOrders. State is AsyncValue<List<Order>> so the screen can render loading / error / data without manual flags.
- build() returns OrderService.getOrders() — Riverpod caches the result.
- refreshOrders sets state to AsyncValue.loading, then re-runs getOrders inside AsyncValue.guard for typed error capture.
- OrdersScreen ref.watches the provider and re-renders on every state transition.
- Network failure on build surfaces as AsyncValue.error; the screen shows a retry button that calls refreshOrders.
- List is reversed by OrderService (newest first) — the controller does not re-sort.
- No pagination yet — getOrders returns whatever the backend default limit is (50).
Use ref.invalidate(orderControllerProvider) from completing checkout to force a refresh — the controller is not auto-invalidated.
Seller Order Controller · SellerOrderController + cancelSellerOrderProvider
Mirror of the customer controller but hitting /vendor/orders with the seller token. cancelSellerOrderProvider (FutureProvider.family<Order, String>) cancels an order then ref.invalidates the seller list to force a refresh.
- build() returns OrderService.getSellerOrders() (no status filter by default).
- refreshOrders is the same loading→guard pattern as the customer controller.
- cancelSellerOrderProvider(orderId) → OrderService.cancelSellerOrder + ref.invalidate(sellerOrderControllerProvider).
- Cancellation is always allowed server-side (no policy gate) — UI must own the confirmation dialog.
- After cancel, splitOrderPayment.status flips to 'refunded' — the screen should re-fetch the detail to reflect this.
- Status query param is supported (getSellerOrders({status: 'pending'})) but the controller doesn't expose it yet — UI filters client-side.
Seller endpoints are documented in lib/src/features/shared/orders/CLAUDE.md including the response shapes — keep that doc up to date when you add filters or actions.
Order Detail Provider · orderDetailProvider · FutureProvider.family<Order, String>
Single-order fetcher that watches userRoleProvider and routes to /vendor/orders/{id} for sellers, /store/orders/{id} for customers. Same family pattern is consumed by both customer and seller detail screens.
- ref.watch(userRoleProvider) → isSeller flag.
- OrderService.getOrder(orderId, isSeller: isSeller) hits the right endpoint with the right field selection.
- Order goes into the FutureProvider.family cache keyed by orderId.
- Role-switch in-session invalidates the cache for this family key — the next read refetches via the right endpoint.
- Seller endpoint adds the query fields='*customer,+payment_status,*split_order_payment' to inline data the seller UI needs.
Family providers leak entries unless invalidated — call ref.invalidate(orderDetailProvider(orderId)) after mutations.
Data layer
Order Service · core/services/order_service.dart
Four endpoints: getOrders (customer list), getOrder (single, role-aware), getSellerOrders (vendor list with field selection), cancelSellerOrder (vendor POST cancel).
- getOrders → GET /store/orders with authScope:'customer'.
- getOrder routes path by isSeller flag and attaches the seller field-selection query.
- getSellerOrders → GET /vendor/orders?fields=… + optional status filter.
- cancelSellerOrder → POST /vendor/orders/{id}/cancel.
- All list responses parse orders one at a time and skip-on-error to avoid one bad row killing the whole list.
- Per-order parse failures are debugPrinted and the row is dropped — they never crash the controller.
- Reversed list ordering is applied here (newest first) — controllers and screens rely on this invariant.
- Seller endpoints rely on the DioHelper path heuristic (/vendor/* → seller token) to attach the right Authorization header.
Each call carries a RequestTrace with feature='orders/customer' or 'orders/seller' — useful when grep-debugging real network traces.
PDF Receipt Service · services/pdf_receipt_service.dart
Generates a PDF receipt from an Order using the `pdf` package — order summary, line items, totals, addresses, optional seller block. Saves to temp + offers share/print via the platform sheet.
- Service is instantiated per call (no provider).
- buildPdf(order) composes a multi-page document with pw.Document().
- savePdf writes to a temp file via path_provider; sharePdf forwards to Share.shareXFiles.
- Long item lists wrap across pages — pageBreak is automatic via the pdf package, no manual splitting.
- RTL languages render through the default font — Arabic shaping is approximate, fine for printable receipts but not for layout-perfect typography.
- Service does not embed images today — seller photo URLs render as text-only fields.
Receipt regeneration must be idempotent — sharing the same order twice should produce byte-identical PDFs (modulo timestamps). No HTTP contract — operates purely on the in-memory Order entity. File output contracts: • savePdf(order) → File at <appCache>/receipt_<orderId>.pdf — screen: lib/src/features/shared/orders/views/receipt_screen.dart • sharePdf(file) → Share.shareXFiles([file]) (platform share sheet) — screen: lib/src/features/shared/orders/views/receipt_screen.dart
Dependency Injection layer
Orders Routes · core/routing/app_router.dart · /orders + /orders/:orderId
Two GoRoutes inside the ShellRoute: /orders → OrdersScreen, /orders/:orderId → OrderDetailScreen. Both are role-aware at render time, not at routing time — the auth guard only checks isLoggedIn.
- Home grid tile 'Panier' / 'Orders' navigates to /orders.
- OrderCard taps push /orders/:orderId with the path param.
- Detail screen reads pathParameters['orderId'] and feeds orderDetailProvider.
- Deep-linking from a notification (FCM 'new order') jumps directly to /orders/:orderId — make sure orderDetailProvider can recover from a cold-start cache miss.
- No nested ShellRoute — the bottom nav stays visible on detail.
Receipt screen is pushed (not routed) from order detail — keep it out of the GoRouter table to avoid making it deep-linkable.
Marketplace (Physical Products)
Paginated product catalog with combined server + client-side filtering: categories, tags, variant option values (color/size), title search and four sort orders. Backs the home tile 'Marketplace' for clients.
Riverpod · Medusa Store API · Paginated lists
API surface
| Method | Endpoint | Purpose | Auth | Status |
|---|---|---|---|---|
| GET | /store/physical-products | Paginated catalog of physical products with combined server-side filter, sort and search. | — | no status |
| GET | /store/physical-products/:productId?fields=*variants.calculated_price | Fetch a single physical product (fallback when route extra is missing). | — | no status |
Presentation layer
Marketplace Home Screen · views/marketplace_home_screen.dart
Composite scrollable screen made of a banner carousel, category strip, trending deals, summer-sale tile, special offers, and the main product grid/list. Watches marketplaceControllerProvider for the list state.
- Top bar with search + cart + notification triggers.
- MarketplaceCategoryList chips toggle category filters.
- MarketplaceFilterBar exposes Filter / Sort / Grid toggles via bottom sheets.
- MarketplaceProductList renders the result and triggers loadMore on near-bottom scroll.
- warningMessage banner shows after auto-recovery and is dismissible via clearWarning.
- Pagination trigger fires when scroll position passes ~80% — tweak in the list widget, not the controller.
- Hero widgets (banners, summer sale) read from local sample data; they are not yet backed by a CMS service.
- Grid vs list toggle persists for the controller lifetime (not across kills).
Long screen (~540 lines) — keep new sections as standalone widgets in widgets/ to avoid the file ballooning further.
Product List Widget · widgets/marketplace_product_list.dart
Switches between grid and list layout based on state.isGridView. Each tile is tappable (pushes /product-details/:id), shows the calculated price, and renders a favorite toggle (controller.toggleFavorite).
- ListView/GridView builds from state.products.
- Near-bottom scroll → controller.loadMore.
- Heart icon tap → controller.toggleFavorite(productId).
- Tile tap → context.push(AppRoute.productDetails, extra: product).
- Empty state renders an illustration + 'Reset filters' CTA when filters are active.
- Grid uses crossAxisCount=2 fixed — tablets need a media-query override.
- Skeleton loading rows are shown for state.isLoading while products.isNotEmpty for smooth append.
Tap routes to AppRoute.productDetails passing the Product via state.extra — see app_router.dart for the typed cast.
Filter / Sort Bar · widgets/marketplace_filter_bar.dart
Horizontal bar with three primary chips: Filter (opens FilterBottomSheet), Sort (SortByBottomSheet), and a Grid/List toggle. Selected filter count is displayed as a badge on the Filter chip.
- Tap Filter → showModalBottomSheet(FilterBottomSheet) → applyCompositeFilters.
- Tap Sort → showModalBottomSheet(SortByBottomSheet) → setSortOrder.
- Tap Grid/List → controller.toggleViewType.
- Active filters are reflected as small chip indicators next to the bar.
- Filter badge count is computed from state.categoryIds.length + state.tagIds.length + state.variantOptionValues.length — order changes if you re-order the filter dimensions.
- Sort by 'price_asc'/'price_desc' is client-side; 'created_at' variants are server-side — bar doesn't distinguish.
Consider centralizing filter-count math in the controller as a derived getter.
Filter / Sort / Category / Location Bottom Sheets · widgets/bottom_sheets/*
Four bottom sheets driving filter and sort interactions. Filter sheet renders the FilterSection list, Sort sheet picks the sort key, Category sheet is a quick category picker, Location sheet (currently mocked) picks the delivery region.
- FilterBottomSheet builds from state.availableFilters and emits selected IDs.
- SortByBottomSheet lists 4-5 sort options with the current one highlighted.
- CategoryBottomSheet is a vertical category list used outside the filter sheet.
- LocationBottomSheet is currently a placeholder; tied to a future region-aware fetch.
- Filter sheet reads available filters from the controller — sheet-only state is local until 'Apply' is tapped.
- Sort sheet calls setSortOrder which forks between client- and server-side sorting.
- Location sheet does not yet wire into MarketplaceService — backend doesn't accept a region filter in this endpoint yet.
Sheet 'Reset' buttons map onto controller.clearAllFilters — they should NOT manually rebuild state.
Domain layer
Product Model · models/product.dart · Product + Variant + Option + Category
Mirrors Medusa's physical product shape: id, title, description, thumbnail, images, options (Color/Size/etc.), variants (with calculated_price), categories, tags, plus a client-only isFavorite flag for the heart toggle.
- Product.fromJson parses the response from /store/physical-products.
- Variant.calculatedPrice carries the per-region price the UI displays.
- copyWith(isFavorite) is used by toggleFavorite without mutating the original.
- isFavorite is local-only — it doesn't round-trip to the backend in this feature (wishlist persistence lives in another service).
- calculated_price requires the `fields=*variants.calculated_price` query param — without it, variants render at 0.
- options & variants are independent: options describe the schema (Color/Size), variants are the realized SKU combinations.
The same Product class is reused by the provision marketplace — booking services are modeled as 'products' with metadata.type='provision'.
Marketplace Controller + State · controllers/marketplace_controller.dart · Notifier<ProductListState>
Notifier owning the entire paged + filtered list. ProductListState carries loading flags, products, pagination cursor (offset, hasMore), every filter dimension, and the available-filter set computed from page 0.
- build() schedules a Future.microtask(refresh) so the initial fetch fires on first watch.
- _fetchProducts respects offset and limit=20; the response is concatenated with previous pages.
- Sort orders 'price_asc' / 'price_desc' are applied client-side; everything else is server-side (passed as `order=` param).
- Available filters (Category, Colors, Size) are extracted from page 0 results via _extractFilters and cached.
- toggleCategory / toggleTag / toggleVariantOption flip an item in the corresponding list, then refresh.
- Medusa's variants[options][value] only accepts a single value — the controller sends the first selected option to the API and filters the rest client-side.
- Filter-error auto-recovery: if a filtered fetch throws and any filter is active, all filters reset, warningMessage is set, and refresh fires unfiltered.
- copyWith does not allow clearing warningMessage; clearWarning rebuilds the state explicitly with warningMessage: null.
- Local price sort is applied on top of paged results — the order across page boundaries is unstable when more items load.
- toggleVariantOption can't enforce per-group single-select (Color vs Size) without group knowledge — the UI must pre-process to send 'one Color + one Size'.
The 100+ lines of inline comments inside ProductListState.copyWith document a real frustration with warningMessage clearing — read those before refactoring.
Filter Models · models/filter_data.dart + filter_sample_data.dart
FilterSection (label + options[]) and FilterOption (label, id, isSelected). filter_sample_data.dart seeds the default sections (Category / Colors / Size / Brand etc.) that _extractFilters then refines from the live product list.
- filterSections seeds the empty state shown before any products load.
- _extractFilters merges live category/color/size values from page 0 into the seed sections.
- Bottom sheets render the FilterSection list and emit selected IDs back to the controller.
- Default 'All' Category option (isSelected: true, id: '') is prepended only when categoryMap is non-empty.
- Colors and Size are detected by case-insensitive title contains — fragile if a seller introduces a different option naming.
FilterOption.id is the only payload sent to the server — labels are presentation-only and must not be trusted as identifiers.
Data layer
Marketplace Service · core/services/marketplace_service.dart
Two endpoints: paginated/filtered list and single-product fetch. Both hit /store/physical-products with `fields=*variants.calculated_price` so the UI gets per-region pricing in the same response.
- getProducts(...filters) → GET /store/physical-products with the dynamic query map.
- Empty / null filters are omitted via the spread + if-condition pattern.
- getProductById(id) → GET /store/physical-products/:id; throws 'Product not found' for null data.
- Network errors are unwrapped (response.data['message']) when possible, then re-thrown as Exception for the controller to surface.
- Each filter list field uses Dio's auto-encoding (?category_id=X&category_id=Y) — relies on Dio's default ListFormat.
- title[$like] is escaped with a literal '$' in the query key — Medusa accepts that as the contains operator.
Pagination is via offset+limit; no cursor / nextLink — the controller increments offset by the actual response length, not by limit, so a partial last page still terminates cleanly.
Dependency Injection layer
Marketplace Provider Wiring · marketplaceServiceProvider + marketplaceControllerProvider
marketplaceServiceProvider provides a singleton MarketplaceService; marketplaceControllerProvider provides the Notifier. ProductListState is the consumed value.
- Controller.build() does ref.watch(marketplaceServiceProvider) — if you override the service provider in tests, the controller picks it up.
- No autoDispose — state survives screen pops so the user returns to their scroll position + filters.
- Switching to autoDispose would lose pagination on a back-and-forth — current behavior is intentional.
- Service is reconstructed on every provider rebuild because the constructor is a plain `MarketplaceService()` — harmless since Dio is a singleton.
Tests that swap the service must do so via ProviderScope override; instantiating MarketplaceController directly bypasses Riverpod and is brittle.
Marketplace Routes · core/routing/app_router.dart · /marketPlace + /product/:id
/marketPlace points at MarketplaceHomeScreen inside the ShellRoute. Product detail uses AppRoute.productDetails and reads `state.extra as Product` to avoid a refetch on tile-tap.
- Home grid tile 'Marketplace' (client) → context.push(/marketPlace).
- MarketplaceProductList tile tap → context.push(/product-details, extra: product).
- ProductDetailScreen reads the Product directly from extra — does not call getProductById on entry.
- Deep-linking to /product-details/:id without extra is unsupported today — the route builder casts state.extra to Product unconditionally.
- The marketPlace path uses camel-case in AppRoute — keep it stable; downstream URLs depend on it.
If product details ever needs to be a real URL (sharable link), refactor to read pathParameters['id'] and call getProductById on entry.
Notifications & Push
End-to-end push pipeline: FCM token sync to backend (per-role), foreground-message local notification fallback, and an in-app notification list that merges customer + seller streams from /social/fcm-notifications.
Riverpod · Firebase Messaging · flutter_local_notifications · Medusa /social/fcm-notifications
API surface
| Method | Endpoint | Purpose | Auth | Status |
|---|---|---|---|---|
| GET | /social/fcm-notifications?limit=50&offset=0 | Fetch a page of in-app notifications for a specific token (called per role when both customer + seller tokens exist). | — | no status |
| POST | /fcm/token | Register the device's FCM token for a given auth scope so the backend can target push to this device + role. | — | no status |
| POST | /social/fcm-notifications/toggle-read | Flip the read state of a single notification — fired optimistically after the UI updates. | — | no status |
Presentation layer
Notifications Screen · views/notifications_screen.dart
Lists all notifications with type-coded icons and colors, an unread-count chip in the header, a 'Mark all as read' action, and per-row tap to navigate or open detail.
- Watches notificationsControllerProvider for state.
- Pull-to-refresh calls refresh.
- Row tap fires markAsRead and navigates based on type / template (orders → /orders/:id; messages → /messages).
- 'Mark all read' calls markAllAsRead.
- Empty state renders illustration + 'No notifications yet'.
- Type colors come from the model extension — keep palette in sync with theming.
- Long-press on a row reveals a dismiss action that calls deleteNotification (local-only).
The unread badge consumers (e.g. home bell icon) should ref.watch the state.unreadCount derived getter, not the full list.
Domain layer
NotificationItem + Type · models/notification_item.dart
Single notification entity: id, title, body, NotificationType enum (order / post / promotion / system / message), template string, createdAt, isRead, payload bag, and the authToken under which it was fetched (so mark-as-read can hit the right token).
- NotificationItem.fromJson reads title from data.title or falls back to template string.
- _typeFromTemplate maps backend template strings to the local NotificationType enum.
- NotificationTypeUI extension provides per-type icon, color, lightColor, darkColor and French label.
- NotificationsResponse.fromJson wraps the paginated list with count/limit/offset.
- Unknown template strings fall back to NotificationType.system (grey, info icon) — defensive against new backend templates.
- authToken is propagated through copyWith — without it, markAsRead can't tell which role's endpoint to call.
- createdAt defaults to DateTime.now() when missing — only affects sort order, never delivered server-side.
The French labels are hard-coded in the extension — should move to ARB if multi-language coverage is added.
Notifications Controller · controllers/notifications_controller.dart · Notifier<NotificationsState>
Notifier that fetches both customer and seller notification streams in parallel, merges them by id, preserves prior read state, sorts newest-first, and exposes markAsRead / markAllAsRead / deleteNotification.
- build() schedules Future.microtask(refresh) — initial fetch on first watch.
- refresh reads both tokens from AuthStorageService and fetches in parallel via Future.wait.
- Per-token fetches use a raw Dio (not DioHelper) so each call carries its own Authorization explicitly.
- De-dup by id with putIfAbsent → preserves read flags from previous state → newest-first sort.
- markAsRead writes optimistic state, then fires /social/fcm-notifications/toggle-read with the original authToken.
- If only one role is present, the other future is omitted — the list still works.
- If a per-token fetch throws, the other is preserved — failures don't cascade.
- Preserving read status from existing state across refresh is intentional — the server might not yet reflect a just-tapped 'read' state.
- deleteNotification is local-only — no backend delete endpoint today, so swiping just hides until next refresh.
- markAllAsRead fires one toggle-read POST per unread notification — could be batched but isn't yet.
Using a raw Dio bypasses DioHelper's path heuristic — necessary because both /social paths would otherwise resolve to whichever role is 'active' and you'd miss the other token's notifications.
NotificationsState · controllers/notifications_controller.dart · const class
Immutable state holding isLoading, the merged notifications list, and an optional error. Exposes a derived unreadCount used by the bell badge.
- const default is NotificationsState(isLoading: true, notifications: const []).
- copyWith allows partial updates; error is intentionally pass-through (passing null clears).
- unreadCount = notifications.where(!isRead).length — recomputed per watcher.
- unreadCount is O(n) — fine for ~50 items; if pagination grows, cache it on update.
- An empty list with a non-null error is a valid 'we tried, failed' state — UI should show retry, not skeleton.
Stays in the same file as the controller — split if state grows independent concerns.
Data layer
NotificationService (FCM + Local) · core/services/notification_service.dart
Singleton wrapping FirebaseMessaging + flutter_local_notifications. Handles: permission request, foreground listener (shows a local notification), background handler, token retrieval/refresh callback, terminated-state initial-message check, topic sub/unsub.
- initialize() requests permission, registers background handler, subscribes to onMessage, sets up local notifications channel.
- Foreground messages with a notification payload are mirrored into a local notification via _showNotification.
- FirebaseMessaging.onTokenRefresh forwards to _onTokenRefresh callback registered by DioHelper.syncFcmTokenForAllRoles.
- Background handler is a top-level @pragma('vm:entry-point') function — must stay at file scope.
- deleteToken is invoked on logout (AuthStateNotifier).
- Android creates a high-importance channel ('high_importance_channel') — required for heads-up display.
- iOS requires presentAlert/presentBadge/presentSound to be true at show time, otherwise the local notification is silent.
- Permission denial silently fails — initialize still completes; getToken may return null. UI shows no notifications without surfacing this to the user yet.
- Topic subscribe/unsubscribe is exposed but not used today.
Initialize is invoked from main.dart before runApp; flutter_local_notifications must initialize after Firebase to share channel IDs cleanly. Native SDK contracts (no HTTP — Firebase + local notifications plugin): • FirebaseMessaging.requestPermission(alert,badge,sound,…) → NotificationSettings { authorizationStatus } — screen: app boot (main.dart) • FirebaseMessaging.getToken() → String? (device FCM token) — screen: app boot + DioHelper._checkAndSendFcmToken • FirebaseMessaging.onTokenRefresh → Stream<String> — screen: app boot (wires into DioHelper.syncFcmTokenForAllRoles) • FirebaseMessaging.onBackgroundMessage(_firebaseMessagingBackgroundHandler) — top-level entry-point — screen: app boot (debug log only) • FirebaseMessaging.onMessage.listen → RemoteMessage { notification: { title, body }, data: {…} } — screen: app boot → _showNotification (mirrors to local notif) • FirebaseMessaging.onMessageOpenedApp / getInitialMessage() → RemoteMessage — screen: app boot (deep-link to /orders/:id, etc.) • flutter_local_notifications.show(id, title, body, NotificationDetails(...)) → void — channel 'high_importance_channel'.
FCM Token Sync (per-role) · core/network/dio_helper.dart · syncFcmTokenForAllRoles + _checkAndSendFcmToken
Backend cares which (auth_token, fcm_token) pairs are active — the customer and seller tokens get separate FCM registrations. DioHelper owns this side channel, keyed by the tuple in SharedPreferences so a re-send only fires on actual change.
- First-of-session: on the first authenticated request, _checkAndSendFcmToken fires fire-and-forget for that auth token.
- syncFcmTokenForAllRoles is explicitly called after login to register both tokens if dual login succeeded.
- _checkAndSendFcmToken uses a separate raw Dio (not the singleton) to avoid interceptor recursion.
- AuthStorageService.isFcmTokenSent / markFcmTokenSent dedupe by (fcmToken, last20charsOfAuthToken).
- _fcmSyncInProgress Set prevents two parallel requests with the same auth token from each sending the FCM token (burst-at-startup race).
- Empty fcmToken is a hard 'skip' — happens before FirebaseMessaging permission resolves.
- Token-tracking keys are never cleared on logout — fine, because clearSession wipes the tokens themselves and the keys become orphaned but harmless.
When debugging missing pushes, first verify the right key in SharedPreferences exists ('fcm_sent_<token>_<suffix>') — if missing, the upload never fired.
Mark-as-Read Pipeline · _toggleReadApi · POST /social/fcm-notifications/toggle-read
Read receipts are optimistic: the UI flips isRead immediately, then a raw Dio POST hits the toggle-read endpoint with the SAME token the notification was fetched under. Failure is logged but not surfaced.
- markAsRead → optimistic state update + _toggleReadApi(id, authToken).
- Raw Dio POST /social/fcm-notifications/toggle-read with explicit Bearer header.
- On success: debug log only; on failure: debug log only — UI does not roll back.
- Read state is preserved across refresh by the controller (see notifications-controller).
- If the user goes offline and marks notifications read, the server stays out of sync until the next online session; a future enhancement could queue these toggles.
- Using the per-notification authToken (and not the current role's token) is critical — cross-role markRead would silently 404.
Backend exposes the toggle as idempotent — calling it twice on an already-read notification is safe.
Dependency Injection layer
Notifications Route + FCM Bootstrap · core/routing/app_router.dart · /notifications + main.dart init
GoRoute for /notifications inside the ShellRoute with a custom slide-from-bottom + fade transition. NotificationService.initialize is called from main.dart before runApp so messaging is live for the first frame.
- main.dart: await NotificationService().initialize() → registers handlers, asks permission, gets initial token.
- main.dart wires FirebaseMessaging.onTokenRefresh → DioHelper().syncFcmTokenForAllRoles().
- /notifications route in ShellRoute uses CustomTransitionPage with a 400ms slide-and-fade.
- If initialize fails (no Google Play Services on Android, permission denied on iOS), the rest of the app still boots — handlers are no-ops.
- Top-level background handler must remain top-level (Dart isolate constraint) — don't move it inside the class.
Background handler runs in a separate isolate without your Riverpod tree — it can only log; UI updates must wait for onMessageOpenedApp.
Notifications Provider · notificationsControllerProvider · NotifierProvider
Single NotifierProvider exposes the merged in-app stream. NotificationService is a process-wide singleton with no provider wrapper — it predates Riverpod adoption in this codebase.
- NotificationsScreen ref.watches the provider.
- Home bell badge ref.watches state.unreadCount.
- Provider survives screen pops (no autoDispose) so badge stays accurate.
- Re-mounting NotificationsScreen does not re-fetch — refresh must be called explicitly (or pull-to-refresh).
Wrapping NotificationService in a Provider would simplify testing — currently any code that constructs NotificationService() gets the singleton.
Profile & Profile Setup
Dual-role profile surface: customer info (/store/customers/me) and seller info (/vendor/sellers/me) fetched in parallel, plus a multi-page profile-setup wizard run after registration and a manage-profile editor for in-session edits.
Riverpod · Medusa /store/customers/me · Vendor /vendor/sellers/me
API surface
| Method | Endpoint | Purpose | Auth | Status |
|---|---|---|---|---|
| GET | /store/customers/me | Fetch the authenticated customer's full profile (identity + addresses + metadata). | — | no status |
| POST | /store/customers/me | Update the authenticated customer's profile (changed fields only). | — | no status |
| GET | /store/customers/me/personal-info | Fetch a lighter profile slice used by header widgets (display name, avatar, role badges). | — | no status |
Presentation layer
Profile Tab + Detail Screens · profile/profile_tab_page.dart · profile.dart · profile_details.dart · login_required_profile.dart
Four screens forming the profile surface. ProfileTabPage is the bottom-nav tab (or LoginRequiredProfile when guest). ProfilePage is the in-shell menu screen. ProfileDetailsPage renders the full info card. SeavenProfileHeader and InstagramProfileHeader pick the layout per role.
- ProfileTabPage decides login vs not-login based on authStateProvider.
- LoginRequiredProfile shows the login/register CTAs for guests.
- ProfilePage shows the menu of actions (manage profile, settings, become seller, devenir prestataire, logout).
- ProfileDetailsPage watches personalInfoProvider and renders the cards (info, addresses, etc.).
- BecomeSellerBanner appears for clients only — links to /devenir-prestataire.
- MetiersBottomSheet (seller-only) lets a seller pick or edit their métiers; consumed by currentSellerTradesProvider.
- Avatar editing happens elsewhere (ManageProfileScreen) — the headers are read-only.
- Pull-to-refresh on the tab triggers personalInfoNotifier.refreshPersonalInfo.
Two header variants (Seaven and Instagram) are an A/B-style holdover from a redesign sprint — only one is currently shown in production.
Manage Profile Screen · manage-profile/manage_profile.dart
Form-based editor for the authenticated customer profile. Fields for first/last name, phone, photo and addresses. Submits via customerProfileServiceProvider.updatePersonInfo.
- Reads current data from customerProfileServiceProvider.
- User edits fields; submit builds a CustomerProfileRequest with only the diff.
- updatePersonInfo throws → SnackBar with message; succeeds → pop with success snackbar.
- Avatar upload is handled separately (multipart) and only persists if the user also taps Save afterwards.
- Phone field is optional — empty string is dropped from the request so backend doesn't null it out.
- Form is unmounted aggressively on submit success; ref.mounted guard in the notifier protects against this.
Updating seller-specific fields (métiers, working hours) is in a different screen, not here.
Profile Setup Wizard · profile_setup/presentation/profile_setup.dart + pages/*
Multi-page legacy wizard: role selection → personal info → client OR prestataire-specific → submit. The freelancer path collects diploma, specialties, mobility, working days/hours.
- ProfileSetupScreen renders the page indicator + the active page widget.
- Pages: role_page → info_page → client_page (clients) | prestataire_page (sellers).
- Each page calls ProfileSetupController.next* / set* methods.
- Final submit dispatches to /store/customers/me + diploma upload + AuthStorage.markProfileSetupComplete.
- Indicator widget is hard-coded to N pages — change with care.
- Hot reload during the wizard wipes the StateNotifier state — design choice, dev-only annoyance.
- Diploma upload uses path_provider + multipart; failure pops a snackbar but does NOT rollback the customer-profile update.
The redesigned onboarding lives in onboarding_register/ and onboarding_register_seller/ — this wizard is a fallback for users from before the redesign.
Domain layer
Customer Profile Model · manage-profile/customer_profile_response.dart + request.dart
CustomerProfileResponse mirrors /store/customers/me — id, first_name, last_name, email, phone, addresses, metadata. CustomerProfileRequest is the partial update payload posted by the manage-profile screen.
- fromJson is tolerant to missing fields — every field optional except id.
- Edit screens construct a CustomerProfileRequest with only the changed fields.
- Response is consumed by ProfileDetailsPage, header widgets, and the address picker for cart shipping defaults.
- Metadata is a free-form map — used for client-side flags like 'has uploaded avatar this session'.
- Phone is optional — backend rejects updates that empty out a previously-set phone, so request omits the field entirely.
The cutomser_details_model.dart filename is a typo — kept as-is to avoid breaking imports.
Personal Info Model · profile/personal_info_response.dart
PersonalInfoResponse mirrors /store/customers/me/personal-info — the lighter slice used by the profile tab header (display name, photo, role-specific badges).
- Returned by UserService.getPersonalInfo.
- Cached by PersonalInfoNotifier; consumed by SeavenProfileHeader and InstagramProfileHeader.
- Photo URL can be null — header falls back to initials.
- This endpoint exists alongside /store/customers/me because the personal-info shape changes more often than the full profile and the backend wanted a stable slim contract.
Don't conflate with CustomerProfileResponse — they overlap but the personal-info endpoint is meant for read-mostly headers, not for edits.
UserProfileIds Provider · personal_info_provider.dart · userProfileIdsProvider + currentCustomerIdProvider
FutureProvider that fetches the authenticated user's customer ID (always) and seller ID (only when role==freelancer) in parallel and returns both. currentCustomerIdProvider selects the active one based on role — consumed by the cart, wishlist, and post-author scoping.
- Watches authStateProvider; bails to empty when !isLoggedIn.
- Spawns UserService.getClientInfo + (if freelancer) VendorService.getSellerProfile in Future.wait.
- currentCustomerIdProvider re-reads userProfileIdsProvider + role and returns sellerId or customerId.
- sellerProfileRawProvider exposes the full raw seller payload (used by trades/metiers UI).
- currentSellerTradesProvider derives the métier list from the raw seller via parseSellerTrades.
- Clients NEVER hit /vendor/sellers/me — the role gate exists specifically to suppress 2 wasted 401 requests per home boot.
- Both fetches swallow their own errors so a failure in one branch doesn't blank the other.
- AuthState equality override (see auth feature) prevents userProfileIdsProvider from refetching on every login-flag tick.
Several other features (cart, wishlist) take a hard dependency on currentCustomerIdProvider — keep its semantics stable.
CustomerProfileNotifier · manage-profile/customer_profile_provider.dart · AsyncNotifier
AutoDispose AsyncNotifier for the edit/view screens. loadClientInfo on build, refreshClientInfo for pull-to-refresh, updatePersonInfo for edits — all gated by ref.mounted checks to avoid setting state after disposal.
- build() returns getClientInfo() — set loading → data | error.
- updatePersonInfo: read userServiceProvider BEFORE setting loading (prevents disposed-ref crash), then POST, then state.data on success.
- Errors rethrow so the calling form can show a SnackBar with the message.
- ref.mounted guard prevents the classic 'setState after dispose' crash when the user navigates away mid-update.
- AutoDispose means stale state goes away when ManageProfileScreen pops — re-entry refetches.
- Calling refreshClientInfo immediately after a successful update is redundant — the update response already contains the fresh data.
userServiceProvider is declared twice (here and in personal_info_provider.dart) — both yield the same UserService instance, no problem in practice.
PersonalInfoNotifier · profile/personal_info_provider.dart · AsyncNotifier
AsyncNotifier wrapping /store/customers/me/personal-info. Loaded once on first read; refreshPersonalInfo re-fetches. Consumed by header widgets that need just the name/photo slice.
- build() awaits loadPersonalInfo.
- loadPersonalInfo sets AsyncValue.loading then calls UserService.getPersonalInfo.
- refreshPersonalInfo is a thin wrapper used by pull-to-refresh on the profile tab.
- Errors are captured as AsyncValue.error and returned as null — the screen renders shimmer + retry state.
- Not autoDispose — the cached personal info is reused across the whole app lifetime.
Both this and CustomerProfileNotifier exist intentionally — different cache lifetimes for different consumers.
ProfileSetupController · profile_setup/presentation/providers/controller.dart
Legacy StateNotifier driving the post-registration profile setup wizard. Holds role choice, personal info, address, freelancer-only fields (diploma, specialties, mobility, working hours), pageIndex, and isLoading/error.
- Page-level widgets call setFirstName / setSex / setAddress / setSpecialties etc.
- nextPage / previousPage walk through the pages in order (role → info → client/prestataire → confirm).
- On final submit, the controller posts the assembled state to /store/customers/me + uploads diploma file (seller path).
- On success: mark profile_setup_complete in AuthStorage, refresh authState, navigate to /home.
- Diploma file upload is gated by role==freelancer — clients skip the field entirely.
- Page index increments are unbounded — the controller assumes the calling screen knows the page count.
- isLoading flag is a single boolean — concurrent operations clobber each other (e.g., file upload + form submit).
This wizard predates the newer onboarding_register / onboarding_register_seller wizards (see app_router.dart). It is still routed via /profile-setup but no longer the default landing for new users.
Data layer
UserService · core/services/profile_service.dart
Dio-backed client for the three customer-profile endpoints: GET /store/customers/me, POST /store/customers/me (update), GET /store/customers/me/personal-info.
- getClientInfo → CustomerProfileResponse.fromJson.
- updateCustomerProfile → POST with the changed-fields-only request body.
- getPersonalInfo → PersonalInfoResponse.fromJson.
- Every call carries authScope='customer' RequestTrace — Dio interceptor attaches the customer token even when the user is in freelancer mode.
- 401 from /store/customers/me is rethrown as 'Unauthorized' — the redirect guard will then bounce to /login.
- Error responses with HTML bodies are surfaced as 'Failed to fetch …' rather than the raw HTML.
Despite being named UserService, the class only knows the customer endpoints — seller profile reads live in VendorService (see seller features). GET /vendor/sellers/me is consumed by userProfileIdsProvider when role=freelancer.
Dependency Injection layer
Profile Routes + Providers · core/routing/app_router.dart · /profile-menu, /profile, /manage-profile, /profile-setup
Four GoRoutes: /profile-menu (ProfilePage menu), /profile (ProfileDetailsPage), /manage-profile (editor), /profile-setup (legacy wizard, OUTSIDE the ShellRoute for full-screen wizard UX).
- Auth redirect (see auth feature) bounces incomplete-profile users to /profile-setup or /onboarding_register based on isPendingSellerRegistration.
- Profile menu pushes to /manage-profile or /settings.
- /profile-setup is outside the ShellRoute → no nav bar.
- Direct deep-link to /profile-setup with profile already complete bounces back to /home via the auth guard.
- /profile-menu is the route name 'profileMenu' even though the URL is /profile-menu — keep the name in sync with go_router consumers.
If you migrate the legacy wizard out, also update the redirect's pendingOnboardingPath fallback in app_router.dart.
Search (Sellers + Places)
Seller-handle search backed by a single lazy fetch + client-side filter, with a persistent local recent-history strip. The same Geoapify autocomplete helper also powers the address pickers in checkout and seller onboarding.
Riverpod · Medusa /store/seller · Geoapify autocomplete · SharedPreferences history
API surface
| Method | Endpoint | Purpose | Auth | Status |
|---|---|---|---|---|
| GET | /store/seller?offset=:offset&limit=:limit | Paginated list of sellers for the seller-handle search screen. | — | no status |
| GET | /store/seller/:handle | Fetch a single seller's public detail page (profile + products + prestations + reviews). | — | no status |
| GET | https://api.geoapify.com/v1/geocode/autocomplete | Place autocomplete for address fields across search, map picker, checkout, prestation. | — | no status |
| GET | https://api.geoapify.com/v1/geocode/search | Forward-geocode a single query string to a place. | — | no status |
| GET | https://api.geoapify.com/v1/geocode/reverse | Reverse-geocode a (lat, lon) pair to a place suggestion (map picker, prestation). | — | no status |
Presentation layer
Search Screen · features/shared/search/search.dart
Full-screen search UI: text field at top, recent-history chips, seller results grid below, pull-to-refresh, near-bottom load-more. Pushed from Home with a slide-from-bottom transition.
- On open, ref.watches sellersProvider and renders history strip + empty search state.
- Each keystroke calls sellersNotifier.search(query) — local filter is instant; first-time fetch is awaited.
- Result tap calls addToHistory(seller) and context.push(/seller/:handle).
- Long-press on history chip → removeFromHistory.
- Clear-all button on history strip calls clearHistory.
- Auto-focus is intentional; users land in the search field immediately on screen open.
- Empty-query + empty history renders an illustration 'No recent searches'.
- Loading-more spinner is footer-anchored, not full-screen, so existing rows stay visible.
Page is wrapped in a PageStorageKey('search_page') so scroll position survives the back/forward push.
Seller Detail Screen · screens/seller_detail_screen.dart
Full seller profile: avatar, métiers, follower count, products grid, prestations, reviews. Custom slide-from-right page transition reinforces the 'deeper into the catalog' navigation.
- Reads handle from the GoRouter path param.
- ref.watches sellerDetailProvider(handle) — renders SellerDetailShimmer while loading.
- Follow / unfollow CTA dispatches into the follow_service (not in this feature) and invalidates the detail provider.
- Tapping a product/prestation pushes the appropriate detail route.
- Deep-link from a notification or shared URL works because the screen reads pathParameters['handle'] and refetches on cold start.
- 404 errors render an empty state with a 'Back to search' CTA.
Avatar tap doesn't open a full-screen photo viewer today — design decision, not bug.
Domain layer
Seller Model · models/sellers_response.dart · Seller, SellerTrade
Public seller card data — id, name, handle (username), photo, store_status, plus a list of SellerTrade (métier) entries. SellersResponse wraps a paginated list with count.
- Seller.fromJson mirrors the /store/seller list item.
- SellerTrade is the métier sub-entity; parseSellerTrades extracts it from the seller raw map.
- fromJson tolerates missing photo / handle — empty strings default in.
- store_status is a free-form string ('active', 'paused', 'pending') — UI maps to a color but defaults to grey for unknown values.
- handle is the only identifier used in URLs (/seller/:handle) — must be unique server-side; the client doesn't validate.
SellerTrade is re-exported and consumed by the profile feature (currentSellerTradesProvider) — keep the schema stable.
SellersState · providers/sellers_provider.dart
All-in-one state holding the full fetched sellers list, the filtered subset shown for the current query, the local search history, pagination cursors (offset/limit/totalCount/hasMoreData), and isLoading + isLoadingMore + searchQuery + error.
- Empty default — actual content arrives via SellersNotifier.fetchSellers + loadHistory.
- copyWith re-uses the standard ?? pattern; error is pass-through so passing null clears it.
- filteredSellers is recomputed by _applyLocalFilter every time the underlying sellers list or query changes.
- Empty filteredSellers + non-empty searchQuery = 'no results for query'.
- Empty filteredSellers + empty searchQuery = 'show recent history' (by design).
- hasMoreData=false stops both manual loadMore and the fetchAllSellers loop.
Two separate loading flags exist so the loadMore spinner doesn't replace the existing list with a full-screen loader.
SellersNotifier · providers/sellers_provider.dart · Notifier<SellersState>
Owns seller fetching, paginated load, lazy-load-on-first-search, local filter, search history (load/add/remove/clear), and reset on screen close.
- build() schedules Future.microtask(loadHistory) so the history strip appears before any fetch.
- search(query) updates searchQuery + filteredSellers locally; if the catalog is empty and query is non-empty, kicks off fetchSellers.
- fetchSellers POSTs /store/seller with offset/limit; appends to state.sellers on offset>0.
- fetchAllSellers loops fetchSellers until hasMoreData is false (used by Search-All-In-Map flow).
- Search history is persisted in LocalStorageService — addToHistory / removeFromHistory / clearHistory all reload via loadHistory.
- Lazy fetch: the catalog is NOT fetched until the first non-empty search — saves a request on opening Search with no intent.
- Local filter is name+handle case-insensitive contains — no fuzzy matching; an exact handle match is not prioritized.
- fetchAllSellers has a safety check `if (currentOffset == previousOffset) break` to prevent infinite loops if the server returns 0 items but a non-zero count.
Debounce was removed (see commented `_debounce?.cancel()` in reset) — current implementation relies on the user to slow down keystrokes.
Seller Detail Provider · providers/seller_detail_provider.dart
FutureProvider.family keyed by handle that fetches /store/seller/{handle} (full profile + products + reviews) for the SellerDetailScreen.
- ref.watch(sellerDetailProvider(handle)) on the detail screen.
- Provider hits /store/seller/{handle} and returns the typed Seller-detail map.
- Family entry stays cached unless invalidated — back-and-forth navigation is instant.
- Handle conflict (two sellers with the same handle) is a backend bug — client falls back to the first match.
- 404 returns a typed error inside AsyncValue.error which the screen renders as 'Seller not found'.
ref.invalidate(sellerDetailProvider(handle)) after a follow/unfollow to force a re-fetch with the updated followers count.
Data layer
Sellers Data Source · DioHelper().get('/store/seller')
Direct DioHelper calls inside SellersNotifier — there is no dedicated SellersService class. /store/seller paginates by offset/limit and returns a count for pagination math.
- DioHelper.get('/store/seller', queryParameters: { offset, limit })
- Response → SellersResponse.fromJson → state mutation.
- Each call carries authScope='customer'; clients can browse sellers, sellers can too.
- Backend counts include 'paused' / 'pending' sellers — the UI does not currently filter them out at fetch time.
- Network errors surface as 'Something went wrong. Try again!' — generic message by design (no enumeration value).
Promoting these calls into a SellersService would let other features reuse them — today only the search screen consumes /store/seller.
Search History (SharedPreferences) · core/services/local_storage.dart · sellerSearchHistory
Persistent recent-search list keyed globally (not per-user). Up to N entries; new entries push the oldest off the end. Used to render the suggestions strip before the user types.
- getSellerSearchHistory reads a JSON array.
- addSellerToSearchHistory dedupes by id and prepends.
- removeSellerFromSearchHistory drops one entry; clearSellerSearchHistory wipes all.
- History is shared across customer/seller roles on the same device — switching role keeps the same recent list.
- JSON-decode error resets to empty (corrupt local state recovers silently).
If we move history to a per-user key (like the cart does), make sure to migrate existing entries to avoid surprising users. Local storage contracts (SharedPreferences): • getSellerSearchHistory() — read 'seller_search_history' → List<Map> → List<Seller> — screen: lib/src/features/shared/search/search.dart (history strip) • addSellerToSearchHistory(seller) — dedupe by id + prepend — screen: search.dart (on result tap) • removeSellerFromSearchHistory(id) — screen: search.dart (long-press dismiss) • clearSellerSearchHistory() — screen: search.dart (Clear all)
Geoapify Service · core/services/geoapify_service.dart
Static helper around Geoapify's autocomplete / geocode / reverseGeocode endpoints. Used by the address pickers in checkout, profile, and the seller onboarding wizard. Search uses it for an in-screen 'find a city' affordance.
- isConfigured gates every call — falls back to empty results when GEOAPIFY_API_KEY is missing.
- autocomplete: text + optional bias (lat/lon) + limit; returns MapPlaceSuggestion[].
- geocode: text → single best match.
- reverseGeocode: lat/lon → single MapPlaceSuggestion.
- Empty/missing API key is a configuration error in .env but returns gracefully (no crash) so debug builds without keys still work.
- Bias parameter format is 'proximity:lon,lat' — Geoapify uses lon,lat (not lat,lon).
- Default 5s timeout — Geoapify is rarely slower but a flaky network surfaces as an empty suggestion list, not an error.
Static class with a private constructor — intentional; no DI wrapper. Tests must override at the top of the static cache (or wrap into a provider in the future). All endpoints below hit https://api.geoapify.com/v1 (NOT the Naow backend).
Dependency Injection layer
Search Routes + Providers · core/routing/app_router.dart · /search + /seller/:handle
Two routes: /search (CustomTransitionPage with slide-up animation) and /seller/:handle (CustomTransitionPage with slide-right). sellersProvider is a single NotifierProvider; sellerDetailProvider is a family-keyed FutureProvider.
- Home swipe-left or search-icon tap pushes /search.
- Seller card tap pushes /seller/:handle with the handle as a path parameter.
- Both routes live in the ShellRoute, so the nav bar stays visible.
- Custom transitions use 420ms forward + 300ms reverse — slightly slower forward to make the new content feel deliberate.
- GoRouter resolves /seller/:handle from external links — make sure the handle matches the URL-safe charset.
If the search experience grows to include products + sellers + places in one screen, split the notifier into per-source notifiers before the controller bloats further.
Seller Services (Provisions)
Seller-side management of provision products (service offerings): list, create via 3-step wizard, view detail, edit options + pricing + cancellation policy. The create flow chains 4-6 backend calls (provision → member assignment → location → policy).
Riverpod · Vendor Provisions API · 4-step creation wizard
API surface
| Method | Endpoint | Purpose | Auth | Status |
|---|---|---|---|---|
| GET | /vendor/categories | Top-level seller_services categories for the category picker. | — | no status |
| GET | /vendor/categories/:parentId | Sub-categories of a chosen parent category. | — | no status |
| POST | /vendor/files | Multipart upload of the wizard's thumbnail / images before submit. | — | no status |
| GET | /vendor/provisions | List the seller's provisions (services), including proposed + published. | — | no status |
| GET | /vendor/products/:id | Provision detail (preload for the service-details screen). | — | no status |
| POST | /vendor/provisions | Create a new provision (3-step wizard's main submit). | — | no status |
| POST | /vendor/provisions/:id | Update a provision (partial). | — | no status |
| POST | /vendor/products/:id/options/:optionId | Update a product option (title + values). | — | no status |
| POST | /vendor/products/:id/variants/:variantId | Update a variant (prices, title, sku). | — | no status |
| DELETE | /vendor/provisions/:id | Delete a provision (services screen). | — | no status |
| GET | /vendor/members | List the seller's members for the member-assignment step. | — | no status |
| POST | /vendor/members/:memberId/provisions | Bind selected provisions to a member with their working hours, slot duration, exceptions and location. | — | no status |
| POST | /vendor/product-location/:productId | Pin a geographic location on the provision (post member-assign). | — | no status |
| GET | /vendor/bookings/policy/:productId | Read the booking policy attached to a provision (deposit %, cancellation window, refund rules). | — | no status |
| POST | /vendor/bookings/policy | Create or update the booking policy for a provision. | — | no status |
| GET | /store/provisions | Customer view of published provisions for the marketplace home / client grid tile. | — | no status |
| GET | /store/product-location | Map-driven nearby provisions search (lat/lng/radius). | — | no status |
| GET | /store/provisions/:id?fields=*variants.calculated_price,+variants.inventory_quantity,*seller,*reviews,*reviews.customer | Provision detail (full payload with seller + reviews + per-variant pricing). | — | no status |
| GET | /store/provisions/:id?fields=metadata | Metadata-only slice used by the booking screen. | — | no status |
| GET | /store/provisions/:productId/slots | Available booking slots used by the calendar. | — | no status |
| GET | /store/provisions/:productId/policy | Customer view of the provision's booking policy (deposit %, cancellation window, refund rules). | — | no status |
| GET | /store/provisions/:productId/booking-questions | Booking questions the customer must answer before checkout. | — | no status |
Presentation layer
Seller Services Screen · services/services.dart
Lists the seller's provisions with status pills, variant counts, thumbnail, and an action menu (edit, delete, duplicate). FAB pushes the add-prestation wizard.
- Watches sellerServicesProvider; renders loading shimmer / list / empty state via AsyncValue.when.
- Row tap pushes /prestation/:id (PrestationDetailScreen).
- Delete tap opens a confirmation dialog → SellerServicesController.deleteService.
- FAB → context.push('/add-prestation').
- Status pills color-mapped: proposed (amber), published (green), rejected (red), unknown (grey).
- Empty state nudges the user to tap the FAB ('Add your first service').
- Pull-to-refresh re-invokes fetch().
449 lines — would benefit from extracting the row into a widget but that's a refactor, not a behavior change.
Prestation Detail Screen · service_details/service_details.dart
Read-only display of a single provision: title, description, status, options, variant prices, and (when available) the booking policy card. Edit button routes to EditProvisionScreen.
- Watches prestationDetailProvider(serviceId) family entry.
- Renders options as chip groups; variants as a price table.
- Booking policy card: deposit %, max cancellation delay, refund rules table.
- Edit button → context.push('/prestation/:id/edit').
- If bookingPolicy is null the policy card is replaced by a 'Configure cancellation policy' CTA.
- Long descriptions are truncated with a 'Show more' toggle.
service_details/CLAUDE.md lists schedule/availability as a future addition — track it there.
Edit Provision Screen · service_details/edit_provision_screen.dart
Editable form for title, description, option label, and variant price tiers. Currently uses DioHelper directly for the product update; policy edit lives here too (POST upsertBookingPolicy).
- Loads the existing ServiceDetail via prestationDetailProvider.
- Form fields preload from state; submit fires a PATCH-style POST to /vendor/products/{id}.
- Policy editor (deposit %, delay, rules list) submits via VendorService.upsertBookingPolicy after the product update succeeds.
- Falls back from /vendor/provisions/{id} to /vendor/products/{id} on 404 (older API path).
- Editing options that already have variants is risky — backend may reject if variant.value strings no longer match options.values.
- Currency change is disabled in edit mode to prevent price-amount drift.
- Photo upload reuses the same VendorService.uploadPublicFile helper as add-prestation.
Migrating the product update from DioHelper to VendorService is on the TODO list in service_details/CLAUDE.md.
Add Prestation Wizard · add-prestation/add-prestation.dart
3-step wizard (Informations → Options & Tarifs → Disponibilités). 2723 lines of UI orchestrating the most complex create flow in the app. Submits via the add-prestation controller's 4-6-call pipeline.
- Step 1: title, description, thumbnail picker (uploadPublicFile), currency, category + sub-category (vendorProductCategoriesProvider + vendorSubCategoriesProvider).
- Step 2: dynamic options + variants table with per-variant price.
- Step 3: working hours per day, exceptions, slot duration, address (Geoapify autocomplete → reverseGeocode for lat/lng), and the cancellation policy block.
- Submit calls the controller's pipeline; success pops back to /services.
- Thumbnail upload happens immediately on selection — a failed upload keeps the user on step 1 without proceeding.
- Step 3 location uses GeoapifyService — without an API key, the address picker is text-only and the submit fails server-side.
- Policy fields are pre-filled with sensible defaults (deposit=20%, delay=72h) so a hurried seller can ship without touching them.
The CLAUDE.md in this folder is the canonical multi-call create flow — read before changing the submit order.
Domain layer
Service Models · services/services_model.dart + service_details_model.dart + add-prestation/model/*
Three layers of model: SellerService (list-row slice), ServiceDetail (full detail with options/variants/policy/metadata), and the add-prestation form state (CreatePrestationState + ProvisionPriceTier + CancellationRule).
- SellerService is constructed from Product (mapped down inside SellerServicesController.fetch).
- ServiceDetail bundles options, variants, BookingPolicy and product metadata for the seller-side detail screen.
- BookingPolicy (deposit %, maxCancellationDelayHours, rules[]) is loaded alongside the product in PrestationDetailController.
- Add-prestation form has its own state with parsed fields (parsedDepositPercentage, apiCancellationRules) for the submit payload.
- Older provisions may have no policy — getBookingPolicy can return null and ServiceDetail.bookingPolicy stays null.
- Variants count is exposed at the list level so cards can show '4 prices configured' without hydrating each variant.
- Member schedule is part of the model spec (see CLAUDE.md) but is not yet wired into ServiceDetail.
Two CLAUDE.md files in service_details/ and add-prestation/ document the missing-policy gap that has since been partially filled — keep them up to date as you finish the work.
Seller Services Controller · services/services_provider.dart · StateNotifier.autoDispose
AutoDispose StateNotifier loading the seller's provisions from /vendor/provisions and mapping them down into the lightweight SellerService rows. Owns the deleteService action.
- Ctor → fetch() → VendorService.getProvisions → map Product → SellerService.
- AsyncValue<List<SellerService>> tracks loading/data/error.
- deleteService removes the row optimistically (rebuilds list) after VendorService.deleteProvision succeeds.
- delete failure surfaces a typed message extracted from data['message'] when possible.
- AutoDispose means leaving and returning to the screen always refetches — intentional, since seller edits can change items elsewhere.
- Status filter (proposed/published/rejected) is done on the UI side; backend returns all statuses.
Uses the legacy StateNotifier API even though the codebase is mostly Notifier — migrate when convenient.
Prestation Detail Controller · service_details/service_details_provider.dart · family
StateNotifier family keyed by serviceId. Fetches /vendor/products/{id}, parses options and variants, then attempts to load the matching booking policy from VendorService.
- Constructor invokes fetch() immediately.
- fetch() GETs /vendor/products/{id}, parses options/variants, builds ServiceDetail.
- Then calls VendorService.getBookingPolicy(serviceId) and merges BookingPolicy if present.
- Errors during policy load are silently swallowed — policy is optional.
- Older provisions without a policy: getBookingPolicy can 404 — caught and treated as 'no policy yet'.
- Per-key auto-dispose means visiting another service's detail does NOT invalidate the previous family entry — back/forward is instant up to the autoDispose timeout.
- Parsing helpers (_parseOption, _parseVariant) tolerate missing fields — bad data renders an empty option/variant rather than crashing.
Currently uses DioHelper directly for the product fetch and VendorService only for the policy — see service_details/CLAUDE.md for the migration plan.
Add Prestation Wizard Controller · add-prestation/provider/add_product_provider.dart
Drives the multi-step wizard: holds the form state, exposes category providers, and runs the 4-6-call submission pipeline (create → assign → location → policy).
- vendorProductCategoriesProvider + vendorSubCategoriesProvider load top-level + nested categories on demand.
- Form state mutations (title, thumbnail, options, variants, working hours, location, policy).
- Submit pipeline: VendorService.createProvision → /vendor/members → assignProvisionsToMember (provision + workingHour + slotDuration + location) → addProductLocation → upsertBookingPolicy.
- Each step bubbles errors to a single 'submitError' state slot.
- If member assignment fails after createProvision, the provision is created but orphaned — backend cleanup is manual today.
- Policy upsert is the last step; it can run independently after the rest succeeds (idempotent).
- Geoapify is used to resolve the address into lat/lng before /vendor/product-location.
- Currency, sub-category, and option values are validated client-side before the submit fires.
CLAUDE.md in this folder is the source of truth for the multi-call sequence — keep it in lockstep with the controller. After these calls the wizard chains VendorService contracts (createProvision → assignProvisionsToMember → addProductLocation → upsertBookingPolicy) listed on the vendor-service node.
Data layer
VendorService (Provisions Slice) · core/services/vendor_service.dart · getProvisions / createProvision / deleteProvision / upsertBookingPolicy / …
Large data-layer class wrapping every /vendor/* endpoint. The provisions slice consumed by this feature: getProvisions, getProvision, createProvision, updateProvision, updateProductOption, updateProductVariant, deleteProvision, getBookingPolicy, upsertBookingPolicy. Plus member helpers for assignment.
- Every method uses DioHelper and tags requests with feature='seller/…' RequestTrace.
- createProvision: POST /vendor/provisions; updateProvision/updateOption/updateVariant: PATCH-style POSTs.
- deleteProvision: DELETE /vendor/provisions/{id}.
- getBookingPolicy: GET /vendor/bookings/policy/{productId}; upsertBookingPolicy: POST /vendor/bookings/policy.
- Member helpers (getMembers, assignProvisionsToMember, updateMemberProvision) are how schedules attach to a provision.
- All paths start with /vendor/ → DioHelper auth interceptor attaches the seller token automatically.
- upsertBookingPolicy is idempotent — calling it on an existing policy replaces it (server-side merge).
- deleteProvision may return 409 if a future booking references it — the controller surfaces the message verbatim.
VendorService is the elephant — 700+ lines covering provisions, products, members, files, calendar. Treat the provisions slice as one logical area, the products slice as another (see seller-products).
ProvisionService (Customer-side) · core/services/provision_service.dart
Customer-facing counterpart that fetches /store/provisions — the public view of the same data the seller manages. Listed here because the seller features must understand how customers will see their published provisions.
- getProvisions: paginated / filtered list — analogous to MarketplaceService.getProducts but for service-type.
- getProvisionsWithDistance: same shape with lat/lng/radius for /store/product-location.
- getProvisionById: single full provision with `*seller,*reviews` field selection.
- getProvisionSlots + getProvisionPolicy + getProvisionQuestions: feed the customer's booking flow.
- Customer-side endpoints require status='published' on the backend — proposed/rejected provisions are invisible.
- getProvisionQuestions treats 404 as 'no questions configured' (per-provision optional).
- Mirroring fields: customer sees /policy as deposit/max-delay/rules — same shape the seller upserts via /vendor/bookings/policy.
Keep ProvisionService and the vendor side aligned — a field added to the create payload usually needs surfacing in both sides.
Dependency Injection layer
Seller Services Routes · core/routing/app_router.dart · /services + /prestation/:id + /add-prestation
Three routes: /services (list, inside ShellRoute), /prestation/:id and /prestation/:id/edit (inside ShellRoute), /add-prestation (OUTSIDE ShellRoute for full-screen wizard).
- /services lists provisions for the authenticated seller.
- Row tap pushes /prestation/:id with the id as path param.
- Edit pushes /prestation/:id/edit; FAB pushes /add-prestation.
- Auth redirect gates /add-prestation behind hasSellerRole.
- /add-prestation is the only seller route declared OUTSIDE the ShellRoute (full-screen wizard).
- Edit route uses a regex match (/prestation/:id/edit) so the redirect can detect it without route-name awareness.
If you ever move /add-prestation back into the ShellRoute, the nav bar overlap on small screens needs UX review.
Seller Products (Physical)
Seller-side physical product CRUD via /vendor/products: list, create with dynamic options/variants matrix, edit, delete. Mirrored on the customer side by ProductDetailScreen which reads /store/physical-products and feeds the local cart.
Riverpod · Vendor Products API · Image upload via /vendor/files
API surface
| Method | Endpoint | Purpose | Auth | Status |
|---|---|---|---|---|
| GET | /vendor/products?type=physical | Typed list of the seller's physical products (Product[]). | — | no status |
| GET | /vendor/products?type=physical | Raw-map variant used to skip Product.fromJson when the screen only needs a subset. | — | no status |
| GET | /vendor/products/:id | Preload a single product for the edit screen. | — | no status |
| POST | /vendor/products | Create a new physical product with options + variants + images. | — | no status |
| POST | /vendor/products/:id | Update product fields (partial). | — | no status |
| DELETE | /vendor/products/:id | Delete a physical product. | — | no status |
| GET | /vendor/stock-locations | Bootstrap the list of stock locations (warehouse / store). | — | no status |
| POST | /vendor/stock-locations | Create a first-time stock location. | — | no status |
| POST | /vendor/inventory-items/:id/location-levels | Set initial stocked_quantity for a variant at a stock location. | — | no status |
| POST | /vendor/inventory-items/:id/location-levels/:levelId | Update a variant's stocked_quantity at an existing location level. | — | no status |
| POST | /vendor/product-location/:productId | Attach a geographic location (lat/lng/address) to a product. | — | no status |
| POST | /vendor/files | Multipart upload of a product image to the vendor files endpoint. | — | no status |
| GET | /store/physical-products/:productId?fields=*variants.calculated_price | Customer-side single product fetch (fallback when ProductDetailScreen has no route extra). | — | no status |
Presentation layer
Seller Products Screen · products/views/seller_products_screen.dart
List of the seller's physical products with status pills, variant counts, edit + delete actions, FAB to create. Pull-to-refresh re-invokes the controller.
- Watches sellerProductsProvider AsyncValue.
- Row tap → context.push('/seller/products/:id/edit').
- Delete confirm → SellerProductsController.deleteProduct.
- FAB → context.push('/add-product').
- Empty state suggests creating the first product with an illustration.
- Delete-failure dialog shows the server error verbatim (often 'product has active orders').
Status color mapping duplicated from the provisions screen — extract into a shared widget once stable.
Create + Edit Product Screens · products/views/create_product_screen.dart · edit_product_screen.dart
Two-step wizards. Create: 975-line composite of basic info → options matrix → variant pricing → image upload. Edit: same form prefilled, plus an inventory-quantity per variant input.
- Create: pickCategory → setTitle/desc → addOption × N → fill variant prices → upload images → submit.
- Edit: load existing product → modify any field → submit triggers updatePhysicalProduct + setInventoryItemQuantity for changed variants.
- Image picker uses image_picker; uploaded URLs are appended to product.images.
- Editing options after variants exist is risky — the matrix re-builds, but server may refuse if existing variant.value strings no longer fit.
- Currency change is allowed in edit but rare — UI shows a warning.
- Long-press on a variant offers a 'duplicate' helper to copy price into adjacent variants.
Create screen is 975 lines — a good candidate for splitting into step-widgets but not blocking shipping.
Product Details Screen (customer) · product_details/views/product_details_screen.dart
Customer-facing product page: image slider, info section, size/color selectors, quantity stepper, description + specs, sticky bottom Add-to-cart bar. Receives a Product via route extra or refetches via loadProduct.
- Reads Product from state.extra; otherwise loadProduct(id).
- ProductSizeSelector + dynamic option selectors call selectOption.
- Quantity selector calls setQuantity.
- ProductBottomBar Add-to-cart → cartControllerProvider.addToCart with selectedVariant.
- Favorite toggle dispatches into ProductDetailsController.toggleFavorite (which mirrors into marketplace).
- selectedVariant=null disables the Add-to-cart button (no SKU resolves the current options).
- Image slider lazy-loads via Image.network; pre-fetch is not implemented yet.
- Quantity steppers respect inventory_quantity when present on the variant.
The customer-side product detail lives in shared/, not in seller/ — adjacent to its sibling provision_details/ which handles bookings.
Domain layer
Seller Product Model · products/models/seller_product_model.dart
SellerProduct is the seller-side card slice: id, title, description, thumbnail, status, variants count, createdAt. Built from the raw /vendor/products map (not the customer Product entity) so seller-only fields (status='proposed') are surfaced.
- SellerProduct.fromJson takes the raw map returned by getPhysicalProductsRaw.
- Consumed by SellerProductsScreen rows.
- Status defaults to 'proposed' on creation — admin moderation flips it to 'published'.
- thumbnail can be empty — UI shows a placeholder.
Distinct from the customer Product model (marketplace/models/product.dart) — keep both, they serve different surfaces.
Create Product Form State · products/providers/create_product_provider.dart · ProductOptionEntry + ProductVariantEntry + CreateProductState
The dynamic options/variants matrix that powers the create wizard. ProductOptionEntry holds title + values (e.g. Size → S,M,L). ProductVariantEntry holds the cross-product (S/Rouge, S/Bleu, …) with per-variant price/sku/stock.
- User adds an Option row → ProductOptionEntry.values builds incrementally.
- Each new option or value rebuilds the variant matrix (cross-product of all option values).
- Per-variant fields (price, sku, stockQuantity) are filled inline in step 2.
- isValid getter on ProductOptionEntry gates the Continue button.
- Adding a third option doubles+triples the variant count quickly — UI throttles input + scrolls horizontally.
- Variant title is composed as 'value1 / value2 / value3' — separator is hard-coded ' / '.
- Empty values silently drop out of the matrix; an option with 0 valid values forces an isValid=false.
Mirrors the provision-side wizard but kept separate — physical products may have inventory tracking, provisions do not.
Seller Products Controller · products/providers/seller_products_provider.dart · StateNotifier.autoDispose
AutoDispose StateNotifier that loads the seller's products from /vendor/products and exposes deleteProduct. AsyncValue<List<SellerProduct>> backs the list screen.
- Ctor → fetch() → VendorService.getPhysicalProductsRaw → SellerProduct.fromJson × N.
- deleteProduct: optimistic removal after VendorService.deletePhysicalProduct succeeds.
- AsyncLoading on every fetch — pull-to-refresh works out of the box.
- deletePhysicalProduct can fail if inventory or active line items reference the product — server message is propagated.
- AutoDispose forces a refetch every time the screen mounts — by design, since seller stock may change.
Pagination not implemented yet — relies on the backend default limit. Add cursor support if seller catalogs grow large.
Create Product Controller · products/providers/create_product_provider.dart
Holds the form state and runs the multi-call submit: upload images via VendorService.uploadPublicFile, build the create payload, POST /vendor/products, then attach the inventory rows via setInventoryItemQuantity + assignInventoryItemLocations + addProductLocation.
- setTitle / setDescription / setImageFiles / pickCategory mutate state.
- addOption / addOptionValue / removeOption rebuild the variants matrix.
- submit: uploadPublicFile per image → createPhysicalProduct → assignInventoryItemLocations + setInventoryItemQuantity per variant.
- Errors short-circuit and surface in state.submitError.
- Image upload is sequential — parallelizing would speed up but the backend rate-limits /vendor/files.
- Variant inventory is set as an after-creation step; if it fails, the product exists but with 0 stock.
- Currency is per-product (not per-variant) — Medusa supports per-variant but the UI simplifies.
Same multi-call pattern as the provision wizard — if you change one, evaluate the other for consistency.
Product Details Controller (customer) · product_details/controllers/product_details_controller.dart
Customer-side controller for ProductDetailScreen. Holds the Product, currently selected options + resolved variant, quantity, isFavorite. _resolveVariant matches the selected options against product.variants and clears the variant when none match.
- setFromProduct seeds the state with the Product passed via route extra, auto-selecting the first value of each option.
- loadProduct(id) is the fallback path when the user deep-links without an extra — calls MarketplaceService.getProductById.
- selectOption mutates selectedOptions and re-resolves the variant.
- toggleFavorite mirrors into marketplaceControllerProvider so the parent list stays in sync.
- If no variant matches the current option combination, selectedVariant is cleared — the Add-to-cart button must disable.
- Quantity has a floor of 1; UI 'minus' button hides below that.
- isFavorite is local-only in this controller — the wishlist service is what persists it.
copyWith uses a `clearVariant` bool to explicitly null selectedVariant — copyWith's normal ?? pattern can't express 'set to null' otherwise.
Data layer
VendorService — Physical Products Slice · core/services/vendor_service.dart · physical-products + inventory + files
Subset of VendorService dedicated to physical products: getPhysicalProducts, getPhysicalProductsRaw, getPhysicalProduct, createPhysicalProduct, updatePhysicalProduct, deletePhysicalProduct, plus inventory and file-upload helpers.
- getPhysicalProductsRaw returns the raw response list — used by the list controller to skip Product.fromJson.
- createPhysicalProduct builds the full product including options, variants and pricing.
- uploadPublicFile (multipart) posts to /vendor/files and returns a public URL used as image src.
- setInventoryItemQuantity attaches stock to a variant at a stock location.
- deletePhysicalProduct cascades to variants + inventory items server-side; clients still need to refetch.
- uploadPublicFile uses a separate Dio config — multipart can't share JSON defaults.
- Stock locations are per-seller (getStockLocations / createStockLocation) — auto-bootstrapped on first product create.
Same VendorService is shared with seller-services (provisions slice) and seller-balance (Stripe slice). The class has grown to ~770 lines — splitting by domain is on the TODO list.
MarketplaceService.getProductById (customer detail) · core/services/marketplace_service.dart · getProductById
Customer-side single-product fetch used by ProductDetailScreen when it can't rely on the route extra. Returns the typed Product including variants with calculated_price.
- loadProduct(productId) calls marketplaceServiceProvider.getProductById.
- Response includes variants + calculated_price (per-region pricing).
- Product.fromJson maps the response into the typed entity used by the screen.
- Product not found → throws 'Product not found' which the controller surfaces as state.error.
- calculated_price requires the `fields=*variants.calculated_price` query — already part of the service method.
Customer + seller views read different endpoints (/store vs /vendor) and don't share a typed contract — be cautious when refactoring.
Dependency Injection layer
Seller Products + Customer Detail Routes · core/routing/app_router.dart
Four routes touching this feature: /seller/products (list), /add-product (create), /seller/products/:id/edit (edit), /product-details (customer-side, reads extra).
- Home grid 'Marketplace' (seller) → /seller/products.
- FAB on seller list → /add-product.
- Edit on a row → /seller/products/:id/edit.
- Customer marketplace tile tap → /product-details with the Product as extra.
- /seller/* routes are gated by hasSellerRole in the auth redirect; clients trying to deep-link bounce to /home.
- /product-details has no path id — depends on route extra, so deep-links are not yet shareable.
If you make /product-details a real URL (id in path), update the cart's add-to-cart deep-link and the marketing-share-link generator.
Seller Balance & Payouts
Stripe Connect payout onboarding for sellers: 3-step wizard (personal info → bank → identity verification), plus the balance + transaction list. Talks directly to api.stripe.com for tokenization and file upload, then to the backend to bind the resulting tokens.
Riverpod · Stripe Connect direct API + /vendor/stripe/* · ImagePicker
API surface
| Method | Endpoint | Purpose | Auth | Status |
|---|---|---|---|---|
| GET | /vendor/stripe/payout-account | Read the current Stripe Connect payout account state. | — | no status |
| POST | /vendor/stripe/payout-account | Submit Step 1 of onboarding: account_token from Stripe → backend creates the Connect account. | — | no status |
| POST | /vendor/stripe/bank_account | Submit Step 2 of onboarding: bank_token from Stripe → backend attaches the bank account. | — | no status |
| POST | /vendor/stripe/verify-identity | Submit Step 3 of onboarding: front-of-document file id → backend submits identity to Stripe. | — | no status |
| GET | /vendor/stripe/account | Refresh the full Stripe account JSON after onboarding completes. | — | no status |
| GET | /vendor/stripe/balance | Available + pending balance in cents. | — | no status |
| GET | /vendor/stripe/transactions | Paginated list of seller transactions. | — | no status |
| GET | /vendor/stripe/transactions/:id | Transaction detail (rendered in a bottom sheet). | — | no status |
| POST | https://api.stripe.com/v1/tokens | Direct Stripe call (Step 1): tokenize personal account details into an account token (ct_...). | — | no status |
| POST | https://api.stripe.com/v1/tokens | Direct Stripe call (Step 2): tokenize bank account details into a bank token (btok_...). | — | no status |
| POST | https://files.stripe.com/v1/files | Direct Stripe call (Step 3): upload identity document and receive a file_id. | — | no status |
Presentation layer
Balance Screen · balance/views/balance_screen.dart
Header showing available + pending balance, transactions list below, tap-to-open detail bottom sheet. Pull-to-refresh re-invokes loadAll.
- Watches balanceControllerProvider.
- Header animates the balance count-up on first load.
- Each TransactionRow → loadTransactionDetails(id) and shows TransactionDetailSheet.
- Empty state when transactions list is empty after loading.
- Balance widget shows EUR by default; multi-currency carriers would need a tab or currency selector.
- Sheet reuses showModalBottomSheet; tapping outside dismisses it without resetting selectedTransactionDetail.
Animated count-up uses a TweenAnimationBuilder so swap doesn't visually 'flicker' on refresh.
Bank Account Wizard Screen · bank_account/views/bank_account_screen.dart
Single screen that switches between three step UIs based on bankAccountControllerProvider.currentStep. Top progress bar reflects completedSteps. Each step has its own validation and submit button.
- Step 1 (personal info): name, email, phone, DOB, address → submitPersonalInfo.
- Step 2 (bank): account holder, account number, country, currency → submitBankDetails.
- Step 3 (identity): pick or take a photo → submitIdentityVerification.
- Completed state: shows 'Verified' or 'Pending review' card.
- submit errors render an inline banner with the _friendlyError message.
- Identity verification uses image_picker — gallery and camera both 2000×2000 max with quality 85.
- Validation is per-step; submitting with empty required fields keeps the user on the step.
714 lines — a candidate for splitting into per-step widget files but works as-is.
Domain layer
Balance + Transaction Models · balance/models/balance_model.dart + transaction_model.dart
BalanceModel mirrors /vendor/stripe/balance (available + pending). TransactionModel mirrors a single row of /vendor/stripe/transactions; TransactionDetailModel is the expanded shape from /vendor/stripe/transactions/:id.
- BalanceModel.fromJson normalizes the Stripe payload into typed currency amounts.
- TransactionModel.fromJson builds list rows; TransactionDetailModel inflates the per-row detail.
- Stripe amounts are minor units (cents) — models hold them as int; UI divides by 100 for display.
- Some transaction types (refunds, fees) carry negative amounts — UI must color-code accordingly.
If we add multi-currency sellers, balance arrives as an array per currency — current models flatten to a single 'currency' field.
Payout Account Model · bank_account/models/payout_account_model.dart
Mirrors /vendor/stripe/account. Exposes derived helpers: needsBankAccount, isVerified, isVerificationPending — consumed by the wizard to auto-advance the step.
- PayoutAccountModel.fromJson reads capabilities, requirements, charges_enabled, payouts_enabled.
- Helpers compute readable booleans the wizard can branch on without reasoning about Stripe internals.
- Verification can move through pending → verified → pending again if Stripe requests another document.
- needsBankAccount stays true even after the user adds a card-funded source — only a real bank routing/account number satisfies it.
Helpers exist precisely so the wizard doesn't reach into Stripe-shaped maps; keep them stable as the API evolves.
Balance Controller · balance/controllers/balance_controller.dart · Notifier<BalanceState>
Notifier that loads balance + transactions in parallel and exposes loadTransactionDetails for the detail bottom sheet. clearError / clearDetail bool flags drive copyWith's null overrides.
- build() schedules Future.microtask(loadAll); initial state is isLoading: true.
- loadAll: Future.wait([getBalance, getTransactions]); maps results into models.
- loadTransactionDetails: per-row tap → getTransactionDetails(id) → set selectedTransactionDetail.
- refresh re-invokes loadAll.
- Errors are unwrapped via replaceFirst('Exception: ', '') for a cleaner SnackBar message.
- If only one of (balance, transactions) succeeds, the other slot stays null — UI handles partial state.
- loadTransactionDetails clearDetail=true on entry so the bottom sheet can show a loader without flashing stale data.
Owns its StripeService instance directly — not provider-wrapped.
Bank Account Wizard Controller · bank_account/controllers/bank_account_controller.dart · Notifier<BankAccountState>
Drives the 3-step Stripe Connect onboarding. On boot, loads the existing account and computes which step the user lands on. Three submit methods chain Stripe direct calls and backend calls, with mapped error messages for the common Stripe failure modes.
- build() → loadPayoutAccount which advances currentStep based on account flags.
- submitPersonalInfo: getStripeAccountToken → createPayoutAccount on backend → step → bankDetails.
- submitBankDetails: getStripeBankToken → addBankAccount on backend → step → identityVerification.
- submitIdentityVerification: uploadFileToStripe → verifyIdentity on backend → refresh account.
- _friendlyError remaps known Stripe error substrings into product-friendly messages.
- Auto-step-advance: an already-verified seller lands directly on completedSteps=3 and the screen shows a 'Done' state.
- duplicate_error → 'A payment account already exists for this profile.' — Stripe's exact wording is unsuitable.
- Network / timeout → 'Network connection error.' instead of leaking the underlying exception.
- Identity verification requires a clear photo — the controller does not pre-validate image quality.
Three completedSteps states matter for the progress bar — the screen reads completedSteps, not currentStep, to decide which checkmarks to draw.
Data layer
StripeService · core/services/stripe_service.dart
Two-Dio service: one (DioHelper) for backend /vendor/stripe/* endpoints, one (_stripeDio) for direct calls to api.stripe.com using the publishable key. Covers payout account get/create, bank token + add, file upload + verify identity, account/balance/transactions.
- Backend reads/writes go through DioHelper → auth interceptor attaches the seller token.
- Stripe direct calls (tokens, file uploads) use _stripeDio with a Bearer header set to the publishable key.
- All methods carry a RequestTrace with feature='seller/stripe' or 'seller/balance'.
- Helpers (_assertSuccess) unify the throw path with friendly default messages.
- getPayoutAccount swallows 404/400/403/401 and returns null — interpreted as 'no account yet'.
- uploadFileToStripe uses multipart/form-data; bytes are streamed from the chosen file path.
- getBalance / getTransactions catch every error and return null/empty list — keeps the screen renderable even when partial Stripe outages occur.
- Direct Stripe calls bypass DioHelper interceptors — no auto-retry, no logging interceptor.
Sharing a single class for direct-Stripe and backend-binding calls is convenient but fragile — separate them if Stripe rotates the publishable key shape.
Dependency Injection layer
Balance + Bank Account Routes · core/routing/app_router.dart · /balance + /bank-account
Two GoRoutes inside the ShellRoute: /balance → BalanceScreen, /bank-account → BankAccountScreen. Both seller-only; the auth redirect bounces clients to /home.
- Seller profile menu links to /balance and /bank-account.
- If a user without seller role deep-links, redirect kicks them back to /home.
- /balance is read-only — no destructive actions can happen here.
- /bank-account is destructive — leaving mid-step preserves state via the Notifier; navigating away from the app entirely re-runs loadPayoutAccount on return.
If we extend to a tax-document screen, slot it next to /balance with the same role gate.
Balance / Bank Account Provider Wiring · balanceControllerProvider + bankAccountControllerProvider · NotifierProvider
Two NotifierProviders, neither autoDispose. The bank-account state is intentionally long-lived so the wizard can resume across screen pops; the balance is long-lived so a refresh-on-return is opt-in (pull-to-refresh).
- balanceControllerProvider construction triggers Future.microtask(loadAll).
- bankAccountControllerProvider construction triggers Future.microtask(loadPayoutAccount).
- Both providers expose a refresh() method for pull-to-refresh.
- Switching to autoDispose for bank-account would lose mid-wizard state on a 'back' tap — currently deliberate.
- Tests can override either provider via ProviderScope; service is constructed inline so injection requires a setter.
Both controllers construct StripeService directly — not provider-wrapped today.