# Product Requirements Document: Pokémon Resell Platform

## 1. Overview

The Pokémon Resell Platform is a marketplace application that enables users to buy and sell Pokémon trading cards. Sellers can list their cards with pricing and condition details, while buyers can browse listings, make purchases, and track their orders. The platform facilitates secure transactions between collectors and provides inventory management for sellers.

## 2. User Roles

### Guest (Unauthenticated User)
- Browse public card listings
- Search and filter available cards
- View card details
- Register for an account
- Log in to existing account

### Buyer (Authenticated User)
- All Guest permissions
- Add cards to cart
- Purchase cards
- View order history
- View purchase receipts
- Update profile information
- Leave reviews on purchased cards

### Seller (Authenticated User)
- All Buyer permissions
- Create card listings
- Edit own listings
- Mark listings as sold
- Delete own listings
- View sales history
- Manage inventory
- View earnings dashboard

### Admin
- All Seller permissions
- View all users
- Suspend/activate user accounts
- Remove inappropriate listings
- View platform analytics
- Manage platform fees
- Resolve disputes

## 3. Core Entities

### User
Represents a registered user on the platform with authentication credentials and profile information.

### Card Listing
Represents a Pokémon card available for sale, including details about the card, condition, price, and availability status.

### Order
Represents a purchase transaction containing one or more card listings, payment information, and fulfillment status.

### Order Item
Represents an individual card listing within an order, linking orders to specific card listings.

### Review
Represents buyer feedback on a purchased card listing, including rating and comments.

### Cart
Represents a temporary collection of card listings a buyer intends to purchase.

### Cart Item
Represents an individual card listing within a user's cart.

### Transaction
Represents the financial record of a completed order, including payment method and amount.

## 4. Entity Relationships

### User Relationships
- **User → Card Listing**: One-to-Many (a user can create multiple listings)
- **User → Order (as Buyer)**: One-to-Many (a user can place multiple orders)
- **User → Review**: One-to-Many (a user can write multiple reviews)
- **User → Cart**: One-to-One (each user has one cart)

### Card Listing Relationships
- **Card Listing → User (Seller)**: Many-to-One (each listing belongs to one seller)
- **Card Listing → Order Item**: One-to-Many (a listing can appear in multiple orders over time, but only sold once)
- **Card Listing → Review**: One-to-Many (a listing can have multiple reviews)
- **Card Listing → Cart Item**: One-to-Many (a listing can be in multiple carts before purchase)

### Order Relationships
- **Order → User (Buyer)**: Many-to-One (each order belongs to one buyer)
- **Order → Order Item**: One-to-Many (an order contains multiple items)
- **Order → Transaction**: One-to-One (each order has one transaction record)

### Cart Relationships
- **Cart → User**: One-to-One (each cart belongs to one user)
- **Cart → Cart Item**: One-to-Many (a cart contains multiple items)

### Order Item Relationships
- **Order Item → Order**: Many-to-One (each item belongs to one order)
- **Order Item → Card Listing**: Many-to-One (each item references one listing)

### Cart Item Relationships
- **Cart Item → Cart**: Many-to-One (each cart item belongs to one cart)
- **Cart Item → Card Listing**: Many-to-One (each cart item references one listing)

### Review Relationships
- **Review → User**: Many-to-One (each review is written by one user)
- **Review → Card Listing**: Many-to-One (each review is for one listing)

### Transaction Relationships
- **Transaction → Order**: One-to-One (each transaction is for one order)

## 5. Key Workflows

### User Registration & Authentication
1. Guest navigates to registration page
2. Guest provides email, password, username, and role preference (Buyer/Seller)
3. System validates input and checks for duplicate email
4. System creates user account with "Buyer" role by default
5. System sends confirmation email (optional)
6. User can log in with credentials
7. System generates authentication token
8. User is redirected to dashboard

### Creating a Card Listing (Seller)
1. Seller navigates to "Create Listing" page
2. Seller enters card details:
   - Card name
   - Pokémon name
   - Set/series
   - Card number
   - Rarity
   - Condition (Mint, Near Mint, Lightly Played, Moderately Played, Heavily Played, Damaged)
   - Price
   - Quantity available
   - Description
   - Upload images (1-5 photos)
3. System validates all required fields
4. System creates listing with status "Available"
5. Listing appears in marketplace
6. Seller receives confirmation

### Browsing and Searching Cards (Any User)
1. User navigates to marketplace
2. System displays all available listings
3. User can apply filters:
   - Price range
   - Condition
   - Rarity
   - Pokémon name
   - Set/series
4. User can sort by:
   - Price (low to high, high to low)
   - Date listed (newest, oldest)
   - Condition
5. System returns filtered/sorted results
6. User clicks on listing to view details

### Adding to Cart and Checkout (Buyer)
1. Buyer views card listing details
2. Buyer clicks "Add to Cart"
3. System validates listing is still available
4. System adds listing to buyer's cart
5. Buyer navigates to cart
6. Buyer reviews cart items
7. Buyer can remove items or proceed to checkout
8. Buyer clicks "Checkout"
9. System validates all cart items are still available
10. Buyer enters shipping address
11. Buyer selects payment method
12. Buyer confirms order
13. System creates order with status "Pending"
14. System marks all card listings in order as "Sold"
15. System creates transaction record
16. System clears buyer's cart
17. System sends order confirmation to buyer
18. System notifies sellers of new sales
19. Order status updates to "Confirmed"

### Order Fulfillment
1. Seller views "My Sales" dashboard
2. Seller sees new order
3. Seller marks order as "Shipped" and enters tracking number
4. System updates order status to "Shipped"
5. System notifies buyer of shipment
6. Buyer receives card
7. Buyer marks order as "Delivered" (or auto-updates after time period)
8. System updates order status to "Delivered"
9. System prompts buyer to leave review

### Leaving a Review (Buyer)
1. Buyer navigates to order history
2. Buyer selects delivered order
3. Buyer clicks "Leave Review" on specific card
4. Buyer provides:
   - Star rating (1-5)
   - Written review (optional)
5. System validates buyer purchased this card
6. System creates review
7. Review appears on card listing page
8. Seller is notified of new review

### Managing Listings (Seller)
1. Seller navigates to "My Listings"
2. System displays all seller's listings
3. Seller can:
   - Edit listing details (if not sold)
   - Mark as sold manually
   - Delete listing (if not sold)
   - View listing analytics (views, favorites)
4. System updates listing accordingly
5. Changes reflect immediately in marketplace

## 6. Features & Requirements

### 6.1 Authentication & User Management

#### F-AUTH-001: User Registration
- System must allow users to register with email and password
- System must require username (unique)
- System must validate email format
- System must enforce password strength (min 8 characters, 1 uppercase, 1 number)
- System must assign default role as "Buyer"

#### F-AUTH-002: User Login
- System must authenticate users with email/password
- System must generate JWT token upon successful login
- System must return user profile and role information
- System must handle invalid credentials gracefully

#### F-AUTH-003: User Profile Management
- Users must be able to view their profile
- Users must be able to update: username, email, phone, shipping address
- Users must be able to change password
- System must validate all profile updates

#### F-AUTH-004: Role Management
- System must support Buyer, Seller, and Admin roles
- Users can have multiple roles (e.g., both Buyer and Seller)
- Sellers must have additional profile fields: business name (optional), seller rating

### 6.2 Card Listing Management

#### F-LIST-001: Create Listing
- Sellers must be able to create new card listings
- Required fields: card name, Pokémon name, price, condition, quantity
- Optional fields: set/series, card number, rarity, description
- System must support image upload (1-5 images, max 5MB each)
- System must validate price > 0
- System must validate quantity > 0

#### F-LIST-002: Edit Listing
- Sellers must be able to edit their own listings
- System must prevent editing of sold listings
- System must update "last modified" timestamp
- System must maintain edit history (optional)

#### F-LIST-003: Delete Listing
- Sellers must be able to delete their own unsold listings
- System must soft-delete listings (mark as deleted, not remove from database)
- System must prevent deletion of sold listings

#### F-LIST-004: View Listing Details
- All users must be able to view listing details
- System must display: all card info, seller info, images, reviews, availability status
- System must show seller rating and review count
- System must track view count

#### F-LIST-005: List My Listings
- Sellers must be able to view all their listings
- System must show status: Available, Sold, Deleted
- System must support filtering by status
- System must show analytics: views, date listed, sales

### 6.3 Marketplace & Search

#### F-MARKET-001: Browse Listings
- All users must be able to browse available listings
- System must display listings in grid/list view
- System must paginate results (20 per page)
- System must show thumbnail image, card name, price, condition

#### F-MARKET-002: Search Functionality
- Users must be able to search by:
  - Card name (partial match)
  - Pokémon name (partial match)
  - Set/series
- System must return results in real-time (debounced)
- System must highlight search terms in results

#### F-MARKET-003: Filter Listings
- Users must be able to filter by:
  - Price range (min-max)
  - Condition (multi-select)
  - Rarity (multi-select)
  - Availability status
- System must allow multiple filters simultaneously
- System must show count of results for each filter option

#### F-MARKET-004: Sort Listings
- Users must be able to sort by:
  - Price (ascending/descending)
  - Date listed (newest/oldest)
  - Condition (best to worst)
  - Popularity (most viewed)
- System must maintain sort preference during session

### 6.4 Shopping Cart

#### F-CART-001: Add to Cart
- Buyers must be able to add available listings to cart
- System must validate listing is still available
- System must prevent adding same listing twice
- System must show confirmation message

#### F-CART-002: View Cart
- Buyers must be able to view all items in cart
- System must display: card image, name, price, seller
- System must calculate and display total price
- System must show item count

#### F-CART-003: Remove from Cart
- Buyers must be able to remove items from cart
- System must update total price immediately
- System must show confirmation message

#### F-CART-004: Cart Persistence
- System must persist cart items for logged-in users
- System must maintain cart across sessions
- System must validate cart items are still available before checkout

### 6.5 Order Management

#### F-ORDER-001: Checkout Process
- Buyers must be able to checkout with cart items
- System must require shipping address
- System must validate all cart items are still available
- System must calculate total amount
- System must support payment method selection (simulated)

#### F-ORDER-002: Create Order
- System must create order with status "Pending"
- System must create order items for each cart item
- System must mark all card listings as "Sold"
- System must reduce listing quantity (if quantity > 1)
- System must create transaction record
- System must clear buyer's cart
- System must generate unique order number

#### F-ORDER-003: View Order History (Buyer)
- Buyers must be able to view all their orders
- System must display: order number, date, total, status, items
- System must support filtering by status
- System must allow viewing order details

#### F-ORDER-004: View Sales History (Seller)
- Sellers must be able to view all their sales
- System must display: order number, buyer, date, amount, status
- System must show earnings summary
- System must support filtering by date range and status

#### F-ORDER-005: Update Order Status
- Sellers must be able to update order status to "Shipped"
- Sellers must be able to add tracking number
- System must notify buyer of status changes
- Buyers must be able to mark order as "Delivered"
- System must auto-update to "Delivered" after 14 days of "Shipped" status

#### F-ORDER-006: Order Details
- Users must be able to view complete order details
- System must display: all items, prices, shipping address, status history, tracking info
- System must show seller information for each item
- System must provide option to contact seller (optional)

### 6.6 Reviews & Ratings

#### F-REVIEW-001: Create Review
- Buyers must be able to review purchased cards
- System must validate buyer purchased the card
- System must allow one review per card per buyer
- Required fields: star rating (1-5)
- Optional fields: written review (max 500 characters)

#### F-REVIEW-002: View Reviews
- All users must be able to view reviews on listing page
- System must display: reviewer name, rating, review text, date
- System must calculate and display average rating
- System must show total review count

#### F-REVIEW-003: Edit Review
- Buyers must be able to edit their own reviews within 30 days
- System must update "last modified" timestamp
- System must recalculate average rating

#### F-REVIEW-004: Delete Review
- Buyers must be able to delete their own reviews
- Admins must be able to delete any review
- System must recalculate average rating

### 6.7 Admin Features

#### F-ADMIN-001: User Management
- Admins must be able to view all users
- Admins must be able to search users by email/username
- Admins must be able to suspend/activate user accounts
- System must prevent suspended users from logging in

#### F-ADMIN-002: Listing Moderation
- Admins must be able to view all listings
- Admins must be able to remove inappropriate listings
- System must notify seller when listing is removed
- Admins must be able to provide removal reason

#### F-ADMIN-003: Platform Analytics
- Admins must be able to view dashboard with:
  - Total users (by role)
  - Total listings (by status)
  - Total orders
  - Total revenue
  - Recent activity
- System must support date range filtering
- System must provide export functionality (CSV)

#### F-ADMIN-004: Dispute Resolution
- Admins must be able to view flagged orders/listings
- Admins must be able to communicate with buyers and sellers
- Admins must be able to issue refunds (simulated)
- System must log all admin actions

## 7. Business Rules

### BR-001: User Account Rules
- Email addresses must be unique across all users
- Usernames must be unique across all users
- Users must be at least 13 years old (self-declared)
- Suspended users cannot create listings or place orders
- Users cannot delete their account if they have pending orders

### BR-002: Listing Rules
- Listing price must be greater than $0.01
- Listing price must not exceed $100,000
- Quantity must be at least 1
- Sellers cannot purchase their own listings
- Listings must have at least one image
- Card name and Pokémon name are required fields
- Sold listings cannot be edited or deleted
- Listings are automatically marked as "Sold" when purchased

### BR-003: Cart Rules
- Users can only add available listings to cart
- Users cannot add the same listing multiple times
- Cart items must be validated for availability before checkout
- Cart is cleared after successful order creation
- Cart items from suspended sellers are automatically removed

### BR-004: Order Rules
- Orders cannot be cancelled after status is "Shipped"
- Orders must have at least one item
- Order total must match sum of item prices
- Buyers cannot order from suspended sellers
- Orders automatically mark to "Delivered" 14 days after "Shipped"
- Minimum order value: $1.00

### BR-005: Review Rules
- Only buyers who purchased a card can review it
- One review per card per buyer
- Reviews can only be edited within 30 days of creation
- Star rating must be between 1 and 5
- Review text maximum length: 500 characters
- Reviews cannot be created for orders older than 90 days

### BR-006: Payment Rules (Simulated)
- All payments are simulated (no real payment processing)
- System assumes all payments are successful
- Transaction records are created for audit purposes
- Refunds are simulated and logged

### BR-007: Image Upload Rules
- Supported formats: JPG, PNG, WEBP
- Maximum file size: 5MB per image
- Minimum 1 image, maximum 5 images per listing
- Images are compressed and resized on upload
- Inappropriate images can be flagged and removed by admins

### BR-008: Seller Rules
- Sellers must have verified email to create listings
- Sellers with rating below 2.0 receive warning notification
- Sellers with more than 5 removed listings are automatically suspended
- Sellers can view earnings but cannot withdraw (withdrawal feature not implemented)

### BR-009: Search & Filter Rules
- Search results exclude sold and deleted listings
- Price filter maximum range: $0 - $100,000
- Search is case-insensitive
- Pagination default: 20 items per page

### BR-010: Data Retention Rules
- Deleted listings are soft-deleted and retained for 90 days
- Order history is retained indefinitely
- User accounts are soft-deleted and retained for 1 year
- Transaction records are retained indefinitely for audit purposes

## 8. Non-Functional Requirements

### NFR-001: Performance
- Page load time must be under 2 seconds for 95% of requests
- Search results must return within 500ms
- Image upload must complete within 10 seconds
- API response time must be under 200ms for 90% of requests
- System must support 100 concurrent users
- Database queries must be optimized with proper indexing

### NFR-002: Security
- All passwords must be hashed using bcrypt (min 10 rounds)
- Authentication must use JWT tokens with 24-hour expiration
- All API endpoints must validate authentication and authorization
- Sensitive data (passwords, payment info) must never be logged
- SQL injection prevention through parameterized queries
- XSS prevention through input sanitization
- HTTPS must be enforced for all connections
- Rate limiting: 100 requests per minute per user

### NFR-003: Scalability
- Database must support horizontal scaling
- Image storage must use cloud storage (S3 or equivalent)
- System must handle up to 10,000 listings
- System must handle up to 1,000 orders per day
- Caching strategy for frequently accessed data (listings, user profiles)

### NFR-004: Availability
- System uptime target: 99.5%
- Scheduled maintenance windows: off-peak hours only
- Database backups: daily automated backups
- Backup retention: 30 days

### NFR-005: Usability
- Interface must be responsive (mobile, tablet, desktop)
- Forms must provide real-time validation feedback
- Error messages must be clear and actionable
- Loading states must be indicated for all async operations
- Accessibility: WCAG 2.1 Level AA compliance target

### NFR-006: Data Integrity
- All database transactions must be ACID compliant
- Foreign key constraints must be enforced
- Concurrent order creation must prevent double-selling
- Optimistic locking for inventory updates

### NFR-007: Monitoring & Logging
- Application logs must capture errors, warnings, and info
- User actions must be logged (login, order creation, listing creation)
- System must track key metrics: active users, orders, revenue
- Error tracking and alerting for critical failures

### NFR-008: Browser Compatibility
- Support latest 2 versions of Chrome, Firefox, Safari, Edge
- Graceful degradation for older browsers
- Mobile browser support: iOS Safari, Chrome Mobile

### NFR-009: API Design
- RESTful API design principles
- Consistent error response format
- API versioning support (v1)
- Comprehensive API documentation (OpenAPI/Swagger)
- JSON request/response format

### NFR-010: Testing
- Unit test coverage target: 70%
- Integration tests for critical workflows
- End-to-end tests for checkout and order flows
- Load testing before production deployment

---

**Document Version:** 1.0  
**Last Updated:** 2025-01-10  
**Author:** Senior Product Manager  
**Status:** Ready for Development