Skip to main content

User Flows

Detailed user journey maps for all personas in the Talbino marketplace.

Flow 1: New User Registration​

Actor: Any user (Buyer or Seller)

1. Open app → Welcome screen
2. Tap "Get Started"
3. Enter phone number
4. Tap "Send Code"
5. Receive SMS with 6-digit OTP
6. Enter OTP code
7. System verifies → Creates user account
8. Complete profile:
   - Name
   - Profile photo (optional)
   - Preferred language (Arabic/English)
9. → Buyer home screen (default)

Success Criteria: User can complete registration in <60 seconds

Flow 2: Buyer Posts Buy Request​

Actor: Buyer

Precondition: User is logged in

1. Home screen → Tap "Post Request" button
2. Select category:
   - Used Phone
   - Accessory
3. Fill product details:
   - Brand (dropdown)
   - Model (text input)
   - Condition preference (dropdown: New, Like New, Good, Acceptable, Any)
4. Set budget:
   - Min price (number)
   - Max price (number)
5. Set location:
   - District (dropdown: Cairo/Giza districts)
6. Add notes (optional text)
7. Review summary
8. Tap "Post Request"
9. System creates request with status=active
10. → Success screen: "Your request is live!"
11. → View request detail screen

Success Criteria:

  • Complete in <30 seconds
  • Request appears in "My Requests" immediately
  • Request visible to approved sellers immediately

Analytics Events:

  • request_started
  • request_category_selected
  • request_submitted
  • request_created

Flow 3: Seller Browses & Makes Offer​

Actor: Seller

Precondition: Seller profile approved

1. Seller home → "Browse Requests" tab
2. View list of active requests:
   - Product summary
   - Budget range
   - Location
   - Time posted
   - Offer count
3. Apply filters (optional):
   - Category
   - Location
   - Budget range
4. Tap request → View full details
5. Tap "Make Offer" button
6. Fill offer form:
   - Price (number, must be within budget range)
   - Availability (text: "Immediate", "2 days", etc.)
   - Condition notes (text)
   - Warranty notes (optional text)
7. Review offer
8. Tap "Submit Offer"
9. System validates:
   - Request status = active ✓
   - Seller status = approved ✓
   - Price within budget ✓
10. System creates offer with status=pending
11. System increments request.offer_count
12. System sends push to buyer: "New offer on your request!"
13. → Success screen: "Offer submitted!"
14. → Offer detail screen

Success Criteria:

  • Offer submission <2s
  • Buyer receives push notification <5s
  • Offer appears in buyer's offer list immediately

Analytics Events:

  • request_viewed
  • offer_started
  • offer_submitted
  • offer_created

Flow 4: Buyer Views & Compares Offers​

Actor: Buyer

Precondition: Request has ≥1 offer

1. Receive push: "New offer on your request!"
2. Tap notification → Opens request detail
3. View offers list:
   - Seller name + rating
   - Price
   - Availability
   - Condition notes
   - Time submitted
4. Sort/filter offers:
   - Lowest price
   - Highest rated seller
   - Most recent
5. Tap offer → View full offer details:
   - All offer fields
   - Seller profile (rating, bio, location)
6. Options:
   - "Chat with Seller"
   - "Accept Offer"
   - "Back to offers"

Success Criteria:

  • Easy comparison of 3-5 offers
  • Clear seller trust signals (rating visible)

Flow 5: Chat Conversation​

Actor: Buyer or Seller

Precondition: Offer exists

1. From offer detail → Tap "Chat with Seller"
2. System checks if conversation exists:
   - If yes: Open existing conversation
   - If no: Create new conversation (unique per offer_id)
3. Chat screen shows:
   - Other party name + avatar
   - Message history (newest at bottom)
   - Text input field
   - Send button
4. User types message → Tap send
5. System creates message record
6. System sends real-time message via WebSocket
7. System sends push to other party if app in background
8. Other party receives message in real-time
9. Message marked as read when viewed

Success Criteria:

  • Message delivery <1s
  • Push notification if recipient offline <5s
  • Conversation persists across app restarts

Analytics Events:

  • chat_opened
  • message_sent
  • message_received

Flow 6: Buyer Accepts Offer​

Actor: Buyer

Precondition: Request has ≥1 pending offer

1. Buyer reviews offers
2. Selects best offer → Tap "Accept Offer"
3. Confirmation dialog: "Accept this offer? Other offers will be rejected."
4. Tap "Confirm"
5. System executes transaction:
   a. Create deal record (status=accepted)
   b. Update accepted offer (status=accepted)
   c. Update all other offers (status=rejected)
   d. Update request (status=closed, closed_at=now)
6. System sends notifications:
   - To seller: "Your offer was accepted!"
   - To other sellers: "Request closed"
7. → Deal detail screen
8. Chat remains active for coordination

Success Criteria:

  • Atomic transaction (all or nothing)
  • All parties notified <5s
  • Deal appears in "My Deals" for both parties

Analytics Events:

  • offer_accepted
  • deal_created
  • request_closed

Flow 7: Deal Completion & Rating​

Actor: Buyer

Precondition: Deal exists with status=accepted

1. Buyer and seller coordinate meetup via chat
2. Meetup happens (offline)
3. Buyer opens deal detail
4. Tap "Mark as Completed" or "Cancel Deal"

--- If Completed ---
5a. Confirmation: "Did you complete this deal?"
6a. Tap "Yes, Completed"
7a. System updates deal (status=completed, completed_at=now)
8a. → Rating screen appears:
    - Seller name + avatar
    - Star rating (1-5)
    - Review text (optional)
9a. Tap "Submit Rating"
10a. System creates rating record
11a. System updates seller_profiles:
     - Recalculate rating_avg
     - Increment rating_count
12a. → Success: "Thanks for your feedback!"

--- If Cancelled ---
5b. Confirmation: "Cancel this deal?"
6b. Select reason (dropdown):
    - Seller didn't show
    - Changed my mind
    - Found better deal
    - Other
7b. Optional: Add description
8b. Tap "Cancel Deal"
9b. System updates deal (status=cancelled, cancelled_at=now)
10b. → Deal marked cancelled

Success Criteria:

  • Rating updates seller profile immediately
  • Cancelled deals don't affect seller rating
  • Buyer can report issues separately

Analytics Events:

  • deal_completed
  • deal_cancelled
  • rating_submitted

Flow 8: Buyer Reports Seller​

Actor: Buyer

Precondition: Deal exists

1. Deal detail screen → Tap "Report Issue"
2. Select reason:
   - Fake offer
   - Seller didn't show
   - Rude behavior
   - Scam attempt
   - Other
3. Add description (optional)
4. Tap "Submit Report"
5. System creates report (status=pending)
6. System notifies admin
7. → Confirmation: "Report submitted. We'll review within 24h."
8. Admin reviews in admin panel
9. Admin takes action:
   - Resolve (no action)
   - Warn seller
   - Suspend seller
10. System updates report (status=reviewed)

Success Criteria:

  • Report submission <2s
  • Admin notified immediately
  • Buyer receives confirmation

Analytics Events:

  • report_created
  • report_reviewed

Flow 9: Seller Registration & Approval​

Actor: User wanting to become seller

Precondition: User account exists

1. User profile → Tap "Become a Seller"
2. Fill seller profile form:
   - Business name (optional)
   - Location (district + city)
   - Bio (text)
3. Tap "Submit for Approval"
4. System creates seller_profile (status=pending)
5. → Waiting screen: "Your application is under review"
6. Admin receives notification
7. Admin reviews in admin panel:
   - View profile details
   - Check user history
   - Approve or Reject
8. System updates seller_profile:
   - If approved: status=approved, approved_at=now
   - If rejected: status=rejected
9. System sends push to user:
   - "Congratulations! You're approved to sell."
   - "Your seller application was not approved."
10. If approved → Seller can now browse requests and make offers

Success Criteria:

  • Application submission <2min
  • Admin review within 24-48h
  • User notified of decision

Analytics Events:

  • seller_application_started
  • seller_application_submitted
  • seller_approved
  • seller_rejected

Flow 10: Admin Moderates Content​

Actor: Admin

Precondition: Admin logged in to admin panel

--- Seller Approval Queue ---
1. Admin dashboard → "Pending Sellers" widget
2. View list of pending applications
3. Click seller → View details:
   - User info
   - Business name
   - Location
   - Bio
   - Registration date
4. Decision:
   - Approve → Seller can start offering
   - Reject → Seller cannot offer
5. System updates seller_profile
6. System sends notification to user

--- Report Review ---
1. Admin dashboard → "Pending Reports" widget
2. View list of pending reports
3. Click report → View details:
   - Reporter info
   - Reported seller info
   - Deal details
   - Reason + description
4. Decision:
   - Resolve (no action)
   - Warn seller (manual message)
   - Suspend seller (status=suspended)
5. System updates report (status=reviewed)
6. If suspended → Seller cannot make new offers

--- Marketplace Metrics ---
1. Admin dashboard → View KPIs:
   - Active requests count
   - Offers per request (avg)
   - Deal completion rate
   - Seller approval queue size
   - Reports pending count

Success Criteria:

  • Admin can process 10+ sellers/hour
  • Admin can review 5+ reports/hour
  • Clear audit trail of all actions

Edge Cases & Error Handling​

Request Creation Fails​

  • Cause: Network error, validation error
  • Handling: Show error message, save draft locally, retry

Offer Submission on Closed Request​

  • Cause: Request closed between view and submit
  • Handling: Show error: "This request is no longer active"

Multiple Offers Accepted Simultaneously​

  • Cause: Race condition (unlikely)
  • Handling: Database constraint prevents, first wins, others get error

Chat Message Fails to Send​

  • Cause: Network error, WebSocket disconnected
  • Handling: Queue message locally, retry, show "Sending..." indicator

Push Notification Not Received​

  • Cause: Device token expired, permissions denied
  • Handling: Fallback to in-app polling, prompt user to enable notifications

Seller Suspended Mid-Deal​

  • Cause: Admin suspends seller
  • Handling: Existing deals continue, new offers blocked

Buyer App Navigation​

Home (Requests List)
├── Post Request → Request Form → Success → Request Detail
├── My Requests → Request Detail
│   └── Offers List → Offer Detail
│       ├── Chat
│       └── Accept → Deal Detail
├── My Deals → Deal Detail
│   ├── Chat
│   ├── Complete → Rating
│   ├── Cancel
│   └── Report
└── Profile
    ├── Edit Profile
    ├── Settings (Language)
    └── Become Seller → Seller Application

Seller App Navigation​

Home (Browse Requests)
├── Request Detail → Make Offer → Offer Form → Success
├── My Offers → Offer Detail
│   └── Chat
├── My Deals → Deal Detail
│   └── Chat
└── Profile
    ├── Edit Profile
    ├── My Ratings
    └── Settings

Admin Web Navigation​

Dashboard
├── Seller Approvals → Seller Detail → Approve/Reject
├── Reports → Report Detail → Review/Action
├── Metrics & Analytics
└── System Settings