Prontua Mobile-First App Scope — Capture-to-Review Flow Spec

Date: 2026-03-29 | Agent: Design Lead | Issue: MOKA-605 | Confidence: High

Executive Summary

• Decision: ship the Phase 1 app as React Native + Expo development builds (not Expo Go), with react-native-ble-plx for BLE setup and WebSocket streaming status.
• The core UX is a 5-screen mobile path optimized for a veterinarian holding a phone during consults: Home -> Active Consult -> Processing -> Note Review -> Export.
• Home now includes credit balance + buy credits CTA to support pay-per-note billing (R$3.90 per note) via credit packs.
• First-run experience now defaults to a phone-only 30-note trial (no paired hardware required), with an explicit “preview quality” disclaimer.
• Hardware UX uses clear, redundant signals: device LED + phone UI + push notification fallback, so consult state is always visible.
• Flow is designed for imperfect clinic connectivity: local draft persistence, reconnect handling, and explicit “processing may continue in background” messaging.
• Flutter is a valid fallback, but RN+Expo is recommended for speed and direct fit with existing Moklabs TypeScript workflows.

Scope and Constraints

• Target user: solo/small-clinic veterinarians in Brazil using phones during consults.
• Monetization context: pay-per-note (R$3.90) with prepaid credit packs (for example, R$50 wallet top-ups).
• First-run trial requirement: user can start capture immediately with phone mic for up to 30 notes before pairing a room device.
• Device: XIAO ESP32S3 Sense, with single button + status LED.
• Phase 1 objective: capture consult audio, process transcript/LLM note, review/edit SOAP note on mobile, export/share.
• Out of scope for this phase: PIMS deep integration, advanced fleet management, tablet-specific redesign.

Mobile UX Flow (5 Wireframes)

1. Home (Clinic Ready)

+------------------------------------------------+
| Prontua                              [Profile] |
|------------------------------------------------|
| Credits: R$50.00 (12 notes est.) [Buy Credits] |
| Device: Connected (Room 2)      LED: Green     |
| Battery: 82%                     Wi-Fi: Stable |
|------------------------------------------------|
| [ Start New Consult ]                           |
| [ Use Phone Mic (Trial) ]                      |
|                                                |
| Recent Consults                                 |
| - Nala (13:40)   Draft note ready              |
| - Thor (11:10)   Exported to WhatsApp          |
|------------------------------------------------|
| Bottom Nav: Home | Consults | Settings         |
+------------------------------------------------+

Interaction notes:

• Primary CTA is always visible: Start New Consult.
• Credit balance is always visible on Home so the vet never starts a consult without price clarity.
• Buy Credits opens a one-screen pack picker (R$50, R$100, R$200) with Pix first and card fallback.
• Hardware status card is persistent and color-mapped to physical LED state.
• If device is offline, CTA swaps to Reconnect Device.

2. Active Consult (Live Capture)

+------------------------------------------------+
| Active Consult                         00:12:34 |
|------------------------------------------------|
| [ REC ] Recording from Phone Mic (Trial Mode)  |
| Audio level: |||||||||--                       |
| Last packet: 2s ago                            |
|------------------------------------------------|
| Quick Notes (optional)                         |
| [ Limping rear leg, appetite down ]            |
|------------------------------------------------|
| [ Pause ]                    [ End Consult ]   |
|------------------------------------------------|
| Tip: You can also end from device button       |
+------------------------------------------------+

Interaction notes:

• Top bar timer confirms session is active.
• Source badge (Phone Mic or Room Device) is persistent during recording.
• In phone trial mode, show non-blocking disclaimer: Preview quality only. For best accuracy, pair Prontua device.
• End Consult requires confirm sheet to prevent accidental termination.
• If connection drops, app shows sticky warning but keeps local consult context.

3. Processing (Transcript + SOAP generation)

+------------------------------------------------+
| Processing Consult                             |
|------------------------------------------------|
| Step 1/3  Uploading audio         [#####---]   |
| Step 2/3  Speech-to-text          [###-----]   |
| Step 3/3  SOAP draft generation   [#-------]   |
|------------------------------------------------|
| Estimated time: 1-3 min                        |
| You can leave this screen; we'll notify you.   |
|------------------------------------------------|
| [ View Transcript (live) ]                     |
| [ Back to Home ]                               |
+------------------------------------------------+

Interaction notes:

• Shows deterministic pipeline states to build trust.
• Allows backgrounding; user gets notification when note is ready.
• On failure, retry action is scoped to failed step only.

4. Note Review (Inline Edit)

+------------------------------------------------+
| SOAP Review - Bella                            |
|------------------------------------------------|
| S: Owner reports low appetite, lethargy...     |
| [Edit]                                         |
|------------------------------------------------|
| O: Temp 39.5C, mild dehydration...             |
| [Edit]                                         |
|------------------------------------------------|
| A: Possible gastroenteritis...                 |
| [Edit]                                         |
|------------------------------------------------|
| P: Fluid therapy, antiemetic, return 48h...    |
| [Edit]                                         |
|------------------------------------------------|
| [ Save Draft ]      [ Approve Note ]           |
+------------------------------------------------+

Interaction notes:

• Section-by-section editing is faster than full-text editing on mobile.
• Confidence highlights (yellow underline) mark uncertain segments from transcript.
• Approve action locks version and creates export-ready payload.

5. Export (Share and Close)

+------------------------------------------------+
| Export Note                                    |
|------------------------------------------------|
| Consult: Bella - 14:05                         |
| Status: Approved                               |
|------------------------------------------------|
| [ Send via WhatsApp ]                          |
| [ Copy to Clipboard ]                          |
| [ Download PDF ]                               |
| [ Email to Clinic ]                            |
|------------------------------------------------|
| Follow-up reminder                              |
| [ + Set 7-day check-in ]                       |
|------------------------------------------------|
| [ Done ]                                       |
+------------------------------------------------+

Interaction notes:

• WhatsApp is first to match Brazil workflow reality.
• Export actions are one-tap, no modal maze.
• “Done” returns to Home with success toast and consult archive update.

Hardware Interaction UX Spec

First-Run Experience (Phone-Only Trial)

1. New user lands on Home with no paired device.
2. App displays trial entry card: Start your 30 free notes using phone mic.
3. User taps Use Phone Mic (Trial) and starts consult immediately.
4. After each completed note, app decrements trial_notes_remaining.
5. At 10 notes remaining, app adds persistent upsell banner: Pair device for higher capture quality.
6. On trial exhaustion, app gates new consults behind either Buy Credits or Pair Device.

Required first-run microcopy:

• No device needed to start. Use your phone mic for trial notes.
• Preview quality may vary with room noise and distance.
• For best SOAP accuracy, pair Prontua room device.

Device state model

Device State	LED on Device	Phone Banner	User Meaning
Idle/ready	Solid green	”Device connected”	Safe to start consult
Pairing mode	Blue pulse	”Pairing in progress”	Complete setup on phone
Recording	Solid red	”Recording live” + timer	Audio is being captured
Processing/upload	Blue blink	”Processing consult”	Capture ended; cloud pipeline running
Error/disconnected	Red blink	”Connection issue” + recover CTA	Requires attention

Button behavior (single physical button)

Action	Duration	Result
Short press	<1s	Start consult if idle; end consult if recording
Long press	3s	Enter pairing mode (BLE advertise)
Long press (while error)	8s	Soft reset + Wi-Fi reconnect

Pairing and setup flow

1. User taps Add Device in app (optional during trial; required for room-device capture mode).
2. App scans BLE peripherals and filters Prontua-* IDs.
3. User selects device, confirms clinic room label.
4. App sends Wi-Fi credentials securely during setup session.
5. Device validates cloud reachability, then moves to Idle/ready.

Notification and interruption behavior

• If consult ends from hardware button, app receives session-close event and opens Processing state.
• If app is backgrounded, local notification announces SOAP draft ready.
• If processing exceeds threshold (e.g., 4 min), app shows delayed-status message and non-blocking retry option.

Tech Stack Recommendation

Decision summary

Recommend: React Native (TypeScript) + Expo SDK (development builds) + react-native-ble-plx.

Decision matrix

Criteria	React Native + Expo	Flutter	Native (Swift + Kotlin)
BLE pairing ecosystem	Strong (needs dev build + native plugin)	Strong (good plugin ecosystem)	Strongest, highest effort
Team velocity for MVP	Highest for current Moklabs stack	Medium	Lowest
Realtime WS + state mgmt	Native support + mature libs	Native support + mature libs	Native support
Offline draft persistence	expo-sqlite persisted DB	SQLite patterns documented	Native DB per platform
Cross-platform consistency	High	High	Low (two codebases)
Total build complexity	Medium	Medium	High

Rationale (source-backed)

• Expo explicitly allows custom native libraries in development builds and config plugins; this is required for BLE-heavy apps (Expo docs).
• react-native-ble-plx supports Expo via plugin config and background options, but is not usable in Expo Go.
• React Native 0.82+ is now fully New Architecture; Expo SDK 55 aligns with that path, reducing legacy migration debt.
• expo-sqlite gives persistent local storage across restarts and supports SQLCipher when needed.
• WebSocket support exists directly in React Native and Flutter; no stack blocker here.

Proposed app architecture (Phase 1)

• presentation: Expo Router screens for the 5-step flow.
• domain:
  • consult session state machine (idle, recording, processing, ready, error)
  • capture source mode (phone_trial, room_device)
  • credits wallet (balance_brl, cost_per_note, notes_remaining_estimate)
• infra:
  • BLE adapter: scan, pair, state sync.
  • Realtime adapter: WebSocket consult status.
  • Local store: SQLite for draft SOAP + unsent events.
  • Notification adapter: local push for processing completion.
  • Payments adapter: Pix-first checkout for credit packs, card fallback.

Risks and Mitigations

Risk	Impact	Mitigation
BLE permission edge cases across Android versions	High	Permission preflight, explicit rationale UI, retry scanner flow
Background behavior mismatch (iOS vs Android)	Medium	Keep critical transitions server-driven + local notifications
Credit depletion surprise mid-consult	High	Reserve one-note cost at consult start; clear balance + low-credit banner on Home
Overloading MVP with too many export channels	Medium	Lock Phase 1 export to WhatsApp, PDF, clipboard
UX confusion between recording vs processing	High	Use synchronized LED + app state labels with distinct color semantics

Build Recommendation (Go/No-Go)

1. Should Moklabs build this app flow now? Go.
2. What exactly to build first? The 5-screen flow above with phone-only trial entry, credits wallet/buy flow, hardware pairing, consult lifecycle, SOAP review/edit, and WhatsApp/PDF export.
3. Who is buyer/user? Owner-operator and small-clinic vets who directly feel documentation burden.
4. Why now? Mobile-first aligns with field workflow and avoids early dashboard overhead.
5. What kills it? Unreliable BLE onboarding, poor transcript confidence visibility, or export friction.

Discord Summary Draft (copy/paste)

<@167093005059227648> <@611903174810533891>

Prontua mobile-first scope updated for MOKA-605.

What is now defined:
- 5-screen mobile flow: Home -> Active Consult -> Processing -> SOAP Review -> Export
- B2C additions: credit balance on Home + Buy Credits flow (Pix-first)
- First-run funnel: phone-only 30-note trial with preview-quality disclaimer
- Hardware UX spec: LED state system + one-button behavior + BLE pairing flow
- Tech stack recommendation: React Native + Expo dev build + react-native-ble-plx + WebSocket + local SQLite

Why this direction:
- Matches solo-vet phone-first behavior
- Keeps hardware + mobile tightly coupled for POC trust
- Fastest path to ship with our current TS/React strengths

Deliverable report:
- reports/product-strategy/2026-03-29-prontua-mobile-first-app-scope.md

Sources

• https://docs.expo.dev/workflow/customizing/ (Tier A, official Expo docs; custom native code + development builds)
• https://docs.expo.dev/guides/new-architecture/ (Tier A, official Expo docs; SDK 55/New Architecture status)
• https://reactnative.dev/blog/2025/10/08/react-native-0.82 (Tier A, official React Native release notes)
• https://reactnative.dev/docs/global-WebSocket (Tier A, official React Native API docs)
• https://docs.expo.dev/versions/latest/sdk/sqlite/ (Tier A, official Expo docs; persistence + SQLCipher)
• https://github.com/dotintent/react-native-ble-plx (Tier B, primary OSS library docs for RN BLE)
• https://docs.flutter.dev/cookbook/networking/web-sockets (Tier A, official Flutter docs)
• https://docs.flutter.dev/app-architecture/design-patterns/offline-first (Tier A, official Flutter architecture docs)
• https://pub.dev/packages/flutter_blue_plus (Tier B, primary plugin docs for Flutter BLE)
• https://developer.android.com/develop/connectivity/bluetooth/bt-permissions (Tier A, official Android BLE permission model)
• https://developer.apple.com/library/archive/documentation/NetworkingInternetWeb/Conceptual/CoreBluetooth_concepts/CoreBluetoothBackgroundProcessingForIOSApps/PerformingTasksWhileYourAppIsInTheBackground.html (Tier A, official Apple BLE background behavior)

Quality Scorecard

Dimension	Score	Notes
Sources (20%)	16/20	11 sources; mostly official docs
Quantified claims (20%)	12/20	Limited numeric claims; mostly implementation guidance
Competitive depth (15%)	12/15	RN vs Flutter vs Native matrix
Actionability (20%)	20/20	Direct wireframes, stack call, hardware states, credits/trial UX
Recency (10%)	9/10	Majority sources updated in 2025-2026
Counter-arguments (15%)	15/15	Explicit risks/kill conditions included
Total	87/100	Pass