Skip to main content

Swopix — Features & User Flow Documentation

Last updated: May 5, 2026

Table of Contents​

  1. App Concept
  2. User Personas
  3. Feature Overview
  4. User Flows
  5. Navigation Structure
  6. Trust & Safety System
  7. Feature Status Matrix
  8. Planned / Unimplemented Features

1. App Concept​

Swopix is a verified college campus marketplace where students can:

  • Buy items from other verified students
  • Sell items they no longer need
  • Rent items for short-term use (textbooks, electronics, furniture, equipment)

The core differentiator is trust through verification: every user must verify their student ID before transacting. A Trust Score system rewards reliable behavior (on-time returns, good condition, responsive communication).

The marketplace is town-scoped: users see listings from colleges in their geographic area, detected via GPS. This keeps transactions local and meetup-friendly.

2. User Personas​

New Student (First-Time User)​

  • Downloads app, goes through onboarding
  • Creates account via phone/email/Google/Apple
  • Selects their college (GPS-assisted)
  • Submits student ID for verification (24–48 hour review)
  • Browses marketplace while awaiting verification

Verified Buyer​

  • Browses listings by category, price, college
  • Views listing details, contacts seller via in-app chat
  • Initiates rental with duration selection and deposit
  • Manages active rentals, marks items as returned
  • Rates sellers after completed transactions

Verified Seller/Lender​

  • Creates listings with photos, description, pricing
  • Sets item as for sale, for rent, or both
  • Receives messages from interested buyers
  • Manages active rentals, confirms returns
  • Builds trust score through successful transactions

3. Feature Overview​

FeatureDescriptionStatus
Onboarding Slides3-slide feature introduction✅ Complete
Phone OTP AuthSMS-based login with 6-digit OTP⚠️ Service implemented, no UI
Google Sign InOAuth via Google✅ Firebase wired
Apple Sign IniOS-only Apple ID login✅ Firebase wired (iOS only)
Email/Password AuthTraditional email login✅ Firebase wired
College SelectionGPS-based college detection and selection✅ UI complete, real GPS
Student ID VerificationCamera capture of front/back ID✅ Firebase Storage upload
Admin PanelReview/approve/reject ID verifications✅ Fully implemented
Marketplace BrowseGrid listing view with search and filters✅ Firestore integrated
Category Quick-LinksHorizontal scrollable category chips✅ Implemented
SearchDebounced text search across title/description✅ Implemented (local filter)
Advanced FiltersCategory, price range, college, availability type⚠️ UI complete — RadioGroup crash
Listing DetailsFull item view with images, description, seller⚠️ Ignores route args (GAP-29)
Image CarouselSwipeable photo gallery✅ Implemented
Save/Bookmark ListingSave listings for later⚠️ UI only — no Firestore persist
Share ListingNative share sheet✅ Implemented
Buy Now (Razorpay)Purchase flow with payment⚠️ Payment works, listing not marked sold
Rent (Razorpay)Rental flow with payment⚠️ Payment works, rental not created in Firestore
Create ListingMulti-step form with photo upload✅ Firestore write works
Content ModerationKeyword filter before listing submission⚠️ Service ready, never called
Draft SavingAuto-save listing draft⚠️ Hook exists, not implemented
Chat InboxList of all conversations⚠️ Mock data only (GAP-02)
Individual ChatReal-time messaging with typing indicator⚠️ Mock data only (GAP-03)
Quick Action ChipsPre-filled message shortcuts✅ Implemented
Image Sharing in ChatSend photos in messages✅ UI complete
Rental InitiationSelect rental duration, confirm with deposit⚠️ Payment works, no Firestore record
Active Rental TrackingCountdown timers, overdue detection⚠️ UI complete, no real data
Rental ExtensionExtend rental period⚠️ Hardcoded prices, no persistence
Mark as ReturnedConfirm item return✅ Firestore write
Rental HistoryPast completed rentals✅ Firestore integrated
User RatingRate users after rental completion⚠️ UI complete, local state only
Trust Score DisplayScore with breakdown bottom sheet✅ UI complete
Trust Score CalculationRecalculate after transactions⚠️ Service ready, never called
Profile ViewUser info, stats, verification status✅ Firestore read
Avatar UploadUpdate profile photo⚠️ Stub — "coming soon" snackbar
Verification StatusPending/approved/rejected states✅ Implemented
Settings ScreenApp preferences (currency, language, privacy)⚠️ UI complete, prefs not applied
Support ScreenHelp & contact options⚠️ All options are stubs
LogoutSession termination with confirmation✅ Implemented
Push NotificationsReal-time alerts❌ Not started

4. User Flows​

4.1 Onboarding & Registration​

App Launch
    │
    ▼
SplashScreen (2–3 seconds)
    │  Animated logo + initialization status messages
    │  Checks auth state (currently always → Onboarding)
    │
    ▼
OnboardingScreen
    │  Slide 1: "Verified College Community"
    │  Slide 2: "Buy, Sell & Rent"
    │  Slide 3: "Trust Score System"
    │  [Skip] button on slides 1 & 2
    │  [Next Step] → next slide
    │  [Get Started] on slide 3
    │
    ▼
AuthenticationScreen

Key UX Details:

  • Onboarding can be skipped at any point via the "Skip" button (top right)
  • Page indicator dots expand on active slide
  • Slide images load from Unsplash URLs with fallback to no-image.jpg
  • Haptic feedback on page swipe and button taps

4.2 Authentication​

AuthenticationScreen
    │
    ├── [Continue with Phone] ──────────────────────────────┐
    │       Shows InternationalPhoneNumberInput              │
    │       [Send OTP] → OTP verification view              │
    │           Pinput 6-digit entry                        │
    │           60-second resend countdown                  │
    │           [Resend Code] after timer                   │
    │           Auto-submit on 6th digit                    │
    │           ──────────────────────────────────────────► │
    │                                                        │
    ├── [Continue with Google] ──────────────────────────── ┤
    │       Simulated 2-second delay                        │
    │       ──────────────────────────────────────────────► │
    │                                                        │
    ├── [Continue with Apple] (iOS only) ────────────────── ┤
    │       SignInWithApple.getAppleIDCredential()          │
    │       ──────────────────────────────────────────────► │
    │                                                        │
    └── [Sign in with Email instead] ───────────────────── ┤
            Shows email + password fields                   │
            [Sign In] button                               │
            ──────────────────────────────────────────────► │
                                                            │
                                                            ▼
                                              CollegeSelectionScreen

Key UX Details:

  • Phone is the primary/hero method (full-width, elevated button)
  • Error messages appear inline below the auth card
  • Loading spinner replaces button content during async operations
  • Terms of Service and Privacy Policy links at bottom (no-op currently)

4.3 College Verification​

CollegeSelectionScreen (Step 2 of 4)
    │
    ├── Location Permission NOT granted
    │       Shows LocationPermissionCard
    │       [Enable Location] → Permission.location.request()
    │           ├── Granted → load colleges
    │           ├── Permanently denied → Settings dialog
    │           └── Denied → inline error message
    │
    └── Location Permission granted
            Detects town via GPS (mock: "Springfield")
            Shows CollegeDropdownField with filtered colleges
            User selects college from searchable dropdown
            [Continue to ID Verification] (enabled only when college selected)
                │
                ▼
            IdVerificationScreen

Key UX Details:

  • Pull-to-refresh re-checks location permission
  • App lifecycle observer auto-detects when user enables location in Settings
  • Location detection shows "Showing colleges in [Town]" info chip
  • Continue button is disabled (greyed) until a college is selected
  • Security note displayed below continue button

4.4 ID Verification​

IdVerificationScreen (Step 3 of 4)
    │
    ├── [Capture Front of ID]
    │       Requests camera permission
    │       Opens CameraPreviewOverlay (full-screen)
    │           [Capture] → takePicture()
    │           [Close] → back to verification screen
    │       Shows captured image thumbnail
    │       [Retake] option
    │
    ├── [Capture Back of ID]
    │       Same flow as front
    │
    └── Both images captured → [Submit for Review] enabled
            Simulated 2-second upload
            Success dialog:
                "Submitted Successfully"
                "Review takes 24-48 hours"
                [Continue to Home] → HomeMarketplaceScreen

Key UX Details:

  • Step indicator shows progress (3 of 4)
  • Verification instructions widget explains photo requirements
  • Estimated review time (24–48 hours) shown in amber info box
  • Error messages shown inline if submission fails

4.5 Browsing the Marketplace​

HomeMarketplaceScreen
    │
    ├── Search Bar
    │       Type to filter listings (300ms debounce)
    │       Recent searches shown as suggestions
    │       Category suggestions shown below
    │
    ├── Category Quick-Links (horizontal scroll)
    │       Textbooks, Electronics, Furniture, Clothing, Sports Equipment
    │       Tap to filter (UI only, not wired to filter state)
    │
    ├── Active Filter Chips (shown when filters applied)
    │       [Categories ×] [Price ×] [Colleges ×] [Availability ×]
    │       Tap × to remove filter
    │
    ├── [Filter Icon] → FilterBottomSheetWidget
    │       Category multi-select
    │       Price range slider
    │       College multi-select
    │       Availability type (Buy Only / Rent Only / Both)
    │       [Apply Filters]
    │
    ├── Listings Grid (2 columns)
    │       ListingCardWidget per item
    │       Tap → ListingDetailsScreen (with listing as argument)
    │       Long-press → Quick Actions bottom sheet
    │           [Save Listing] [Share Listing] [Report Listing]
    │
    ├── Empty State (no results)
    │       EmptyStateWidget with [Create Listing] CTA
    │
    └── Infinite Scroll
            Triggers _loadMoreListings() when 400px from bottom
            Shows skeleton cards while loading more

Key UX Details:

  • Personalized greeting "Hey Sarah 👋" (currently hard-coded)
  • Skeleton loading cards shown during initial load
  • Pull-to-refresh resets listings to full mock dataset
  • Notification bell in AppBar (shows "No new notifications" snackbar)

4.6 Listing Details & Purchase/Rental​

ListingDetailsScreen
    │
    ├── Image Carousel (swipeable)
    ├── Title, Price, Rent/Day badge
    ├── View count + Posted date
    │
    ├── SellerInfoCardWidget
    │       Seller avatar, name, college, verified badge, online status
    │       Trust score percentage
    │       [Message Seller] → ChatScreen
    │
    ├── Description (5-line collapse with Read More/Less)
    │
    ├── Item Details (Category, Condition, Availability)
    │
    ├── RentalInfoCardWidget (if rentable)
    │       Deposit amount
    │       Rental terms
    │
    ├── [Bookmark] (AppBar) → toggles save state
    ├── [Share] (AppBar) → native share sheet
    │
    └── Bottom Action Buttons
            [Rent Item] → RentalDurationBottomSheet
                Select 1/3/7/14/30 days
                Shows total cost + deposit
                [Confirm Rental] → snackbar + option to view in Rentals
            [Buy Now] → (not yet implemented)

4.7 Creating a Listing​

CreateListingScreen
    │
    ├── PhotoGalleryWidget
    │       [+ Add Photo] → bottom sheet: Camera / Gallery
    │       Camera: requests permission → ImagePicker.camera
    │       Gallery: ImagePicker.gallery
    │       Max 8 photos, tap × to remove
    │
    ├── Title field (max 60 chars, live counter)
    ├── Description field (max 500 chars, live counter)
    ├── CategorySelectorWidget (dropdown)
    ├── ConditionSelectorWidget (New / Like New / Good / Fair / Poor)
    │
    ├── PricingSectionWidget
    │       Toggle: [Sell] [Rent] [Both]
    │       Sell: Sale Price field
    │       Rent: Daily Rate + Min Days + Deposit fields
    │       Both: All fields shown
    │
    ├── Form Validation (on submit)
    │       Title: required, min 3 chars
    │       Description: required, min 10 chars
    │       Category: required
    │       Photos: at least 1 required
    │       Price/Rate: required and > 0 based on pricing type
    │
    └── [Post Listing]
            Simulated 2-second API call
            Success snackbar → navigate to HomeMarketplaceScreen
            Error snackbar on failure

4.8 Messaging​

ChatScreen (Inbox)
    │
    ├── Filter Tabs: All | Unread | Archived (non-functional)
    ├── Conversation List
    │       Avatar with online indicator
    │       Unread count badge
    │       Last message preview
    │       Listing context tag
    │       Tap → IndividualChatScreen
    │
    └── Pull-to-refresh

IndividualChatScreen
    │
    ├── AppBar: Seller avatar, name, online status, verified badge
    │           [Info] → ListingDetailsScreen
    │
    ├── ListingContextCardWidget (pinned at top)
    │       Item thumbnail, title, price
    │       Tap → ListingDetailsScreen
    │
    ├── Quick Action Chips
    │       "Is this available?" | "What's your best price?" | "When can we meet?"
    │       Tap → auto-sends as message
    │
    ├── Message List
    │       MessageBubbleWidget per message
    │       Sender messages: right-aligned, primary color
    │       Received messages: left-aligned, surface color
    │       Image messages: inline image preview
    │       Read receipts (double checkmark)
    │       TypingIndicatorWidget (animated dots)
    │       Long-press → Copy / Delete / Report options
    │
    └── ChatInputWidget
            Text field
            [Image] button → ImagePicker
            [Send] button (enabled when text non-empty)

4.9 Rental Management​

RentalManagementScreen
    │
    ├── Tab: Active Rentals
    │       RentalCardWidget per rental
    │           Item image, title
    │           Renter/lender avatar and name
    │           Countdown timer (days/hours remaining)
    │           Overdue indicator (red) if past return date
    │           [Mark as Returned] → confirmation dialog
    │           [Extend Rental] → duration bottom sheet (1 day / 3 days / 1 week)
    │           Swipe left → Contact | Details | Report actions
    │
    └── Tab: History
            RentalHistoryCardWidget per completed rental
                Item image, title, dates
                Late return indicator
                Star rating (if rated)
                [Rate User] → star rating dialog with optional review text
                [View Details] → ListingDetailsScreen

Key UX Details:

  • Overdue rentals are visually highlighted in red
  • Timer updates every minute (via recursive Future — see BUG-19)
  • Swipe actions use flutter_slidable package

4.10 Profile & Account Management​

ProfileScreen
    │
    ├── ProfileHeaderWidget
    │       Avatar (tap to update — coming soon)
    │       Name, college
    │       Verified badge (if approved)
    │
    ├── VerificationStatusWidget (if not approved)
    │       Pending: "Under Review" with timeline
    │       Rejected: reason + [Resubmit ID] → IdVerificationScreen
    │
    ├── TrustScoreWidget (if approved)
    │       Score display (e.g., 4.7/5.0)
    │       Rental count
    │       Tap → Trust Score Breakdown bottom sheet
    │           On-time Returns, Item Condition, Communication, Response Time
    │
    ├── StatsSectionWidget
    │       Active Listings count
    │       Successful Rentals count
    │       Member Since date
    │
    ├── Menu Items
    │       My Listings → HomeMarketplaceScreen
    │       Rental History → RentalManagementScreen
    │       Saved Items → (coming soon)
    │       Payment Methods → (coming soon)
    │       Notifications → (coming soon)
    │       Help & Support → (coming soon)
    │       Settings → (coming soon)
    │
    └── [Logout]
            Confirmation dialog
            On confirm → AuthenticationScreen (removes all routes)

5. Navigation Structure​

Bottom Navigation Bar​

The CustomBottomBar appears on all main screens (Home, Chat, Rentals, Profile) and on secondary screens (Listing Details, Create Listing, ID Verification).

TabIconRoute
BrowseHome/home-marketplace-screen
MessagesChat bubble/chat-screen
(Create)+ FAB/create-listing-screen
RentalsClock/rental-management-screen
ProfilePerson/profile-screen

Screen Hierarchy​

SplashScreen (initial)
└── OnboardingScreen
    └── AuthenticationScreen
        └── CollegeSelectionScreen
            └── IdVerificationScreen
                └── HomeMarketplaceScreen ◄──── Main Hub
                    ├── ListingDetailsScreen
                    │   └── IndividualChatScreen
                    ├── CreateListingScreen
                    ├── ChatScreen
                    │   └── IndividualChatScreen
                    ├── RentalManagementScreen
                    └── ProfileScreen
                        └── IdVerificationScreen (resubmit)

6. Trust & Safety System​

Trust Score​

  • Displayed as a decimal score (e.g., 4.7/5.0) and percentage
  • Calculated from four components:
    1. On-time Returns — percentage of rentals returned by due date
    2. Item Condition — percentage of items returned in acceptable condition
    3. Communication — average rating from renter feedback
    4. Response Time — average time to respond to messages
  • Higher trust scores unlock better deals and priority listings (planned feature)
  • Score breakdown accessible via tap on TrustScoreWidget

Verification Flow​

  1. User submits front + back of student ID via camera
  2. Submission enters review queue (24–48 hour SLA)
  3. Admin reviews and approves or rejects with reason
  4. User notified of outcome (push notification — planned)
  5. Approved users get verified badge on profile and listings

Verification States​

StateUIActions Available
pendingYellow "Under Review" cardNone (wait)
rejectedRed card with reason[Resubmit ID]
approvedGreen verified badgeFull marketplace access

Reporting​

  • Listings can be reported via long-press quick actions on marketplace
  • Messages can be reported via long-press in chat
  • Rentals can have issues reported via swipe action
  • All reports show "Report submitted" confirmation (no backend yet)

7. Feature Status Matrix​

FeatureUILogicBackendNotes
Onboarding✅✅N/AComplete
Phone OTP Auth❌✅✅Service ready, no UI (GAP-20)
Google Sign In✅✅✅Firebase wired
Apple Sign In✅✅✅Firebase wired, iOS only
Email Auth✅✅✅Firebase wired
College Selection✅✅✅Real GPS + Firestore save
ID Verification✅✅✅Firebase Storage upload
Admin Panel✅✅✅Fully implemented
Marketplace Browse✅✅✅Firestore integrated
Search✅✅ (local)❌Client-side only
Filters✅✅❌Filter sheet active, RadioListTile resolved
Listing Details✅✅✅Dynamic list navigation works via route args
Buy Now✅✅⚠️Payment works, listing not marked sold (GAP-14)
Rent⏳⏳⏳Deferred (Rental flow currently disabled)
Create Listing✅✅✅Firestore write works
Content ModerationN/A✅N/ALexical moderation active before posting
Chat Inbox✅✅✅Fully live, uses conversationsStream
Individual Chat✅✅✅Fully live, messages stream and write
Rental Initiation⏳⏳⏳Deferred (Rental flow currently disabled)
Rental Management⏳⏳⏳Deferred (Rental flow currently disabled)
User Rating✅✅ (local)❌Not persisted to Firestore (GAP-17)
Profile✅✅✅Firestore read
Trust Score✅⚠️⚠️Display works, never recalculated (GAP-18)
Avatar Upload✅✅✅Uploads to Cloudinary via StorageService
Saved Items✅✅✅Full screen and Firestore toggle integration
Settings✅✅✅Currency settings bridged to CurrencyService
Support✅⚠️ (stubs)❌All options show "coming soon" (GAP-11)
Push Notifications❌❌❌Not started

8. Planned / Unimplemented Features​

For gaps that exist in the current codebase (designed but not developed), see errors.md for the full tracker and phased fix plan.

High Priority (Phase B — Core Data Flow)​

  1. Purchase Completion — After a successful purchase, the listing must be marked isActive = false to prevent duplicate purchases.

Medium Priority (Phase C & D)​

  1. Trust Score Integration — TrustScoreService is fully implemented but never called. Must be triggered after transactions, returns, and ratings.
  2. Phone OTP UI — AuthService.sendPhoneOtp() and verifyPhoneOtp() are implemented but there is no phone input UI in auth_screen.dart.

Low Priority (Phase E — Polish)​

  1. Dark Mode — Theme is fully defined. The toggle in settings needs to call ThemeService and MyApp needs to observe it.
  2. Listing Edit/Delete — Sellers cannot modify or remove their listings after posting.
  3. Rental Extension — Currently shows hardcoded prices ($10/$25/$50) with no payment step and no Firestore persistence.
  4. Draft Saving — _saveDraft() and _loadDraft() in create_listing_screen.dart are empty stubs.
  5. Push Notifications — FCM for Android, APNs for iOS. Needed for new messages, rental due dates, and verification status changes.
  6. Server-side Search — Current search is client-side only. Full-text search across all listings requires a Firestore composite index or Algolia integration.
  7. Dispute Resolution — No formal process beyond the "Report Issue" flow.
  8. Seller Analytics — Views, inquiries, and conversion rate dashboard for sellers.