Building a Marketplace MVP
Build a two-sided marketplace with seller listings, buyer search, in-platform transactions, reviews, and trust mechanics.
Marketplace architecture and the chicken-and-egg problem
A marketplace connects buyers and sellers. The technical challenge is building for two distinct user types with different needs. The business challenge is the chicken-and-egg problem: sellers will not list without buyers, and buyers will not come without listings. Your MVP needs to solve both. Start with the supply side — get enough listings to make the marketplace useful. Then attract demand. Ask Claude Code: Create a Next.js project with TypeScript, Tailwind, and Prisma for a services marketplace (the patterns work for products too — adjust the terminology). Define the database schema. User (id, email, name, role as buyer or seller or both, createdAt, profileImageUrl, bio, isVerified boolean). Listing (id, sellerId, title, description as rich text, category, subcategory, price in pence, priceType as fixed or hourly or starting_from, images as JSON array of URLs, status as draft or active or paused or sold, location optional, tags as JSON array, createdAt, updatedAt, viewCount, favouriteCount). Category (id, name, slug, description, icon, listingCount computed, parentId optional for subcategories). Create a category tree with 6 to 8 main categories, each with 3 to 5 subcategories. Seed with 30 sample listings across all categories. Ask Claude Code: Generate realistic marketplace listings with varied prices, descriptions, and categories. Include high-quality and low-quality listings to test the moderation system later. The marketplace has three core flows: sellers create and manage listings, buyers discover and purchase, and the platform facilitates the transaction and takes a commission. Keep the commission model simple for the MVP — a flat percentage (10 to 15 percent) on every transaction.
Seller experience: listing creation and management
Sellers need a frictionless way to create attractive listings. The easier it is to list, the more supply your marketplace has. Ask Claude Code: Create a listing creation flow at src/app/sell/new/page.tsx. Build a multi-step form. Step 1 — Category: show the category tree as clickable cards. Selecting a main category shows subcategories. Step 2 — Details: title (required, max 100 characters), description (rich text editor with formatting), price (number input with currency selector), price type (fixed, hourly, starting from), and tags (type-ahead input). Step 3 — Images: upload up to 8 images. The first image is the primary image shown in search results. Show image previews with drag-to-reorder and delete buttons. Validate image size (max 5MB each) and dimensions (minimum 800x600). Step 4 — Review: show a preview of the listing exactly as buyers will see it. Publish button creates the listing with status active. Save Draft button saves with status draft. Build a seller dashboard. Ask Claude Code: Create a dashboard at src/app/dashboard/listings/page.tsx. Show all seller listings in a table: title, status (colour badge), price, views, favourites, enquiries, and creation date. Quick actions: edit, pause/unpause, duplicate, and delete. Filter by status. Sort by any column. Show performance metrics at the top: total views, total enquiries, conversion rate (enquiries divided by views), and total revenue. Add listing analytics for each listing. Ask Claude Code: On the listing detail page (seller view), show: view count over time (line chart), where views came from (search, browse, direct link), how many people favourited it, how many enquired, and the conversion funnel (views to favourites to enquiries to purchases). Suggest improvements if the listing is underperforming — for example, Listings in this category with 5 or more images get 3x more enquiries. Your listing has 2 images. Common error: image upload is the most failure-prone part of listing creation. Handle timeouts (large files on slow connections), partial uploads (upload succeeded for 3 of 5 images — save those 3 and let the user retry the rest), and format issues (convert HEIC to JPEG transparently).
Buyer experience: search, discovery, and filtering
Buyers need to find what they want quickly. Search quality determines whether buyers come back. Ask Claude Code: Build the marketplace homepage at src/app/page.tsx. Show: a prominent search bar with category suggestions, featured listings (high-quality, diverse), popular categories as browseable cards, and recently added listings. Create the search system. Ask Claude Code: Build a search page at src/app/search/page.tsx with a full-text search engine. Search across listing title, description, and tags. Rank results by relevance (title matches first, then description, then tags) with a boost for listings with more views and favourites (social proof as a ranking signal). Display results as a grid of listing cards — each showing the primary image, title, price, seller name with verification badge, and favourite count. Build the filtering sidebar. Ask Claude Code: Create filters for: category and subcategory (hierarchical checkboxes), price range (dual-handle slider with min and max inputs), price type (fixed, hourly, starting from), location (if applicable — text input with autocomplete), seller verification status, listing age (last 24 hours, last 7 days, last 30 days, any), and sort order (relevance, newest, price low to high, price high to low, most popular). Show the count of matching listings. Update results in real-time as filters change. Encode all filters in URL parameters for shareable searches. Build the listing detail page for buyers. Ask Claude Code: Create src/app/listings/[slug]/page.tsx. Show the image gallery (swipeable carousel on mobile, thumbnail grid with lightbox on desktop), listing details (title, price, description with full formatting), seller profile card (name, photo, verification status, member since, total listings, average rating, response time), and action buttons: Contact Seller, Make Offer (if the price type is starting_from), Add to Favourites, and Share. Below the listing, show similar listings based on the same category and price range. Common error: search that returns zero results kills conversion. When a search has no results, suggest alternative search terms, show listings from the closest category, and include a Create Alert button that notifies the buyer when matching listings appear.
Transactions and payment processing
The transaction system must protect both buyers and sellers. Marketplaces use an escrow model: the buyer pays, the platform holds the funds, the seller delivers, the buyer confirms, and then the platform releases payment minus commission. Ask Claude Code: Set up Stripe Connect for marketplace payments. Stripe Connect allows your platform to accept payments on behalf of sellers and distribute funds. Install stripe: npm install stripe. Each seller creates a Stripe Connected Account during onboarding. Ask Claude Code: Build a seller onboarding flow for Stripe Connect. Create an API route that generates a Stripe Account Link — a hosted page where the seller provides their bank details, identity verification, and tax information. After onboarding, the seller's account is ready to receive payments. Use Standard Stripe accounts (not Express or Custom) for the simplest integration. Build the purchase flow. Ask Claude Code: When a buyer clicks Buy Now, create a Stripe Checkout Session with: the listing price, a platform fee (your commission — for example, 12 percent), the seller's connected account as the destination for the remaining 88 percent, and a description referencing the listing. After successful payment, create an Order record in your database: orderId, buyerId, sellerId, listingId, amount, platformFee, status as paid, paidAt. Send confirmation emails to both buyer and seller. Build the order management system. Ask Claude Code: Create order tracking at src/app/orders/page.tsx. Show all orders with status badges: Paid (awaiting delivery), Delivered (seller marked as delivered), Completed (buyer confirmed receipt), Disputed (buyer raised an issue), and Refunded. Sellers can mark orders as Delivered. Buyers can mark as Completed (which triggers payment release) or Dispute. For the MVP, handle disputes manually — disputed orders flag in the admin dashboard for human review. Common error: never transfer funds to the seller immediately upon payment. Hold funds for at least 48 hours (or until buyer confirms delivery) to allow for disputes. Immediate payout invites fraud where a seller creates a listing, gets paid, and disappears.
Reviews, trust, and reputation
Trust is the foundation of any marketplace. Without it, buyers will not pay and sellers will not deliver. Reviews, verification, and reputation systems create trust between strangers. Ask Claude Code: Build a review system. After an order is marked as Completed, both the buyer and seller can leave reviews. Review (id, orderId, reviewerId, revieweeId, rating as 1 to 5, comment, createdAt, isVerified as boolean, helpfulCount). A review is verified if it corresponds to a real completed transaction — this distinguishes genuine reviews from fake ones. Only allow one review per order per party. Create the review UI. Ask Claude Code: On each listing page and seller profile, show the aggregate rating (average stars, total review count), a star distribution chart (how many 5-star, 4-star, etc.), and individual reviews sorted by most recent. Each review shows: the reviewer name, star rating, date, comment, and a Helpful button. Highlight verified purchase reviews with a badge. Add seller verification. Ask Claude Code: Create a verification system with multiple levels. Level 1 — Email Verified: email address confirmed (automatic at signup). Level 2 — Identity Verified: seller uploaded a government ID and it was reviewed (manual process for MVP — the admin approves in the dashboard). Level 3 — Pro Seller: completed more than 10 transactions with an average rating above 4.5. Show verification badges on listings and profiles. Buyers can filter search results to show only verified sellers. Build trust signals throughout the marketplace. Ask Claude Code: Add these trust elements: on listing pages show how many people are viewing this listing right now (creates urgency and social proof), seller response time badge (Typically responds within 2 hours), buyer protection guarantee text (Your payment is protected. Funds are only released when you confirm delivery), and secure payment badges (Stripe, SSL). Add a fraud detection system. Ask Claude Code: Flag suspicious activity automatically: new accounts creating high-value listings (potential scam), listings with descriptions copied from other listings (duplicate detection), accounts with multiple failed payment attempts, and reviews from accounts with no other activity (potential fake reviews). Flag these for admin review rather than auto-blocking to avoid false positives. Common error: allow sellers to respond to negative reviews publicly. One-sided reviews feel unfair and discourage sellers from participating. A professional response to a negative review often builds more trust than the review destroys.
Admin moderation and deployment
The admin dashboard is your control centre for maintaining marketplace quality and handling edge cases. Ask Claude Code: Build an admin area at src/app/admin/ with restricted access (check user role in middleware). Create these admin pages. Listing Moderation: queue of new listings awaiting approval (for marketplaces that moderate before publishing) or flagged listings. Show the listing details, seller profile, and approve/reject/request changes buttons. User Management: list of all users with role, status, listing count, transaction count, and rating. Actions: verify, suspend, ban, impersonate (view the marketplace as this user for debugging). Transaction Disputes: list of disputed orders with all context — the listing, the messages between buyer and seller, the payment details, and the timeline. Actions: resolve in favour of buyer (refund), resolve in favour of seller (release payment), split (partial refund). Reviews Moderation: flagged reviews and reviews on suspended accounts. Approve, remove, or edit actions. Analytics: marketplace KPIs — gross merchandise volume, transaction count, average order value, take rate (actual commission collected as percentage of GMV), active sellers, active buyers, and new listings. Add automated moderation. Ask Claude Code: Create content moderation rules that automatically flag listings with prohibited keywords, spam patterns (excessive capitalisation, repeated characters), prices that are unrealistically low (potential scam bait), or images that fail a basic quality check (too small, too blurry). These flags route to the moderation queue rather than auto-rejecting — human judgment is needed for final decisions. Deploy to Vercel with a PostgreSQL database on Neon and image storage on Cloudflare R2 or AWS S3. Ask Claude Code: Configure the production deployment. Set up Stripe Connect webhooks for payment events. Configure image upload to cloud storage instead of local filesystem. Set up the daily jobs: recalculate seller ratings, update listing view counts, flag inactive listings (no updates in 90 days), and send weekly seller performance emails. Test the complete marketplace flow: create a seller account, complete Stripe onboarding, create a listing, search for it as a buyer, purchase it, confirm delivery, leave a review, and verify the seller receives payment minus commission.
Platform Business Models
This guide is hands-on and practical. The full curriculum covers the conceptual foundations in depth with structured lessons and quizzes.
Go to lesson