Swopix — About the App

A verified college campus marketplace for buying, selling, and renting items between students.

What is Swopix?

Swopix is a mobile-first marketplace built exclusively for college students. It lets verified students buy, sell, and rent items — textbooks, electronics, furniture, clothing, sports gear — within their local campus community. Every user must verify their student ID before transacting, which keeps the platform trusted, local, and safe.

The name blends Swap and Pixels — reflecting the digital exchange of real-world goods between students.

The Problem It Solves

College students constantly cycle through items — textbooks used for one semester, laptops upgraded every two years, furniture bought for a dorm and abandoned at graduation. Generic marketplaces like Facebook Marketplace or Craigslist have no identity verification, no community trust layer, and no rental model. Swopix fills that gap:

Verified identity — only real students with valid IDs can transact
Campus-scoped — listings are filtered to your geographic college area
Rental-first — items can be rented for days or weeks, not just sold outright
Trust scoring — reliable behavior is rewarded with a visible trust score

Core Value Propositions

For Buyers / Renters	For Sellers / Lenders
Browse verified student listings	Earn money from items sitting unused
Rent instead of buying (save money)	Set items for sale, rent, or both
Know who you're dealing with (verified badge)	Build a trust score that attracts more buyers
Local meetups — no shipping needed	Manage active rentals with countdown timers
Secure payments via Razorpay	Receive payouts after successful transactions

Target Audience

Primary: College students aged 18–25 in India (INR default currency, Razorpay payment gateway).

User types:

New student — downloads app, goes through onboarding, verifies student ID, starts browsing
Buyer/Renter — browses listings, contacts sellers, initiates rentals or purchases
Seller/Lender — creates listings with photos and pricing, manages inquiries and active rentals

Platform & Tech Stack

Layer	Technology
Framework	Flutter 3.x (Dart 3.x)
UI System	Material 3
Target Platforms	Android, iOS, Web (Chrome)
Backend	Firebase (Auth, Firestore, Storage)
Payments	Razorpay
Responsive Layout	Sizer package
Typography	Google Fonts — PlusJakartaSans, Inter
State Management	setState (local, per-screen)
Navigation	Flutter Named Routes
Image Loading	CachedNetworkImage
Camera	camera + image_picker packages
Permissions	permission_handler
Connectivity	connectivity_plus
Sharing	share_plus
Rental List UI	flutter_slidable

Package name: com.swopix.app
Flutter SDK: ^3.6.0
Min Android SDK: 21
Min iOS: 12+

App Flow — From Download to Transaction

Install App
    │
    ▼
Splash Screen
    Animated logo, checks Firebase auth state
    │
    ├── Not signed in ──────────────────────────────────────────────────────┐
    │                                                                        │
    ▼                                                                        │
Onboarding (3 slides)                                                        │
    "Verified College Community"                                             │
    "Buy, Sell & Rent"                                                       │
    "Trust Score System"                                                     │
    │                                                                        │
    ▼                                                                        │
Authentication                                                               │
    Phone OTP  /  Google  /  Apple (iOS)  /  Email+Password                 │
    │                                                                        │
    ▼                                                                        │
College Selection (Step 2/4)                                                 │
    GPS detects nearby colleges                                              │
    User picks their institution                                             │
    │                                                                        │
    ▼                                                                        │
ID Verification (Step 3/4)                                                   │
    Camera capture of student ID (front + back)                             │
    Submitted for 24–48 hour admin review                                   │
    │                                                                        │
    ▼                                                                        │
    ├── Signed in + verified ◄──────────────────────────────────────────────┘
    │
    ▼
Home Marketplace  ◄──── Main Hub
    │
    ├── Browse & Search listings
    ├── Tap listing → Listing Details → Buy Now / Rent
    ├── + button → Create Listing
    ├── Messages tab → Chat Inbox → Individual Chat
    ├── Rentals tab → Active Rentals + History
    └── Profile tab → Profile, Trust Score, Settings

Screens

Splash Screen

Animated logo with scale + fade animation. Checks Firebase auth state and routes the user to the correct screen — onboarding for new users, home for verified users, ID verification for users who haven't completed verification.

Onboarding

Three slides introducing the app's core concepts. Skippable at any point. Uses SmoothPageIndicator for page dots. Leads to the authentication screen.

Authentication

Four sign-in methods on a single screen:

Phone OTP — international phone input + 6-digit Pinput with 60-second resend timer
Google Sign In — OAuth via Google
Apple Sign In — iOS only, conditionally shown
Email / Password — traditional login

All methods are wired to Firebase Auth. On success, navigates to college selection.

College Selection

GPS-assisted college picker. Requests location permission, detects the user's town, and shows a searchable dropdown of nearby colleges. Uses WidgetsBindingObserver to auto-detect when the user enables location from system settings. Saves college to Firestore on continue.

ID Verification

Camera-based student ID capture. Captures front and back of the ID using the device camera. Uploads to Firebase Storage and creates a verification request. Admin reviews within 24–48 hours. Shows step indicator (3 of 4).

Home Marketplace

The main browsing screen. Two-column listing grid with:

Debounced search (300ms) across title and description
Category quick-links (horizontal scroll): All, Electronics, Textbooks, Furniture, Clothing, Sports, Music
Advanced filter bottom sheet: category, price range, college, availability type
Active filter chips with individual dismiss
Infinite scroll pagination
Long-press on listing → quick actions (Save, Share, Report)
Pull-to-refresh

Listing Details

Full item view with:

Swipeable image carousel
Title, price, rent/day badge
View count and posted date
Seller info card (avatar, name, college, verified badge, trust score, online status)
Collapsible description (Read More / Show Less)
Item details table (category, condition, availability)
Rental info card (deposit amount, rental terms) — shown only for rentable items
Bookmark and share buttons
Sticky bottom CTA: Rent and/or Buy Now buttons

Buy Now Flow (Purchase Bottom Sheet)

Three-step flow:

Order Summary — item card, price breakdown (item price + 2% platform fee = total)
Razorpay Checkout — opens native Razorpay payment sheet (UPI, Cards, Net Banking, Wallets)
Success / Error — confirmation with payment ID, or error with retry option

Rent Flow (Rental Duration Bottom Sheet)

Duration selector: 1, 3, 7, 14, or 30 days
Cost breakdown: rental cost + security deposit + 2% platform fee = total
Opens Razorpay checkout on confirm
Success screen shows payment ID and navigates to Rentals tab

Create Listing

Multi-step form:

Photo gallery (up to 8 photos from camera or gallery)
Title (max 60 chars) and description (max 500 chars) with live counters
Category selector and condition selector (New / Like New / Good / Fair / Poor)
Pricing type toggle: Sell / Rent / Both
- Sell: sale price
- Rent: daily rate, minimum days, security deposit
- Both: all fields
Form validation before submission
Submits to Firestore via FirestoreService.createListing()

Chat Inbox

List of all conversations with:

Avatar with online indicator
Unread count badge
Last message preview
Listing context tag
Filter tabs: All / Unread / Archived
Pull-to-refresh

Individual Chat

Full messaging interface:

Pinned listing context card at top
Quick action chips: "Is this available?", "What's your best price?", "When can we meet?"
Message bubbles (sent right, received left)
Image sharing
Read receipts (double checkmark)
Typing indicator (animated dots)
Long-press on message: Copy / Delete / Report

Rental Management

Two tabs:

Active — rental cards with countdown timers, overdue detection (red highlight), swipe actions (Contact / Details / Report), Mark as Returned, Extend Rental
History — completed rentals with dates, late return indicator, star rating dialog

Rentals are loaded from Firestore (getUserRentals). Timer updates every minute via Timer.periodic.

Profile

Profile header: avatar, name, college, verified badge
Verification status widget (pending / rejected / approved states)
Trust score widget (score out of 5, rental count, breakdown bottom sheet)
Stats: active listings, successful rentals, member since
Menu: My Listings, Rental History, Saved Items, Payment Methods, Notifications, Help & Support, Settings
Logout with confirmation dialog

Settings, Support, Legal

Settings screen (preferences)
Support screen (help & contact)
Privacy Policy and Terms & Conditions screens

Payment System

Swopix uses Razorpay as the payment gateway.

Money Flow

Buyer pays:   Item Price  +  2% Platform Fee  =  Total Charged
Owner gets:   Item Price  (ownerPayoutStatus: pending → paid)
Platform:     2% Platform Fee  (commission)

For rentals:

Buyer pays:   Rental Cost  +  Security Deposit  +  2% of Rental Cost  =  Total
Owner gets:   Rental Cost  (deposit held, refunded on return)
Platform:     2% of Rental Cost

Payment Records (Firestore)

orders/{id} — created on every successful payment:

type              'purchase' | 'rental'
status            'paid' → 'confirmed' → 'completed'
buyerId           Firebase UID of buyer
ownerId           Firebase UID of seller/lender
listingId         Firestore listing document ID
itemPrice         Amount owner receives
platformFee       2% commission
totalCharged      Amount buyer paid
ownerPayoutStatus 'pending' | 'processing' | 'paid'
razorpayPaymentId Razorpay payment ID
rentalDays        (rental only)
depositAmount     (rental only)
depositStatus     'held' | 'refunded'

payments/{razorpayPaymentId} — audit trail for reconciliation.

Supported Payment Methods (via Razorpay)

UPI (GPay, PhonePe, Paytm, etc.)
Credit / Debit Cards (Visa, Mastercard, RuPay)
Net Banking (all major Indian banks)
Wallets

Trust & Safety

Student ID Verification

Every user must submit front and back photos of their student ID before they can transact. Submissions are reviewed by admins within 24–48 hours. Verified users get a green verified badge on their profile and listings.

Verification states:

State	UI	Access
`pending`	Yellow "Under Review" card	Browse only
`rejected`	Red card with reason + Resubmit button	Browse only
`approved`	Green verified badge	Full access

Trust Score

A decimal score (0–5.0) calculated from four components:

On-time Returns — percentage of rentals returned by the due date
Item Condition — percentage of items returned in acceptable condition
Communication — average rating from transaction feedback
Response Time — average time to respond to messages

Higher trust scores build credibility and are displayed on listings and profiles.

Reporting

Listings: long-press → Report Listing
Messages: long-press → Report Message
Rentals: swipe → Report Issue

Firebase Collections

Collection	Purpose
`users/{uid}`	User profiles, verification status, trust score
`listings/{id}`	Marketplace listings
`rentals/{id}`	Active and completed rental records
`conversations/{id}`	Chat conversation metadata
`conversations/{id}/messages/{id}`	Individual chat messages
`orders/{id}`	Purchase and rental orders with payment data
`payments/{paymentId}`	Payment audit trail

Design System

Brand Colors

Name	Hex	Usage
`primarySkyBlue`	`#6C5CE7`	CTAs, active states, primary brand
`accentLimeGreen`	`#00A859`	Trust, verification, success
`accentAmber`	`#FFB800`	Rent badges, alerts, trust gold
`errorRed`	`#EF4444`	Errors, overdue, destructive actions
`warningOrange`	`#F97316`	Warnings
`textDark`	`#111827`	Primary text
`textLight`	`#6B7280`	Secondary text
`surfaceWhite`	`#F8F9FB`	Background
`borderLight`	`#E5E7EB`	Borders, dividers

Typography

UI text: PlusJakartaSans (Google Fonts)
Body / labels: Inter (Google Fonts)
Prices / data: JetBrainsMono (via AppTheme.dataTextStyle())
Text scaling locked to 1.0 globally (prevents system font size from breaking layouts)

Spacing

8pt grid system. Responsive sizing via sizer package (x.w, x.h, x.sp).

Themes

Both light and dark themes are fully defined in AppTheme. The app currently runs in light mode only — dark mode toggle is planned.

All navigation uses Flutter named routes defined in lib/app/routes.dart.

Route	Screen
`/`	SplashScreen
`/onboarding-screen`	OnboardingScreen
`/authentication-screen`	AuthenticationScreen
`/college-selection-screen`	CollegeSelectionScreen
`/id-verification-screen`	IdVerificationScreen
`/home-marketplace-screen`	HomeMarketplaceScreen
`/listing-details-screen`	ListingDetailsScreen
`/create-listing-screen`	CreateListingScreen
`/chat-screen`	ChatScreen
`/individual-chat-screen`	IndividualChatScreen
`/rental-management-screen`	RentalManagementScreen
`/profile-screen`	ProfileScreen
`/settings-screen`	SettingsScreen
`/support-screen`	SupportScreen
`/privacy-policy-screen`	PrivacyPolicyScreen
`/terms-conditions-screen`	TermsConditionsScreen

The bottom navigation bar (Browse / Messages / Rentals / Profile + central Create button) appears on all main screens.

Project Structure

lib/
├── main.dart                    # Entry point, Firebase init, error handler, orientation lock
├── firebase_options.dart        # Generated by FlutterFire CLI
├── app/
│   ├── routes.dart              # All named routes
│   └── theme.dart               # Design system — colors, typography, light/dark themes
├── core/
│   ├── app_export.dart          # Barrel export file
│   ├── currency_service.dart    # Multi-currency formatting (default: INR)
│   └── theme_service.dart       # Theme persistence via SharedPreferences
├── models/
│   └── user_model.dart          # UserModel with Firestore serialization
├── services/
│   ├── auth_service.dart        # Firebase Auth wrapper (email, Google, Apple, phone)
│   ├── firestore_service.dart   # All Firestore reads/writes
│   ├── storage_service.dart     # Firebase Storage uploads
│   ├── payment_service.dart     # Razorpay checkout wrapper
│   └── order_service.dart       # Order + payment recording in Firestore
├── widgets/                     # Shared reusable widgets
│   ├── custom_app_bar.dart      # AppBar variants
│   ├── custom_bottom_bar.dart   # Bottom navigation bar
│   ├── custom_error_widget.dart # Global error fallback
│   ├── custom_icon_widget.dart  # String → IconData mapper
│   ├── custom_image_widget.dart # Multi-source image widget
│   └── main_shell.dart          # Main navigation shell
└── screens/
    ├── splash/
    ├── onboarding/
    ├── auth/
    ├── college_selection/
    ├── id_verification/
    ├── home/
    ├── listing_details/
    ├── create_listing/
    ├── chat/
    ├── rentals/
    ├── profile/
    ├── settings/
    ├── support/
    └── legal/

assets/
└── images/
    ├── img_app_logo.svg
    ├── no-image.jpg
    └── sad_face.svg

Running the App

# Install dependencies
flutter pub get

# Run on Android
flutter run -d android

# Run on iOS
flutter run -d ios

# Run on Chrome (web)
flutter run -d chrome

# Release build
flutter build apk --release
flutter build ios --release
flutter build web --release

Firebase setup:

# Reconfigure Firebase (regenerates firebase_options.dart)
flutterfire configure --project=swopix-cbf7c

Feature Status

Feature	Status
Onboarding slides	✅ Complete
Phone OTP auth	⚠️ Service implemented, no UI (GAP-20)
Google Sign In	✅ Firebase wired
Apple Sign In (iOS)	✅ Firebase wired
Email / Password auth	✅ Firebase wired
College selection (GPS)	✅ Real GPS + Firestore save
Student ID verification	✅ Firebase Storage upload
Admin panel	✅ Fully implemented
Marketplace browse	✅ Firestore integrated
Search & filters	✅ Integrated (Filter sheet active, RadioListTile resolved)
Listing details	✅ Integrated dynamically (reads route arguments)
Buy Now (Razorpay)	⚠️ Payment works; listing not marked sold after purchase (GAP-14)
Rent (Razorpay)	⏳ Deferred (Rental flow currently disabled / Coming Soon)
Order recording (Firestore)	✅ Complete
Create listing	✅ Firestore write works
Content moderation	✅ Active (moderateContent called before posting)
Chat inbox	✅ Integrated with Firestore conversationsStream
Individual chat	✅ Integrated with Firestore messagesStream
Rental management	⏳ Deferred (Rental flow currently disabled / Coming Soon)
Mark as returned	✅ Firestore write
User rating	⚠️ UI complete, local state only — not persisted (GAP-17)
Profile screen	✅ Firestore read
Trust score display	✅ UI complete
Trust score calculation	⚠️ Service ready, never called after transactions (GAP-18)
Avatar upload	✅ Integrated via StorageService and Cloudinary
Saved items	✅ Integrated saved items screen and bookmarks collection
Settings screen	✅ Integrated (Currency bridge active)
Support screen	⚠️ UI complete; all options are stubs (GAP-11)
Dark mode	⚠️ Theme defined, toggle not exposed
Push notifications	❌ Not started
Server-side search	❌ Not started
Seller analytics	❌ Not started
Dispute resolution	❌ Not started
Owner payout automation	❌ Manual / Cloud Function needed

Known Issues

See errors.md for the full tracker with phased fix plan. Key open items:

ID	Issue	Severity	Phase
GAP-14	Listing not marked sold after purchase (duplicate purchases)	🔴 HIGH	B
GAP-18	Trust score never recalculated after transactions	🟠 MEDIUM	C
GAP-20	Phone OTP auth has no UI	🟠 MEDIUM	D
BUG-21	`env.json` committed to repo — rotate any exposed keys	🟠 HIGH	—

Security Notes

Razorpay Key Secret (RAZORPAY_KEY_SECRET) must never be in the Flutter app. It belongs in a Firebase Cloud Function for server-side payment verification and owner payouts.
env.json at the project root should be added to .gitignore immediately and any exposed keys rotated.
Firebase Security Rules for Firestore and Storage must be configured before production launch to prevent unauthorized reads/writes.
All user-uploaded images (ID verification, listing photos) should be stored in Firebase Storage with restricted access rules.

Swopix — Built with Flutter & Firebase. Payments by Razorpay.

What is Swopix?​

The Problem It Solves​

Core Value Propositions​

Target Audience​

Platform & Tech Stack​

App Flow — From Download to Transaction​

Screens​

Splash Screen​

Onboarding​

Authentication​

College Selection​

ID Verification​

Home Marketplace​

Listing Details​

Buy Now Flow (Purchase Bottom Sheet)​

Rent Flow (Rental Duration Bottom Sheet)​

Create Listing​

Chat Inbox​

Individual Chat​

Rental Management​

Profile​

Settings, Support, Legal​

Payment System​

Money Flow​

Payment Records (Firestore)​

Supported Payment Methods (via Razorpay)​

Trust & Safety​

Student ID Verification​

Trust Score​

Reporting​

Firebase Collections​

Design System​

Brand Colors​

Typography​

Spacing​

Themes​

Navigation​

Project Structure​

Running the App​

Feature Status​

Known Issues​

Security Notes​