Source document · Mobile-app/MOBILE_APP_SRS.md

SB Relaxing Club Kotlin Multiplatform Mobile SRS

Version: 1.0
Status: Implementation baseline
Updated: 25 September 2026
Parent: Product SRS
Backend contract: Go API SRS

1. Purpose and platform direction

This specification defines the Android and iOS customer/provider application. Build it with Kotlin Multiplatform (KMP). Shared Kotlin code owns domain models, API calls, validation, session state, caching, localization access, and feature state. Platform-specific code provides secure storage, push registration, permissions, media pickers, deep links, share sheets, and other OS services. Compose Multiplatform is the preferred shared UI approach where its behavior is suitable; use native platform APIs behind clean interfaces for system integrations.

The API SRS is authoritative for server rules and endpoint behavior. Mobile clients MUST treat API results as authoritative and MUST NOT fabricate successful payment, order, moderation, or role state.

Current integration status: Android fetches service categories and public listings from the Go API, signs in with verified accounts, securely persists rotating sessions, reads scoped order history, and creates server-priced bookings. The booking confirmation flow creates WeChat/Alipay payment attempts and submits them for manual provider verification using method-specific instructions returned by the API. Payment submission is disabled when the server has no instructions configured. Failed catalog requests show an error and retry action instead of sample server data. Provider QR images, Stripe checkout, and iOS UI are not integrated.

2. Supported environments

iOS and Android phone layouts are primary; larger devices remain usable.
Minimum OS targets are set at project setup and verified against store requirements at release.
Network conditions include Wi-Fi, 3G/4G/5G, intermittent connectivity, and offline intervals.
Localized languages: English, Chinese, French, Arabic, Kiswahili, Spanish.
Themes: dark, light, and optionally follow system.

3. Visual and interaction requirements

The reference video is ../API/reference/WhatsApp Video 2026-09-14 at 22.41.28.mp4. It captures existing mobile Home, Find Services, service-item selection, booking form/date picker, order confirmation, My Orders, Profile, and Provider Dashboard flows.

Replicate its visual system: dark charcoal/navy backgrounds as the default; turquoise primary buttons, selected states, and outlines; orange/yellow provider-oriented actions and highlights; rounded bordered cards; circular category icons; compact status pills; muted supporting text with clear hierarchy; full-width primary actions; and persistent bottom navigation. Keep form controls large, rounded, and readable. Date and time selection should feel native to the platform. Avoid placing primary actions behind the keyboard or system insets. Build a shared design-token layer for color, spacing, type scale, corner radius, borders, and elevation, with light-theme counterparts.

The video is a reference for the flows it shows, not a substitute for the complete functional inventory below. Screens not shown must use the same design tokens and interaction patterns.

Accessibility requirements: screen-reader labels and order, minimum platform tap targets, contrast in both themes, dynamic font scaling, reduced-motion respect, keyboard navigation where applicable, and complete RTL mirroring for Arabic (including layout direction, text alignment, icons that imply direction, and navigation gestures).

Primary bottom tabs:

Home
Videos
Chat
Lifestyle
Orders

Secondary routes include Search, Profile, Settings, Provider Dashboard, Notifications, service/listing details, order form/details, chat room, and content details. Android Settings includes privacy/account information and a deliberate, confirmed account deletion action backed by DELETE /api/v1/auth/me. Preserve navigation state sensibly when switching tabs. System back and iOS swipe-back must work. Deep links and push payloads open the relevant authorized destination after session restoration; if authentication is required, retain the destination and resume after login.

Provider-only dashboard entry is shown when the API reports an approved provider profile. Do not infer provider status from a local role flag.

5. Shared KMP module requirements

Organize shared source by feature/domain and keep platform dependencies behind interfaces. Shared module responsibilities:

Typed API client and serialization for the versioned Go API.
Domain types for account, roles, services, providers, listings, menu items, orders, payment state, chat, social content, and notifications.
Input validation for immediate feedback, while recognizing server validation as final.
Repository/state layer with loading, content, empty, offline, retry, and error states.
Secure-session interface whose platform implementations use Keychain and Android Keystore-backed storage.
Local cache for service/catalog data, recent own orders, and recent chat summaries/messages where safe.
Localization resources and locale-aware formatting.
Deep-link parsing and navigation intents.
Upload coordination and progress state.
Workflow state models that cannot imply a server-confirmed transition before the API confirms it.

Keep secrets, password material, access tokens, refresh tokens, and private signed URLs out of logs and ordinary preferences. Use structured cancellation and lifecycle-aware collection so requests stop or resume safely with screens.

6. Authentication and account screens

6.1 Register/login

Registration collects username, email, password, and confirmation; it then displays the email OTP verification step. Include resend countdown/feedback, field errors, password visibility, terms/privacy links, and network retry. Login collects email and password, requests an email OTP, and creates the local session only after the user enters the six-digit code. Login codes can be resent subject to server throttling. Google sign-in uses native platform SDKs with API token exchange. Android includes email OTP password recovery through the API reset endpoints. Logout revokes the session when online and clears local sensitive state. Android Settings exposes account deletion with a confirmation step, calls the authenticated deletion endpoint, and clears the local session after success.

6.2 Guest mode

Guests can browse eligible services and listings and submit supported guest orders. The UI must explain that account-only features (chat/community/provider tools) require sign-in. Guest order confirmation must give a secure way to retrieve the booking according to the API contract; never expose an order by predictable ID.

6.3 Session and deletion

Restore sessions securely at launch. Handle expired/revoked tokens and refresh failures by preserving a safe return destination and asking the user to sign in again. Settings includes permanent account deletion with clear consequences, a deliberate confirmation, re-authentication if required, progress, and a signed-out completion state. Clear sensitive caches after deletion/logout.

7. Home, search, and discovery

Home displays user greeting, notification/profile access, hero banner, Add Your Business entry, service category grid, and featured business listings. Support pull-to-refresh, loading skeletons, empty/error/retry states, image placeholders, and offline indication.

Search supports live text filtering and category filters across services, listings, and providers. Debounce remote queries, preserve query/filter state when opening and returning from detail, and provide clear/reset controls. Results show the correct entity type and available actions.

Service and business detail cards expose menus, item descriptions/prices, provider identity, service category, payment options, and relevant contact/availability. Selecting a menu item updates selection and total visibly. Support selecting multiple items when permitted. Keep total and booking CTA visible and current.

8. Provider registration and listing creation

Provider self-registration captures display name, phone, profile image, bio, categories/services, area/location, WeChat/payment contact where configured, and up to ten portfolio images/videos. Show the API approval/status state and explain any unavailable provider functions while pending.

Business creation/editing captures name, category, description, cover image, menu items and prices, payment QR images, and optional featured choice. Support draft state and multiple listings before payment. Show server-calculated publication fee tier and featured add-on, payment instructions, payment-submitted state, and confirmed/declined outcome. Do not show “published” until the API confirms activation. Show monthly renewal date/status and reminder/suspension notices returned by the API.

9. Booking flow

Use a clear staged flow:

Review service/listing and selected menu items.
Enter name, contact phone, date/time, service address/room, notes, and category-specific fields.
Attach required/optional media: Kuaidi package screenshots/details, printing document, optional WeChat QR, or service-specific evidence.
Review calculated amount and payment choices.
Display provider Alipay/WeChat QR or Stripe option when offered. Manual payment action is explicitly “I have paid”/“Submit payment confirmation”; it does not claim the payment is verified.
Submit once using an idempotency key and show order confirmation only after API success.

Persist a recoverable local draft if the app is interrupted, excluding sensitive payment data where not needed. Prevent accidental duplicate submission while a request is pending, but allow safe retry using the same idempotency key. Show inline validation, upload progress/retry, and clear server errors. Do not lose form state on rotation/process recreation where feasible.

10. Orders and order details

Orders screen groups All, Active, and Completed (with server states mapped clearly). Cards show listing/service, order date, selected items, amount/currency, order status, and payment status separately. Detail view shows complete information and attached files through authorized URLs. Android opens order details and sends versioned cancel/provider workflow transitions to the API. Completed/cancelled orders may be hidden from the customer list without claiming permanent system deletion.

On status changes, refresh or update from server truth and present push/deep-link context. Offline state may show cached data but must identify it as stale and disable unsupported mutations.

11. Provider Dashboard

Provider Dashboard includes incoming/action-required orders, active orders, completed orders, customer chats, sales summary, and manual/off-platform order creation. Order cards show customer, listing/items, requested time, amount, order/payment states, and available action. Confirm/complete/cancel controls require API authorization and show pending state until successful. Completion refreshes order, completed history, sales, and notification state. Guard against double taps and conflict responses.

Manual order form captures required sale/order details and explicitly labels the entry as off-platform. Android records manual sales through the provider-scoped API endpoint and shows confirmation only after API success. Where owner/contact pairing is enabled, present both authorized contacts without exposing private data publicly.

12. Chat

Chat list is sorted by recent activity and displays last-message preview, timestamp, and unread badge. Chat room supports paginated history, text, image/video attachment, read state, retry, and near-real-time incoming messages. Use local optimistic bubbles only with clear sending/failed states and stable client message IDs. Reconnect to real-time channel and fetch missed history after network loss. Push opens the correct conversation. Only conversation participants can access attachments or messages.

13. Videos and Moments

13.1 Short video

Provide a vertical feed that autoplays the visible item, pauses off-screen items, preloads modestly, respects mute/system accessibility settings, and releases decoders/resources as items leave view. Display creator, caption, like/comment/share controls, and view count when available. Upload flow selects/captures video, accepts title/description/thumbnail, shows progress/retry, and surfaces moderation/processing state. Sharing uses native share sheet and records a share event only according to API contract.

13.2 Moments

Lifestyle Moments feed supports text, one or more images/videos, optional location consent, likes, comments, and China Place type if enabled. Android currently uploads one selected image per moment through an owner-authorized signed URL and displays attached images using short-lived signed read URLs; video and multi-image composition remain in progress. Composer previews/reorders/removes attachments, supports upload progress, and asks for location only after explaining its use. Provide report/block actions and respect moderation/visibility responses.

14. Lifestyle features

Before gated features, display an opt-in registration step for selected sections (Moments, live, books/comics, dating as configured). Dating profile creation/editing includes display name, age, gender, country, looking-for, biography, interests, main image, extra media, and contact settings. Clearly communicate profile visibility and provide hide/delete/report/block controls. Enforce server-provided eligibility and visibility; do not expose contact fields in cached public lists.

Curated music, comics, games, books/stories, and Entertainment links are browsable by category. External links open using a safe browser mechanism and validate scheme. Audio uses a mini-player if enabled, with play/pause, progress, track title, and background behavior subject to platform permissions and audio-focus rules.

15. Meetings and livestreams

Meeting room list supports browse/create/join, participant state, and host end action. Android joins/leaves and lets the host end meetings through authorized API routes. Authorized join returns a short-lived room-scoped LiveKit token; Android connects through LiveKit, requests camera/microphone permissions, renders local and remote camera tracks, and supports mute/camera-off controls plus audio-only/read-only permission fallback. Leave the provider room and API participation together. Show network/reconnecting states and recover permission denial through app settings.

Livestream UI includes live status, title, viewer count, like/comment interaction, and leave action. Stream creation appears only when API eligibility allows it. Viewer and host states are distinct. If recordings are available, expose them only after API publication and moderation approval. Handle interruptions, backgrounding, incoming calls, and poor network gracefully.

16. Profile, settings, and notifications

Profile shows editable display name, username, photo, account state, and provider entry/dashboard. Android currently edits username and display name through the authenticated profile update endpoint. Settings includes theme, language, notification preferences, privacy/terms, account deletion, app version, and sign-out. Android light/dark theme selection applies immediately and persists on device; locale selection is persisted across English, Chinese, French, Arabic, Kiswahili, and Spanish; common navigation and booking/auth/community labels are translated, and Arabic uses RTL layout. Translation coverage for all screen content and notification preference controls remains in progress.

Register APNs/FCM token after permission/login as appropriate, handle token refresh, unregister on logout where supported, and reflect denied permission without blocking other features. Notification preferences are synchronized with API. Deep links are validated and require a fresh authorization check when loading private data.

17. Native capability requirements

Provide small platform interfaces for:

Secure token storage.
Camera capture and photo/video library picker.
Document picker, especially printing files.
Camera/microphone/photo/location/notification permission state and explanations.
APNs and FCM registration.
Native share sheet.
Deep links/universal links/app links.
WebRTC media and audio focus.
Network connectivity and background/resume events.

If permission is denied, only the related capability is disabled; unrelated app areas remain available. Request location only when the user explicitly invokes a location feature. Respect iOS and Android permission changes after returning from system Settings.

18. Offline, caching, and error behavior

Cache public catalog/listings, recent own orders, and recent chat data with appropriate expiry. Mark cached content and stale status. Never cache private media beyond an approved policy. Queue only operations explicitly safe to retry (such as unsent chat drafts) and preserve idempotency identity. Order submission/payment transitions are not reported complete until the API confirms. Provide retry controls, inline errors, empty states, and global offline status. Avoid blank screens and destructive loss of composed forms.

19. Performance and privacy

Cold start target under 3 seconds to usable Home on a representative mid-range device over 4G.
Cached search response target under 300 ms.
Smooth feed scrolling with thumbnail-first loading and bounded media prefetch.
Show upload progress and allow retry.
Keep access/refresh tokens in secure storage; no credentials in logs or analytics.
Request only needed permissions and explain each before the system prompt.
Follow store privacy declarations and data retention policy; provide account deletion in-app.

20. Testing and acceptance

Release acceptance covers both platforms and at least Guest, Member, Provider, Accountant (web-only access validation), and Admin (web-only access validation) scenarios. Mobile checks include:

Authentication, OTP, Google sign-in, reset, refresh, logout, deletion, and guest booking.
Home/search/detail/menu selection and the visual flow shown in the reference video.
Booking with date/time, category attachments, manual QR payment submission, optional Stripe where enabled, and confirmation.
Customer order history, status/payment separation, cancellation/hide rules, and deep links.
Provider registration, business creation/payment state, dashboard, completion, sales refresh, and manual order entry.
Chat delivery, unread/read updates, attachments, reconnect, and push route.
Video/Moments composition, playback/feed behavior, upload retry, reporting/blocking, and moderation states.
Meeting permissions, join/leave/end, reconnect, and denied permissions; livestream eligibility and viewer flow if launch-enabled.
Arabic RTL, all six locales, light/dark themes, font scaling, accessibility navigation, and poor/offline network states.
Push and deep links on physical iOS and Android devices.

21. Open decisions

Minimum iOS/Android versions and Compose Multiplatform UI coverage.
Guest booking verification and post-booking recovery UX.
Stripe launch scope and supported service categories.
Exact cancellation/refund UX and policy.
Dating age/contact/matching policy and moderation controls.
Livestream eligibility and recording availability.
Offline message-send policy and local cache retention period.
Provider-pair profile editing and account ownership behavior.