System Requirements Document (SRD)

Project Name: opal-app

1. Introduction

The opal-app is a mobile-first car marketplace application designed to connect private car sellers and buyers in a seamless, secure, and user-friendly environment. The app enables sellers to list vehicles with ease and buyers to discover, enquire about, and complete car purchases efficiently.

This document outlines the system requirements for the opal-app, ensuring a clean, modern, and premium user experience tailored to the Singaporean market. The app will prioritize simplicity, trustworthiness, and transaction readiness, while balancing security and user experience.

2. System Overview

The opal-app will serve as a comprehensive platform for private car transactions, supporting two primary user journeys:

1. Seller Journey: Sellers can create and manage car listings, communicate with buyers, and track the sale process.
2. Buyer Journey: Buyers can browse, search, and filter car listings, contact sellers, and track the purchase process.

The app will feature a clean, mobile-first design with intuitive navigation, in-app messaging, and essential security measures like phone/email verification. It will be built using React Native for cross-platform compatibility, ensuring a fast and efficient development process.

3. Functional Requirements

Seller Journey

• As a Seller, I should be able to create a new car listing by entering the car’s key details:
  • Brand
  • Model
  • Year
  • Body type
  • Price
  • Mileage
  • Fuel type
  • Transmission
  • Location
  • Description
  • Availability status
• As a Seller, I should be able to automatically generate realistic car images based on the vehicle details.
• As a Seller, I should be able to preview the listing before publishing.
• As a Seller, I should be able to edit or remove an existing listing.
• As a Seller, I should be able to view enquiries from interested buyers.
• As a Seller, I should be able to reply to buyers inside the app.
• As a Seller, I should be able to mark a car as:
  • Available
  • Reserved
  • Sold
• As a Seller, I should be able to confirm a sale once both buyer and seller agree.

Buyer Journey

• As a Buyer, I should be able to browse available cars in a clean marketplace feed.
• As a Buyer, I should be able to search and filter cars by:
  • Brand
  • Body type
  • Price range
  • Year
  • Mileage
  • Fuel type
  • Location
• As a Buyer, I should be able to open a car listing to view:
  • Image gallery
  • Vehicle details
  • Price
  • Seller information
  • Description
  • Availability status
• As a Buyer, I should be able to save favourite cars.
• As a Buyer, I should be able to contact the seller with an enquiry.
• As a Buyer, I should be able to message the seller inside the app.
• As a Buyer, I should be able to make an offer or express intent to buy.
• As a Buyer, I should be able to track the purchase process until the car is marked sold.

Marketplace Experience

• As a User, I should see a dashboard for buyers to browse cars.
• As a User, I should see a seller dashboard to manage listings and enquiries.
• As a User, I should see listing detail pages.
• As a User, I should experience a smooth add/edit listing flow.
• As a User, I should experience a seamless messaging or enquiry flow.
• As a User, I should experience a purchase/status tracking flow.
• As a User, I should see empty states, loading states, validation messages, and success confirmations.

4. User Personas

1. Seller:

   • Private individuals looking to sell their cars.
   • Needs: Easy listing creation, buyer communication, and sale tracking.

2. Buyer:

   • Individuals searching for cars to purchase.
   • Needs: Intuitive browsing, filtering, and communication with sellers.

3. Admin:

   • Platform moderators ensuring smooth operations and content moderation.
   • Needs: Tools for managing listings, user accounts, and flagged content.

5. Visuals Colors and Theme

Color Palette

• primary: #1A73E8 (Vivid Blue)
• primary_light: #E3F2FD (Soft Sky Blue)
• secondary: #FF6F61 (Coral Red)
• accent: #FFD700 (Golden Yellow)
• highlight: #FFA500 (Bright Orange)
• bg: #F9FAFB (Light Gray)
• surface: rgba(255, 255, 255, 0.9) (White with slight transparency)
• text: #212121 (Dark Charcoal)
• text_muted: #757575 (Muted Gray)
• border: rgba(0, 0, 0, 0.1) (Subtle Black)

6. Signature Design Concept

Interactive Car Showcase

The opal-app homepage will feature an interactive 3D car showcase. Users can swipe or drag to rotate a 3D car model, which dynamically updates based on the selected filters (e.g., brand, body type, color).

• Animation: Smooth transitions between car models using @react-three/fiber and @react-three/drei.
• Interaction: Hovering over car details will highlight them with subtle animations (e.g., glowing outlines).
• Micro-interactions: Clicking on a car will zoom into its details, with a parallax effect revealing the listing information.
• Background: A gradient backdrop that shifts colors based on the time of day (e.g., sunrise hues in the morning, twilight tones in the evening).

This concept will make the app feel premium and engaging while keeping the focus on the cars.

7. Interaction Model & Motion Direction

• Landing Page: Parallax interaction with layered depth.
• Internal Pages: Animated transitions for smooth navigation between sections.
• Micro-interactions: Subtle hover effects, spring physics for buttons, and scroll-triggered reveals.

8. Non-Functional Requirements

• The app must load within 3 seconds on a 4G connection.
• The app must support iOS 13+ and Android 8.0+.
• The app must ensure data security with HTTPS and encrypted communication.
• The app must handle up to 10,000 concurrent users.

9. Tech Stack

• Frontend: React Native
• Backend: Python, FastAPI
• Database: MySQL with Alembic for migrations
• AI Tools: Google Nano Banana for image generation
• Orchestration: Docker, docker-compose

10. Assumptions and Constraints

• Users will primarily access the app from mobile devices.
• Payments will be handled offline between users.
• The app will initially target the Singaporean market.

11. Glossary

• Listing: A car advertisement created by a seller.
• Enquiry: A message sent by a buyer to a seller.
• Parallax: A design effect where background elements move slower than foreground elements, creating depth.
• React Native: A framework for building cross-platform mobile apps.

This document provides a clear roadmap for the development of the opal-app, ensuring a balance between functionality, security, and user experience. Let’s move forward to bring this vision to life!