# Product Requirements Document: Pokemon Card Resell Platform

## 1. Overview

The Pokemon Card Resell Platform is a specialized e-commerce marketplace that enables collectors and traders to buy, sell, and trade Pokemon trading cards. The platform facilitates secure transactions between sellers and buyers, provides card authentication and grading information, manages inventory, and supports both individual card sales and bulk listings. Users can browse cards by set, rarity, condition, and price, while sellers can manage their storefronts and track sales performance.

## 2. User Roles

### 2.1 Guest (Unauthenticated User)
- Browse card listings and search/filter cards
- View card details, images, and pricing
- View seller profiles and ratings
- Access public marketplace statistics
- Register for an account or log in

### 2.2 Buyer (Authenticated User)
- All Guest permissions
- Add cards to cart and wishlist
- Purchase cards and complete checkout
- Make offers on cards
- Leave reviews and ratings for sellers
- Track order history and status
- Manage shipping addresses
- Save payment methods
- Receive notifications about price drops and new listings
- Message sellers with questions

### 2.3 Seller (Authenticated User with Seller Profile)
- All Buyer permissions
- Create and manage card listings
- Upload card images and descriptions
- Set pricing and inventory quantities
- Manage storefront profile
- View sales analytics and reports
- Process orders and update shipping status
- Respond to buyer messages and offers
- Accept or decline offers
- Manage bulk listings
- Set seller policies (returns, shipping)

### 2.4 Admin
- All system permissions
- Manage user accounts (suspend, ban, verify)
- Moderate listings and remove inappropriate content
- Resolve disputes between buyers and sellers
- Manage card database (sets, rarities, base card info)
- View platform-wide analytics
- Configure platform settings and fees
- Manage featured listings
- Process refunds and handle payment issues
- Verify card authenticity reports

## 3. Core Entities

### 3.1 User
Represents any registered user on the platform with authentication credentials, profile information, contact details, and account status.

### 3.2 SellerProfile
Extended profile for users who sell cards, including business information, seller ratings, policies, payout details, and storefront customization.

### 3.3 Card
Master reference data for Pokemon cards including card name, set, card number, rarity, type, HP, attacks, and official artwork/information.

### 3.4 CardSet
Represents a Pokemon card set/expansion (e.g., Base Set, Jungle, Sword & Shield) with release date, set symbol, and total card count.

### 3.5 Listing
A specific card offered for sale by a seller, including condition, price, quantity available, grading information, and listing status.

### 3.6 ListingImage
Photos uploaded by sellers showing the actual card being sold, including front, back, and detail shots.

### 3.7 Cart
Temporary collection of listings a buyer intends to purchase, with quantity and selected options.

### 3.8 CartItem
Individual listing within a cart with quantity and any item-specific selections.

### 3.9 Order
A completed purchase transaction containing buyer information, payment details, shipping address, and order status.

### 3.10 OrderItem
Individual listing purchased within an order, with quantity, price at time of purchase, and item-specific status.

### 3.11 Payment
Payment transaction record including amount, payment method, transaction ID, and payment status.

### 3.12 ShippingAddress
Saved or one-time shipping address for order delivery.

### 3.13 Review
Buyer feedback for a seller or specific transaction, including rating, comment, and timestamp.

### 3.14 Offer
A buyer's proposed price for a listing, with offer amount, message, status (pending/accepted/declined/expired).

### 3.15 Wishlist
Collection of cards or listings a buyer wants to track or purchase later.

### 3.16 WishlistItem
Individual card or listing within a wishlist.

### 3.17 Message
Communication between buyer and seller regarding a listing or order.

### 3.18 Notification
System-generated alerts for users about orders, offers, messages, and platform updates.

### 3.19 CardCondition
Standardized condition grades (Mint, Near Mint, Lightly Played, Moderately Played, Heavily Played, Damaged) with descriptions.

### 3.20 Category
Organizational taxonomy for cards (e.g., Generation, Type, Rarity tier).

### 3.21 Transaction
Financial record of money movement including sales, refunds, fees, and payouts.

### 3.22 Dispute
Formal complaint or issue raised by buyer or seller requiring resolution.

### 3.23 SavedPaymentMethod
Stored payment information (tokenized) for quick checkout.

## 4. Entity Relationships

### 4.1 User Relationships
- User **1:1** SellerProfile (optional - only if user becomes seller)
- User **1:Many** Listing (as seller)
- User **1:Many** Order (as buyer)
- User **1:Many** Review (as reviewer)
- User **1:Many** Review (as seller being reviewed)
- User **1:1** Cart (active cart)
- User **1:Many** Wishlist
- User **1:Many** ShippingAddress
- User **1:Many** SavedPaymentMethod
- User **1:Many** Offer (as buyer)
- User **1:Many** Message (as sender)
- User **1:Many** Message (as recipient)
- User **1:Many** Notification
- User **1:Many** Dispute (as initiator)

### 4.2 Card & Set Relationships
- CardSet **1:Many** Card
- Card **1:Many** Listing
- Card **Many:Many** Category

### 4.3 Listing Relationships
- Listing **Many:1** User (seller)
- Listing **Many:1** Card
- Listing **1:Many** ListingImage
- Listing **1:Many** CartItem
- Listing **1:Many** OrderItem
- Listing **1:Many** Offer
- Listing **1:Many** WishlistItem
- Listing **Many:1** CardCondition

### 4.4 Cart Relationships
- Cart **1:1** User
- Cart **1:Many** CartItem
- CartItem **Many:1** Listing

### 4.5 Order Relationships
- Order **Many:1** User (buyer)
- Order **1:Many** OrderItem
- Order **1:1** Payment
- Order **Many:1** ShippingAddress
- Order **1:Many** Transaction
- Order **1:Many** Dispute

### 4.6 OrderItem Relationships
- OrderItem **Many:1** Order
- OrderItem **Many:1** Listing
- OrderItem **Many:1** User (seller - denormalized)

### 4.7 Wishlist Relationships
- Wishlist **Many:1** User
- Wishlist **1:Many** WishlistItem
- WishlistItem **Many:1** Card (or Listing)

### 4.8 Review Relationships
- Review **Many:1** User (reviewer)
- Review **Many:1** SellerProfile (seller being reviewed)
- Review **Many:1** Order (optional - transaction-specific review)

### 4.9 Offer Relationships
- Offer **Many:1** User (buyer)
- Offer **Many:1** Listing

### 4.10 Message Relationships
- Message **Many:1** User (sender)
- Message **Many:1** User (recipient)
- Message **Many:1** Listing (optional - context)
- Message **Many:1** Order (optional - context)

### 4.11 Payment & Transaction Relationships
- Payment **1:1** Order
- Transaction **Many:1** Order
- Transaction **Many:1** User (seller receiving payout)

### 4.12 Dispute Relationships
- Dispute **Many:1** Order
- Dispute **Many:1** User (initiator)
- Dispute **Many:1** User (admin resolver - optional)

## 5. Key Workflows

### 5.1 User Registration & Seller Onboarding

**User Registration:**
1. Guest clicks "Sign Up"
2. User enters email, password, and basic profile information
3. System validates email format and password strength
4. System sends verification email
5. User clicks verification link
6. Account is activated as Buyer role
7. User is redirected to homepage/dashboard

**Seller Onboarding:**
1. Authenticated user navigates to "Become a Seller"
2. User completes seller profile form (business name, description, policies)
3. User provides payout information (bank account/PayPal)
4. User agrees to seller terms and conditions
5. System creates SellerProfile linked to User
6. Admin reviews and approves seller account (optional)
7. Seller can now create listings

### 5.2 Creating a Listing

1. Seller navigates to "Create Listing"
2. Seller searches for card from master Card database
3. Seller selects the specific card
4. Seller enters listing details:
   - Condition (select from CardCondition options)
   - Price
   - Quantity available
   - Grading information (if applicable)
   - Additional description/notes
5. Seller uploads 1-10 photos of actual card
6. Seller sets listing options (accept offers: yes/no)
7. Seller reviews and submits listing
8. System validates all required fields
9. Listing is created with status "Active"
10. Listing appears in marketplace search results
11. System sends notification to users with card on wishlist

### 5.3 Browsing & Searching Cards

1. User navigates to marketplace
2. User applies filters:
   - Card set
   - Rarity
   - Condition
   - Price range
   - Seller rating
   - Graded/ungraded
3. User enters search keywords (card name, type, etc.)
4. System returns matching listings sorted by relevance/price/date
5. User clicks on listing to view details
6. User views card information, seller details, photos, and reviews
7. User can add to cart, add to wishlist, or make offer

### 5.4 Making an Offer

1. Buyer views listing with "Make Offer" enabled
2. Buyer clicks "Make Offer"
3. Buyer enters offer amount and optional message
4. System validates offer is below listing price
5. Offer is created with status "Pending"
6. System sends notification to seller
7. Seller reviews offer and can:
   - Accept: Listing is reserved for buyer, buyer receives checkout link
   - Decline: Offer status changes to "Declined", buyer is notified
   - Counter: Seller proposes different price, buyer can accept/decline
8. If accepted, buyer has 24 hours to complete purchase
9. If expired (48 hours with no action), offer status changes to "Expired"

### 5.5 Purchase & Checkout Flow

1. Buyer adds listing(s) to cart
2. Buyer clicks "Checkout"
3. System validates cart items are still available
4. Buyer selects or enters shipping address
5. Buyer selects or enters payment method
6. System calculates:
   - Subtotal (sum of item prices)
   - Shipping cost (per seller if multiple)
   - Platform fee
   - Tax
   - Total
7. Buyer reviews order summary
8. Buyer confirms purchase
9. System processes payment:
   - Creates Payment record
   - Charges payment method
   - If successful: continues to step 10
   - If failed: shows error, allows retry
10. System creates Order with status "Paid"
11. System creates OrderItem for each cart item
12. System reduces listing quantity
13. System clears cart
14. System creates Transaction records (buyer payment, seller payout pending)
15. System sends order confirmation email to buyer
16. System sends new order notification to seller(s)
17. Buyer is redirected to order confirmation page

### 5.6 Order Fulfillment

1. Seller receives new order notification
2. Seller navigates to "Orders" dashboard
3. Seller views order details and shipping address
4. Seller packages card(s) securely
5. Seller ships order and obtains tracking number
6. Seller updates order status to "Shipped" and enters tracking info
7. System sends shipping notification to buyer with tracking link
8. Order status automatically updates to "In Transit"
9. After estimated delivery date, system prompts buyer to confirm receipt
10. Buyer confirms receipt or system auto-confirms after 7 days
11. Order status changes to "Delivered"
12. System releases payment to seller (creates payout Transaction)
13. System prompts buyer to leave review

### 5.7 Returns & Disputes

**Return Request:**
1. Buyer navigates to order history
2. Buyer selects order and clicks "Request Return"
3. Buyer selects reason (not as described, damaged, wrong item, etc.)
4. Buyer uploads photos and provides description
5. System creates Dispute with type "Return Request"
6. System notifies seller
7. Seller reviews return request and can:
   - Approve: Provides return shipping label, awaits item return
   - Decline: Provides reason, dispute escalates to admin
8. If approved, buyer ships item back
9. Seller confirms receipt and condition
10. System processes refund
11. Dispute status changes to "Resolved"

**Dispute Escalation:**
1. If seller declines or no response in 48 hours, buyer can escalate
2. Dispute status changes to "Escalated"
3. Admin reviews evidence from both parties
4. Admin makes decision (full refund, partial refund, no refund)
5. System processes refund if applicable
6. Dispute status changes to "Resolved"
7. Both parties are notified of outcome

### 5.8 Review & Rating

1. After order is delivered, buyer receives review prompt
2. Buyer navigates to order history
3. Buyer clicks "Leave Review" for specific seller
4. Buyer provides:
   - Star rating (1-5)
   - Written review
   - Optional: rating categories (shipping speed, card condition, communication)
5. System validates review (must be from completed order)
6. Review is created and linked to SellerProfile
7. System updates seller's average rating
8. Review appears on seller's profile
9. Seller receives notification of new review
10. Seller can respond to review (optional)

### 5.9 Wishlist & Price Alerts

1. Buyer views card or listing
2. Buyer clicks "Add to Wishlist"
3. System creates WishlistItem
4. Buyer can enable price alerts for wishlist items
5. When new listing is created for wishlisted card:
   - System checks if price is below buyer's alert threshold
   - System sends notification to buyer
6. Buyer can view all wishlist items in dedicated page
7. Buyer can move wishlist item directly to cart
8. Buyer can remove items from wishlist

### 5.10 Seller Analytics & Reporting

1. Seller navigates to "Analytics" dashboard
2. System displays:
   - Total sales (revenue)
   - Number of orders
   - Average order value
   - Top selling cards
   - Inventory value
   - Pending payouts
   - Sales trends (daily/weekly/monthly charts)
3. Seller can filter by date range
4. Seller can export reports as CSV/PDF
5. Seller views performance metrics:
   - Average rating
   - Response time
   - Shipping time
   - Order fulfillment rate

## 6. Features & Requirements

### 6.1 User Management Module

**F-UM-001: User Registration**
- Support email/password registration
- Email verification required before account activation
- Password must meet complexity requirements (min 8 chars, uppercase, lowercase, number)
- Capture: first name, last name, email, username, phone (optional)

**F-UM-002: Authentication**
- Secure login with email/password
- "Remember me" option for persistent sessions
- Password reset via email link
- Session timeout after 30 days of inactivity
- Support for OAuth (Google, Facebook) - optional

**F-UM-003: User Profile Management**
- Edit profile information (name, username, email, phone, avatar)
- Change password with current password verification
- View account activity log
- Delete account (with confirmation and data retention policy)

**F-UM-004: Seller Profile Management**
- Create seller profile with business name, description, logo
- Set seller policies (return policy, shipping policy, processing time)
- Configure payout methods (bank transfer, PayPal)
- Display seller statistics (member since, total sales, rating)
- Customize storefront banner and colors

**F-UM-005: User Roles & Permissions**
- Role-based access control (Guest, Buyer, Seller, Admin)
- Automatic role assignment based on actions (e.g., creating listing grants Seller role)
- Admin ability to modify user roles and permissions

### 6.2 Card Database Module

**F-CD-001: Card Master Data**
- Maintain comprehensive Pokemon card database
- Card attributes: name, set, card number, rarity, type, HP, attacks, abilities, artist, release date
- Store official card artwork/images
- Support for multiple languages/regions

**F-CD-002: Card Set Management**
- Organize cards by set/expansion
- Set attributes: name, release date, set symbol, total cards, series
- Display set completion percentage for users

**F-CD-003: Card Search & Browse**
- Full-text search across card names, types, attacks
- Filter by: set, rarity, type, HP range, release date
- Sort by: name, card number, release date, rarity
- Autocomplete suggestions while typing

**F-CD-004: Card Detail Page**
- Display all card attributes and official artwork
- Show current market listings for this card
- Display price history and trends
- Show related cards (same set, same Pokemon evolution line)

**F-CD-005: Category & Taxonomy**
- Organize cards by categories (Generation, Type, Rarity tier, Special categories)
- Support hierarchical category structure
- Tag cards with multiple categories

### 6.3 Listing Management Module

**F-LM-001: Create Listing**
- Search and select card from master database
- Required fields: card, condition, price, quantity
- Optional fields: grading company, grade, certification number, description
- Upload 1-10 images (max 5MB each, JPG/PNG)
- Set "Accept Offers" toggle
- Set minimum offer amount (if offers enabled)
- Draft listings (save without publishing)

**F-LM-002: Edit Listing**
- Modify price, quantity, description, images
- Cannot change card or condition after first sale
- Track edit history with timestamps

**F-LM-003: Listing Status Management**
- Status options: Draft, Active, Sold Out, Paused, Archived
- Automatically set to "Sold Out" when quantity reaches 0
- Seller can pause/unpause listings
- Automatically archive listings older than 1 year with no activity

**F-LM-004: Bulk Listing Management**
- Upload multiple listings via CSV template
- Bulk edit (price adjustment, pause/unpause)
- Bulk delete with confirmation

**F-LM-005: Listing Images**
- Primary image displayed in search results
- Image gallery on listing detail page
- Zoom functionality on images
- Image order management (drag and drop)

**F-LM-006: Condition Standards**
- Predefined condition grades: Mint (M), Near Mint (NM), Lightly Played (LP), Moderately Played (MP), Heavily Played (HP), Damaged (DMG)
- Display condition descriptions and examples
- Require sellers to follow condition guidelines

**F-LM-007: Graded Cards**
- Support for professional grading (PSA, BGS, CGC)
- Fields: grading company, grade (1-10), certification number
- Display grading badge on listings
- Verify certification numbers (optional integration)

### 6.4 Marketplace & Discovery Module

**F-MD-001: Marketplace Homepage**
- Featured listings carousel
- Recently listed cards
- Popular cards (most viewed/sold)
- Browse by set (grid of set logos)
- Search bar with autocomplete

**F-MD-002: Search & Filter**
- Full-text search across card names and descriptions
- Filters:
  - Card set (multi-select)
  - Rarity (multi-select)
  - Condition (multi-select)
  - Price range (slider)
  - Graded/Ungraded
  - Seller rating (minimum)
  - Shipping location
  - Accept offers (yes/no)
- Save search preferences
- Clear all filters option

**F-MD-003: Sort Options**
- Sort by: Relevance, Price (low to high), Price (high to low), Newest, Ending Soon, Most Popular
- Default sort by relevance for search, newest for browse

**F-MD-004: Listing Detail Page**
- Display all listing information (price, condition, quantity, description)
- Image gallery with zoom
- Seller information card (name, rating, response time)
- "Add to Cart" button
- "Add to Wishlist" button
- "Make Offer" button (if enabled)
- "Ask Question" button (message seller)
- Related listings (same card, different conditions/prices)
- Shipping information and estimated delivery

**F-MD-005: Seller Storefront**
- Dedicated page for each seller
- Display seller profile, banner, logo
- List all active listings from seller
- Filter/sort within storefront
- Display seller reviews and ratings
- Show seller policies

**F-MD-006: Trending & Recommendations**
- "Trending Now" section based on views and sales
- Personalized recommendations based on browsing history
- "Customers also viewed" on listing pages
- "Complete your set" suggestions

### 6.5 Shopping Cart Module

**F-SC-001: Add to Cart**
- Add listing to cart with quantity selection
- Validate quantity available
- Prevent adding own listings to cart
- Show success message with cart preview

**F-SC-002: Cart Management**
- View all cart items with thumbnails, titles, prices
- Update quantity (with availability validation)
- Remove items
- Display subtotal
- Group items by seller
- Save cart for logged-in users (persist across sessions)

**F-SC-003: Cart Validation**
- Check item availability before checkout
- Remove sold-out items automatically with notification
- Validate price changes (notify user if price increased)
- Check seller account status (active/suspended)

**F-SC-004: Cart Persistence**
- Save cart for authenticated users
- Merge guest cart with user cart on login
- Cart expires after 30 days of inactivity

### 6.6 Checkout & Payment Module

**F-CP-001: Checkout Flow**
- Multi-step checkout: Shipping → Payment → Review → Confirm
- Display order summary sidebar (items, subtotal, shipping, tax, total)
- Progress indicator showing current step

**F-CP-002: Shipping Address**
- Select from saved addresses
- Add new address (name, street, city, state, zip, country, phone)
- Set default shipping address
- Validate address format
- Support international shipping (if seller allows)

**F-CP-003: Shipping Calculation**
- Calculate shipping cost per seller (if multiple sellers in cart)
- Display shipping method and estimated delivery date
- Support flat rate, calculated, and free shipping options
- Seller-defined shipping rates

**F-CP-004: Payment Processing**
- Support credit/debit cards (Visa, Mastercard, Amex, Discover)
- Support PayPal
- Tokenize and save payment methods (PCI compliant)
- CVV required for saved cards
- Display payment method icons

**F-CP-005: Order Review**
- Display complete order summary
- Show billing and shipping addresses
- Show payment method (last 4 digits)
- Display all fees and total
- Terms and conditions checkbox
- "Place Order" button

**F-CP-006: Payment Security**
- PCI DSS compliant payment processing
- SSL/TLS encryption for all transactions
- 3D Secure authentication for cards (optional)
- Fraud detection and prevention
- Do not store full card numbers

**F-CP-007: Tax Calculation**
- Calculate sales tax based on shipping address
- Support for multiple tax jurisdictions
- Display tax breakdown in order summary

**F-CP-008: Platform Fees**
- Charge seller fee per transaction (e.g., 5% + $0.30)
- Display fee breakdown in seller analytics
- Deduct fees before payout to seller

### 6.7 Order Management Module

**F-OM-001: Order Creation**
- Generate unique order number
- Create order record with all details (items, buyer, shipping, payment)
- Send order confirmation email to buyer
- Send new order notification to seller(s)
- Reduce listing inventory quantities

**F-OM-002: Order Status Tracking**
- Status workflow: Paid → Processing → Shipped → In Transit → Delivered → Completed
- Display status timeline with dates
- Allow seller to update status
- Automatic status updates based on tracking info (if integrated)

**F-OM-003: Buyer Order History**
- List all orders with order number, date, total, status
- Filter by status and date range
- Search orders by order number or item name
- View detailed order information
- Download invoice (PDF)

**F-OM-004: Seller Order Management**
- Dashboard showing orders by status (new, processing, shipped)
- Order details with buyer information and shipping address
- Print packing slip
- Update order status and add tracking number
- Bulk actions (mark as shipped, print labels)

**F-OM-005: Order Tracking**
- Display tracking number and carrier
- Link to carrier tracking page
- Show estimated delivery date
- Email notifications for status changes

**F-OM-006: Order Cancellation**
- Buyer can cancel order before shipping (within 1 hour of purchase)
- Seller can cancel order with reason (out of stock, pricing error)
- Automatic refund processing on cancellation
- Restore listing inventory on cancellation

**F-OM-007: Order Modifications**
- Buyer can request address change before shipping
- Seller can approve/deny modification requests
- Track modification history

### 6.8 Offer System Module

**F-OS-001: Make Offer**
- Buyer enters offer amount (must be less than listing price)
- Optional message to seller
- Set minimum offer threshold (e.g., 70% of listing price)
- Limit offers per buyer per listing (e.g., 3 active offers)

**F-OS-002: Offer Management (Seller)**
- View all offers (pending, accepted, declined, expired)
- Accept offer (reserves listing for buyer)
- Decline offer with optional message
- Counter offer with different price
- Set auto-decline threshold (e.g., auto-decline offers below 60%)

**F-OS-003: Offer Notifications**
- Notify seller of new offer
- Notify buyer of offer status change (accepted/declined/countered)
- Reminder notifications (offer expiring soon)

**F-OS-004: Offer Expiration**
- Offers expire after 48 hours if no seller response
- Accepted offers expire after 24 hours if buyer doesn't complete purchase
- Automatic status updates on expiration

**F-OS-005: Offer to Purchase Conversion**
- When offer accepted, generate unique checkout link for buyer
- Reserve listing quantity for buyer
- If buyer doesn't complete purchase within 24 hours, release reservation

### 6.9 Wishlist Module

**F-WL-001: Add to Wishlist**
- Add card or specific listing to wishlist
- Support multiple wishlists (e.g., "High Priority", "Future Purchases")
- Prevent duplicate entries

**F-WL-002: Wishlist Management**
- View all wishlist items with images and current prices
- Remove items from wishlist
- Move items to cart
- Organize items (drag and drop reorder)
- Share wishlist via link (public/private toggle)

**F-WL-003: Price Alerts**
- Set price alert threshold for wishlist items
- Notify when listing price drops below threshold
- Notify when new listing is created for wishlisted card
- Email and in-app notifications

**F-WL-004: Wishlist Analytics**
- Show total wishlist value
- Track price changes over time
- Show availability status (in stock / out of stock)

### 6.10 Review & Rating Module

**F-RR-001: Leave Review**
- Buyers can review sellers after order delivery
- One review per order per seller
- Required: star rating (1-5)
- Optional: written review (max 500 characters)
- Optional: category ratings (shipping speed, card condition, communication)

**F-RR-002: Review Display**
- Show reviews on seller profile page
- Display average rating and total review count
- Sort reviews by: Most Recent, Highest Rating, Lowest Rating
- Filter reviews by rating (5 stars, 4 stars, etc.)
- Show verified purchase badge

**F-RR-003: Review Moderation**
- Flag inappropriate reviews
- Admin can hide/remove reviews
- Seller can report reviews for moderation
- Prevent profanity and personal information in reviews

**F-RR-004: Seller Response**
- Seller can respond to reviews (one response per review)
- Response displayed below review
- Edit response within 24 hours

**F-RR-005: Rating Calculation**
- Calculate average rating across all reviews
- Weight recent reviews more heavily (last 90 days)
- Display rating breakdown (% of 5-star, 4-star, etc.)
- Update seller rating in real-time

### 6.11 Messaging Module

**F-MS-001: Send Message**
- Buyer can message seller about listing or order
- Message form with subject and body
- Attach images (optional, max 3 images)
- Context-aware messaging (auto-include listing/order reference)

**F-MS-002: Message Inbox**
- Unified inbox for all messages
- Organize by conversation threads
- Show unread message count
- Mark messages as read/unread
- Archive conversations

**F-MS-003: Message Notifications**
- Email notification for new messages
- In-app notification badge
- Push notifications (if mobile app)

**F-MS-004: Message Management**
- Search messages by keyword
- Filter by: unread, archived, listing, order
- Delete conversations
- Block users (prevent future messages)

**F-MS-005: Automated Messages**
- Auto-send message templates (order confirmation, shipping notification)
- Seller can create custom templates
- Merge fields for personalization (buyer name, order number, etc.)

### 6.12 Notification Module

**F-NT-001: Notification Types**
- Order updates (confirmed, shipped, delivered)
- Offer updates (received, accepted, declined, expired)
- Messages (new message received)
- Wishlist alerts (price drop, new listing)
- Account updates (password changed, email verified)
- Admin announcements

**F-NT-002: Notification Delivery**
- In-app notifications (notification center)
- Email notifications
- SMS notifications (optional, for critical updates)
- Push notifications (if mobile app)

**F-NT-003: Notification Preferences**
- User can enable/disable notification types
- Choose delivery method per notification type
- Quiet hours (no notifications during specified times)
- Digest mode (batch notifications into daily/weekly summary)

**F-NT-004: Notification Center**
- View all notifications in chronological order
- Mark as read/unread
- Clear all notifications
- Filter by type
- Click notification to navigate to relevant page

### 6.13 Search & Discovery Module

**F-SD-001: Advanced Search**
- Boolean operators (AND, OR, NOT)
- Exact phrase matching (quotes)
- Wildcard search
- Search within results

**F-SD-002: Search History**
- Save recent searches (last 10)
- Clear search history
- Quick access to recent searches

**F-SD-003: Saved Searches**
- Save search criteria with custom name
- Receive alerts when new listings match saved search
- Manage saved searches (edit, delete)

**F-SD-004: Autocomplete & Suggestions**
- Real-time search suggestions while typing
- Suggest card names, sets, and categories
- Show popular searches
- Correct typos and suggest alternatives

**F-SD-005: Faceted Navigation**
- Dynamic filters based on search results
- Show count of results per filter option
- Multi-select filters with AND/OR logic
- Clear individual filters or all filters

### 6.14 Analytics & Reporting Module

**F-AR-001: Seller Dashboard**
- Overview metrics: total sales, active listings, pending orders, average rating
- Sales chart (daily/weekly/monthly)
- Top selling cards
- Revenue breakdown by card set
- Inventory value calculation

**F-AR-002: Sales Reports**
- Generate reports by date range
- Export as CSV, Excel, PDF
- Include: order details, revenue, fees, net profit
- Filter by card, set, condition

**F-AR-003: Inventory Reports**
- Current inventory value
- Inventory by condition
- Inventory by set
- Low stock alerts (quantity below threshold)

**F-AR-004: Performance Metrics**
- Average order value
- Conversion rate (views to sales)
- Response time to messages
- Shipping time (order to shipped)
- Order fulfillment rate

**F-AR-005: Admin Analytics**
- Platform-wide metrics (total users, total sales, total listings)
- User growth charts
- Revenue by category/set
- Top sellers and buyers
- Geographic distribution of users

**F-AR-006: Market Insights**
- Price trends for cards over time
- Most searched cards
- Fastest selling cards
- Market demand indicators

### 6.15 Admin Module

**F-AD-001: User Management**
- View all users with search and filters
- View user details and activity history
- Suspend/unsuspend user accounts
- Ban users (permanent suspension)
- Verify seller accounts
- Reset user passwords
- Impersonate users (for support purposes)

**F-AD-002: Listing Moderation**
- Review flagged listings
- Remove inappropriate listings
- Edit listing details (if necessary)
- Feature listings on homepage
- Bulk moderation actions

**F-AD-003: Order Management**
- View all orders with advanced filters
- Manually process refunds
- Cancel orders on behalf of users
- Resolve payment issues
- Export order data

**F-AD-004: Dispute Resolution**
- View all disputes (open, escalated, resolved)
- Review evidence from both parties
- Communicate with buyer and seller
- Make resolution decisions (refund, partial refund, no refund)
- Close disputes with notes

**F-AD-005: Card Database Management**
- Add new cards to database
- Edit card information
- Upload official card images
- Manage card sets
- Bulk import cards via CSV

**F-AD-006: Platform Configuration**
- Set platform fee percentage and fixed fee
- Configure payment gateways
- Set tax rates by jurisdiction
- Manage email templates
- Configure notification settings
- Set business rules (max offer attempts, order cancellation window, etc.)

**F-AD-007: Content Management**
- Manage homepage featured listings
- Create and edit static pages (About, FAQ, Terms, Privacy)
- Manage announcements and banners
- Upload platform assets (logos, icons)

**F-AD-008: Reporting & Logs**
- View system logs (errors, warnings)
- Audit logs (user actions, admin actions)
- Generate compliance reports
- Monitor system health and performance

### 6.16 Financial Module

**F-FN-001: Transaction Recording**
- Record all financial transactions (sales, refunds, fees, payouts)
- Link transactions to orders and users
- Track transaction status (pending, completed, failed)

**F-FN-002: Seller Payouts**
- Calculate seller earnings (order total - platform fee - payment processing fee)
- Hold funds for configurable period (e.g., 7 days after delivery)
- Batch payouts (weekly, bi-weekly, monthly)
- Support multiple payout methods (bank transfer, PayPal)
- Generate payout reports

**F-FN-003: Refund Processing**
- Process full and partial refunds
- Refund to original payment method
- Track refund status
- Adjust seller payouts for refunded orders
- Handle refund fees

**F-FN-004: Fee Management**
- Calculate platform fees per transaction
- Calculate payment processing fees
- Display fee breakdown to sellers
- Generate fee reports for accounting

**F-FN-005: Financial Reporting**
- Revenue reports (gross, net, by category)
- Payout reports (pending, completed)
- Refund reports
- Fee collection reports
- Tax reports (sales tax collected)

### 6.17 Dispute & Support Module

**F-DS-001: Create Dispute**
- Buyer or seller can initiate dispute
- Dispute types: Item not received, Item not as described, Damaged item, Return request, Other
- Upload evidence (photos, messages, documents)
- Provide detailed description

**F-DS-002: Dispute Workflow**
- Status: Open → Under Review → Escalated → Resolved
- Automatic escalation if no resolution within 48 hours
- Both parties can add comments and evidence
- Admin can request additional information

**F-DS-003: Resolution Options**
- Full refund to buyer
- Partial refund to buyer
- Return item for refund
- No refund (buyer keeps item)
- Custom resolution (e.g., replacement, store credit)

**F-DS-004: Support Tickets**
- Users can create support tickets for non-order issues
- Ticket categories: Account, Payment, Technical, General
- Ticket priority levels
- Admin can assign tickets to support staff
- Track ticket status and response time

**F-DS-005: Help Center**
- FAQ section with common questions
- Searchable knowledge base
- Category-based article organization
- User feedback on article helpfulness

## 7. Business Rules

### 7.1 User & Account Rules

**BR-UA-001:** Email addresses must be unique across all users.

**BR-UA-002:** Users must verify email before accessing buyer/seller features.

**BR-UA-003:** Passwords must be at least 8 characters with at least one uppercase, one lowercase, and one number.

**BR-UA-004:** Users must be 13 years or older to create an account (COPPA compliance).

**BR-UA-005:** Suspended users cannot create listings, purchase items, or send messages.

**BR-UA-006:** Banned users cannot log in or create new accounts with the same email.

**BR-UA-007:** Users can only have one active seller profile per account.

**BR-UA-008:** Seller profiles require payout information before creating listings.

### 7.2 Listing Rules

**BR-LS-001:** Listings must reference a valid card from the master card database.

**BR-LS-002:** Listing price must be greater than $0.01 and less than $1,000,000.

**BR-LS-003:** Listing quantity must be between 1 and 1,000.

**BR-LS-004:** At least one image is required for active listings.

**BR-LS-005:** Maximum 10 images per listing.

**BR-LS-006:** Sellers cannot purchase their own listings.

**BR-LS-007:** Listings automatically set to "Sold Out" when quantity reaches 0.

**BR-LS-008:** Inactive listings (no views or sales in 365 days) are automatically archived.

**BR-LS-009:** Graded cards must include grading company, grade, and certification number.

**BR-LS-010:** Minimum offer amount (if enabled) must be at least 50% of listing price.

**BR-LS-011:** Sellers cannot edit card or condition after first sale from listing.

**BR-LS-012:** Listing descriptions cannot contain external links or contact information.

### 7.3 Pricing & Fees Rules

**BR-PF-001:** Platform fee is 5% of sale price + $0.30 per transaction.

**BR-PF-002:** Minimum platform fee is $0.50 per transaction.

**BR-PF-003:** Sellers receive payout after 7 days from delivery confirmation.

**BR-PF-004:** Refunds include platform fee refund but not payment processing fee.

**BR-PF-005:** Shipping costs are set by seller and not subject to platform fees.

**BR-PF-006:** Sales tax is calculated based on buyer's shipping address.

**BR-PF-007:** Sellers cannot charge more than actual shipping cost + $1 handling fee.

### 7.4 Order & Purchase Rules

**BR-OP-001:** Orders can only be placed for active listings with available quantity.

**BR-OP-002:** Buyers cannot purchase from suspended or banned sellers.

**BR-OP-003:** Order total must be at least $1.00.

**BR-OP-004:** Maximum order total is $50,000 per transaction.

**BR-OP-005:** Buyers can cancel orders within 1 hour of purchase if not yet shipped.

**BR-OP-006:** Sellers must ship orders within 3 business days unless otherwise stated.

**BR-OP-007:** Orders automatically marked as delivered 7 days after tracking shows delivery.

**BR-OP-008:** Buyers have 30 days from delivery to request return or open dispute.

**BR-OP-009:** Sellers cannot modify order total after payment is processed.

**BR-OP-010:** Each order must have a unique order number (format: ORD-YYYYMMDD-XXXXX).

### 7.5 Offer Rules

**BR-OF-001:** Offers must be less than the current listing price.

**BR-OF-002:** Offers must be at least 50% of listing price (or seller's minimum threshold).

**BR-OF-003:** Buyers can have maximum 3 active offers per listing.

**BR-OF-004:** Offers expire after 48 hours if seller doesn't respond.

**BR-OF-005:** Accepted offers expire after 24 hours if buyer doesn't complete purchase.

**BR-OF-006:** Buyers cannot make offers on their own listings.

**BR-OF-007:** Offers are automatically declined if listing is sold before seller responds.

**BR-OF-008:** Counter offers reset the 48-hour expiration timer.

### 7.6 Review & Rating Rules

**BR-RR-001:** Only buyers who completed a purchase can leave reviews.

**BR-RR-002:** One review per order per seller.

**BR-RR-003:** Reviews can be edited within 48 hours of posting.

**BR-RR-004:** Reviews cannot be deleted by users (only by admin for policy violations).

**BR-RR-005:** Seller responses can be edited within 24 hours of posting.

**BR-RR-006:** Reviews must be at least 10 characters if written review is provided.

**BR-RR-007:** Reviews cannot contain profanity, personal information, or external links.

**BR-RR-008:** Seller rating is calculated from reviews in last 12 months.

**BR-RR-009:** Minimum 5 reviews required before average rating is displayed.

### 7.7 Inventory & Stock Rules

**BR-IS-001:** Listing quantity is reduced immediately upon order payment.

**BR-IS-002:** Quantity is restored if order is cancelled before shipping.

**BR-IS-003:** Quantity is restored if payment fails.

**BR-IS-004:** Sellers cannot reduce quantity below number of pending orders.

**BR-IS-005:** Out-of-stock listings remain visible but cannot be purchased.

**BR-IS-006:** Sellers receive low stock alert when quantity reaches 1.

### 7.8 Shipping Rules

**BR-SH-001:** Sellers must provide tracking number within 3 business days of order.

**BR-SH-002:** Domestic shipping must be completed within 10 business days.

**BR-SH-003:** International shipping must be completed within 30 business days.

**BR-SH-004:** Sellers are responsible for shipping costs on returns due to seller error.

**BR-SH-005:** Buyers are responsible for return shipping costs for buyer's remorse.

**BR-SH-006:** Free shipping threshold can be set by seller (e.g., orders over $50).

### 7.9 Dispute & Return Rules

**BR-DR-001:** Disputes must be opened within 30 days of delivery.

**BR-DR-002:** Buyers must provide evidence (photos) for "not as described" disputes.

**BR-DR-003:** Sellers have 48 hours to respond to disputes before auto-escalation.

**BR-DR-004:** Items must be returned in same condition as received for full refund.

**BR-DR-005:** Refunds are processed within 5 business days of dispute resolution.

**BR-DR-006:** Partial refunds must be at least 10% and at most 90% of order total.

**BR-DR-007:** Sellers with dispute rate above 5% receive warning.

**BR-DR-008:** Sellers with dispute rate above 10% are suspended pending review.

### 7.10 Security & Fraud Rules

**BR-SF-001:** Maximum 5 failed login attempts before 15-minute account lockout.

**BR-SF-002:** Password reset links expire after 1 hour.

**BR-SF-003:** Email verification links expire after 24 hours.

**BR-SF-004:** Sessions expire after 30 days of inactivity.

**BR-SF-005:** Payment information must be tokenized (never store full card numbers).

**BR-SF-006:** Suspicious orders (high value, new account) are flagged for manual review.

**BR-SF-007:** Users cannot change email more than once per 30 days.

**BR-SF-008:** Payout information changes require email confirmation.

### 7.11 Content & Moderation Rules

**BR-CM-001:** Listing titles must be between 10 and 100 characters.

**BR-CM-002:** Listing descriptions must be between 20 and 2,000 characters.

**BR-CM-003:** Images must be JPG or PNG format, max 5MB each.

**BR-CM-004:** Prohibited content: counterfeit cards, stolen cards, inappropriate images.

**BR-CM-005:** Listings with 3+ user reports are automatically hidden pending review.

**BR-CM-006:** Users with 5+ content violations are permanently banned.

**BR-CM-007:** Seller profiles cannot contain external links or contact information.

### 7.12 Notification Rules

**BR-NT-001:** Order confirmation emails sent within 5 minutes of purchase.

**BR-NT-002:** Shipping notification emails sent within 1 hour of tracking number entry.

**BR-NT-003:** Price alert notifications sent maximum once per day per card.

**BR-NT-004:** Digest emails sent at 9 AM user's local time.

**BR-NT-005:** Critical notifications (security, payment issues) cannot be disabled.

**BR-NT-006:** Marketing emails can be unsubscribed without affecting transactional emails.

## 8. Non-Functional Requirements

### 8.1 Performance Requirements

**NFR-PF-001:** Page load time must be under 2 seconds for 95% of requests.

**NFR-PF-002:** Search results must return within 500ms for 90% of queries.

**NFR-PF-003:** API response time must be under 200ms for 95% of requests.

**NFR-PF-004:** System must support 10,000 concurrent users.

**NFR-PF-005:** Database queries must be optimized with proper indexing (query time < 100ms).

**NFR-PF-006:** Image loading must use lazy loading and CDN for optimization.

**NFR-PF-007:** System must handle 1,000 transactions per hour during peak times.

**NFR-PF-008:** Checkout process must complete within 30 seconds from cart to confirmation.

### 8.2 Scalability Requirements

**NFR-SC-001:** System architecture must support horizontal scaling.

**NFR-SC-002:** Database must support read replicas for load distribution.

**NFR-SC-003:** Static assets must be served via CDN (CloudFlare, AWS CloudFront).

**NFR-SC-004:** Application must support auto-scaling based on traffic load.

**NFR-SC-005:** System must handle 100,000+ listings without performance degradation.

**NFR-SC-006:** System must support 50,000+ registered users.

**NFR-SC-007:** File storage must use cloud object storage (AWS S3, Google Cloud Storage).

### 8.3 Security Requirements

**NFR-SE-001:** All data transmission must use HTTPS/TLS 1.3.

**NFR-SE-002:** Passwords must be hashed using bcrypt with minimum 12 rounds.

**NFR-SE-003:** Payment processing must be PCI DSS Level 1 compliant.

**NFR-SE-004:** API endpoints must implement rate limiting (100 requests/minute per user).

**NFR-SE-005:** SQL injection prevention through parameterized queries/ORM.

**NFR-SE-006:** XSS prevention through input sanitization and output encoding.

**NFR-SE-007:** CSRF protection on all state-changing requests.

**NFR-SE-008:** Sensitive data (SSN, payment info) must be encrypted at rest (AES-256).

**NFR-SE-009:** Regular security audits and penetration testing (quarterly).

**NFR-SE-010:** Implement Web Application Firewall (WAF) for DDoS protection.

**NFR-SE-011:** Multi-factor authentication (MFA) available for user accounts.

**NFR-SE-012:** Admin actions must be logged in audit trail.

### 8.4 Availability & Reliability Requirements

**NFR-AR-001:** System uptime must be 99.9% (excluding planned maintenance).

**NFR-AR-002:** Planned maintenance windows must be announced 48 hours in advance.

**NFR-AR-003:** Database backups must be performed daily with 30-day retention.

**NFR-AR-004:** Point-in-time recovery must be available for last 7 days.

**NFR-AR-005:** Disaster recovery plan with RTO (Recovery Time Objective) of 4 hours.

**NFR-AR-006:** RPO (Recovery Point Objective) of 1 hour for data loss.

**NFR-AR-007:** Implement health checks and monitoring for all critical services.

**NFR-AR-008:** Automated failover for database and application servers.

### 8.5 Usability Requirements

**NFR-US-001:** Interface must be responsive and mobile-friendly (mobile-first design).

**NFR-US-002:** Support for modern browsers (Chrome, Firefox, Safari, Edge - last 2 versions).

**NFR-US-003:** WCAG 2.1 Level AA accessibility compliance.

**NFR-US-004:** Keyboard navigation support for all interactive elements.

**NFR-US-005:** Screen reader compatibility (ARIA labels and semantic HTML).

**NFR-US-006:** Color contrast ratio minimum 4.5:1 for text.

**NFR-US-007:** Error messages must be clear and actionable.

**NFR-US-008:** Form validation must provide real-time feedback.

**NFR-US-009:** Loading states and progress indicators for async operations.

**NFR-US-010:** Maximum 3 clicks to reach any major feature from homepage.

### 8.6 Compatibility Requirements

**NFR-CP-001:** Support iOS 13+ and Android 9+ for mobile web.

**NFR-CP-002:** Support desktop resolutions from 1280x720 to 4K.

**NFR-CP-003:** Support tablet devices (iPad, Android tablets).

**NFR-CP-004:** Graceful degradation for older browsers with feature detection.

**NFR-CP-005:** API versioning to maintain backward compatibility.

### 8.7 Maintainability Requirements

**NFR-MT-001:** Code must follow established style guides and linting rules.

**NFR-MT-002:** Minimum 80% unit test coverage for business logic.

**NFR-MT-003:** Integration tests for critical user workflows.

**NFR-MT-004:** Comprehensive API documentation (OpenAPI/Swagger).

**NFR-MT-005:** Code reviews required for all changes before deployment.

**NFR-MT-006:** Continuous Integration/Continuous Deployment (CI/CD) pipeline.

**NFR-MT-007:** Structured logging with log levels (DEBUG, INFO, WARN, ERROR).

**NFR-MT-008:** Centralized log aggregation and monitoring (ELK stack, Datadog, etc.).

**NFR-MT-009:** Database migrations must be reversible.

**NFR-MT-010:** Feature flags for gradual rollout of new features.

### 8.8 Compliance & Legal Requirements

**NFR-CL-001:** GDPR compliance for EU users (data privacy, right to deletion).

**NFR-CL-002:** CCPA compliance for California users.

**NFR-CL-003:** COPPA compliance (no users under 13).

**NFR-CL-004:** Clear Terms of Service and Privacy Policy.

**NFR-CL-005:** Cookie consent banner for EU users.

**NFR-CL-006:** Data retention policy (delete inactive accounts after 3 years).

**NFR-CL-007:** User data export functionality (download all personal data).

**NFR-CL-008:** Anti-money laundering (AML) compliance for high-value transactions.

**NFR-CL-009:** Sales tax collection and remittance per jurisdiction requirements.

### 8.9 Monitoring & Analytics Requirements

**NFR-MA-001:** Real-time application performance monitoring (APM).

**NFR-MA-002:** Error tracking and alerting (Sentry, Rollbar, etc.).

**NFR-MA-003:** User analytics and behavior tracking (Google Analytics, Mixpanel).

**NFR-MA-004:** Conversion funnel tracking (cart abandonment, checkout completion).

**NFR-MA-005:** Server and infrastructure monitoring (CPU, memory, disk, network).

**NFR-MA-006:** Database performance monitoring (slow queries, connection pool).

**NFR-MA-007:** Uptime monitoring with alerts for downtime.

**NFR-MA-008:** Business metrics dashboard (sales, revenue, active users).

### 8.10 Data Requirements

**NFR-DT-001:** Database must support ACID transactions.

**NFR-DT-002:** Soft delete for user-generated content (retain for 90 days).

**NFR-DT-003:** Data anonymization for deleted user accounts.

**NFR-DT-004:** Audit trail for financial transactions (immutable log).

**NFR-DT-005:** Data validation at application and database levels.

**NFR-DT-006:** Referential integrity enforced through foreign keys.

**NFR-DT-007:** Optimistic locking for concurrent updates (prevent race conditions).

**NFR-DT-008:** Full-text search indexing for cards and listings (Elasticsearch, PostgreSQL FTS).

### 8.11 Integration Requirements

**NFR-IN-001:** Payment gateway integration (Stripe, PayPal).

**NFR-IN-002:** Email service provider integration (SendGrid, AWS SES).

**NFR-IN-003:** SMS service integration for notifications (Twilio, optional).

**NFR-IN-004:** Shipping carrier API integration for tracking (USPS, FedEx, UPS - optional).

**NFR-IN-005:** Cloud storage integration for images (AWS S3, Google Cloud Storage).

**NFR-IN-006:** CDN integration for static assets (CloudFlare, AWS CloudFront).

**NFR-IN-007:** OAuth providers integration (Google, Facebook - optional).

**NFR-IN-008:** Card grading verification API (PSA, BGS - optional).

**NFR-IN-009:** Tax calculation service (Avalara, TaxJar - optional).

### 8.12 Deployment Requirements

**NFR-DP-001:** Containerized deployment using Docker.

**NFR-DP-002:** Orchestration using Kubernetes or similar (optional for scale).

**NFR-DP-003:** Blue-green or canary deployment strategy for zero-downtime updates.

**NFR-DP-004:** Environment separation (development, staging, production).

**NFR-DP-005:** Infrastructure as Code (Terraform, CloudFormation).

**NFR-DP-006:** Automated deployment pipeline triggered by git commits.

**NFR-DP-007:** Rollback capability within 5 minutes of deployment.

**NFR-DP-008:** Environment variables for configuration (no hardcoded secrets).

---

**Document Version:** 1.0  
**Last Updated:** 2025-01-10  
**Domain:** https://harsh.dev.dalfin.ai  
**Prepared By:** Senior Product Manager