Your App Blueprint

# ClearList

Walk through the house taking photos, drop them all in at once, and a minute later you've got a full sale page you can share. The pile becomes money and an empty room, in one session.

Here's everything you're about to build. Take your time. Every piece is explained in plain language, and none of it is as scary as it looks from the outside. You've got this.

## The Goal

The whole plan in three honest lines.

What they're accomplishing

Clearing the whole pile before the deadline, and getting paid for it.

Instead, today

They list one item at a time until they burn out, then donate the rest.

Why that sucks

The per-item effort is so high the money never feels worth it, so the stuff wins.

The one line that runs this whole plan: you are not competing with eBay. You're competing with the donation bag. Every decision has to beat "just donate it and feel the relief."

## Who It's For

A two-sided marketplace, so two real users, not "everyone."

Sellers · the side you build first

People mid-move or clearing out an estate. Twenty to a hundred items, and a hard deadline (the truck comes in three weeks). The pile has become a "death pile" that's been sitting for months, sometimes years, and the move is finally forcing the issue.

Buyers

Budget furnishers and bargain-hunters who just want enough information to decide (validated dimensions, weight, condition, and a clear available-or-reserved status) without a string of DMs, and who can reserve and reschedule a pickup themselves. Their needs are the seller's table stakes: a listing that doesn't let a buyer decide is a listing that doesn't sell.

First 10 users: sellers from one declutter or moving community you can personally show up in, not a broad launch.

## User Flows

How it feels to use, on a good day and on a rough one.

### The batch clear-out (the happy path)

The one thing that has to feel like magic.

    flowchart TD
        A[Drop in 40 photos at once] --> B[AI groups photos into items]
        B --> C[AI researches a price for each]
        C --> D[AI drafts every title + description]
        D --> E[You skim and fix the few it got wrong]
        E --> F[Publish one sale page]
        F --> G[Share the link in your community]

### A buyer reserving an item

First come, first served, with a polite line if needed.

    flowchart TD
        A[Buyer opens your sale page] --> B[Taps 'Reserve' on an item]
        B --> C{Anyone ahead of them?}
        C -->|No| D[They're first in line]
        C -->|Yes| E[They join the queue, first come first served]
        D --> F[Pickup details shared once confirmed]
        E --> F
        F --> G[They show up, you hand it over, done]

### When the AI gets one wrong (the rough day)

Already planned for, so a wrong guess never derails the whole batch.

    flowchart TD
        A[Review screen opens] --> B[Low-confidence items flagged at the top]
        B --> C{What's wrong?}
        C -->|Price is off| D[Fix the price]
        C -->|Two things in one photo| E[Split into two items]
        C -->|One thing across two photos| F[Merge into one item]
        D --> G[Regenerate just that one listing]
        E --> G
        F --> G
        G --> H[Rest of the batch stays untouched]
        style A fill:#fef3c7,stroke:#f59e0b
        style B fill:#fef3c7,stroke:#f59e0b
        style C fill:#fde68a,stroke:#f59e0b
        style D fill:#fef3c7,stroke:#f59e0b
        style E fill:#fef3c7,stroke:#f59e0b
        style F fill:#fef3c7,stroke:#f59e0b
        style G fill:#fef3c7,stroke:#f59e0b
        style H fill:#fef3c7,stroke:#f59e0b

## Features

What you build now, and what waits until you've proven people want the core.

V1 — build now (the part that beats the donation bag)

- • Batch photo upload (a whole pile at once, not one at a time)
- • AI groups photos into items, drafts a title + description, researches a price
- • A review screen that surfaces the low-confidence ones first
- • One public sale page with a shareable link
- • Local pickup with a simple "reserve this item" button

V2+ — later (roughly what ClearList has grown into)

- • A multi-step AI pipeline (grouping → writing → pricing → quality check) for better listings
- • A real first-come-first-served buyer queue with reservations and no-show handling
- • Pickup scheduling wired to your calendar
- • Paid tiers for big moves and estate sales
- • An admin "control room" for operations

## System Architecture

How the pieces connect, and which way the information actually flows.

    flowchart LR
        U[You, on your phone] --> APP[Your App + the public sale pages]
        APP --> DB[(Database: where sellers, items, sales, and reservations get saved)]
        APP --> AI[AI Brain: reads photos, writes and prices listings]
        APP --> MAIL[Email: sends reservation + pickup messages]
        APP --> PAY[Payments: handles the paid tiers]

## Tech Stack

Every tool you'll use, what it does in plain words, and what it costs.

The App (Next.js, installable from the browser)

Free

The app and the public sale pages. Works like an app on a phone, with no app store needed.

Hosting (Vercel)

Free to start

Puts the app online and makes a shared sale link look good and load instantly.

Database + Login (Firebase)

Free tier

Where your app saves things, handles sign-in, and shows listings appearing live. The easiest managed database for a beginner.

AI Brain (Gemini API)

Pay per use

Reads the photos, groups them into items, and writes and prices each listing. Strong at images, cheap enough to run a 40-photo batch.

Email (Resend)

Free tier

Sends the reservation and pickup-detail emails. Dead simple to set up.

Payments (Paddle)

% per sale

Takes payment for the paid tiers, and handles sales tax for you so you never have to learn tax law.

Calendar (Google Calendar API) — V2

Free

Lets buyers pick a pickup slot instead of endless back-and-forth. Comes later, in V2.

## Cost Breakdown

Near $0/month to start. Here's the free tier on each, and roughly when it starts costing money.

Service | Free tier | When it starts costing
--- | --- | ---
The App + Hosting (Vercel) | Generous free tier for a hobby project | Only at real traffic, well past your first users
Database + Login (Firebase) | Free up to a healthy amount of reads/writes | When many sellers are active at once
AI Brain (Gemini) | Pay per use — a few cents per 40-photo batch | From the first batch, but tiny; the paid tier covers it
Email (Resend) | Free for a few thousand emails a month | Only at higher volume
Payments (Paddle) | No monthly fee | A percentage only when you actually make a sale

One thing to watch: the AI calls are the only real cost. They're a few cents per batch, so they stay cheap as long as the AI runs once when a seller drops in their photos. Don't have the app re-run the AI on a timer or over and over — running it more than you need is exactly how a "few cents" quietly turns into a real bill. The paid tier for big moves is what covers this cost.

## Timeline

A realistic shape for a first build, not a race.

The honest sequence: get the boring foundation working first (project, database, login), then spend most of your energy on the one magic moment — the batch engine that turns a pile of photos into finished listings. Everything after that (the sale page, reserving, payments) builds on top of a core you already trust.

Work phase by phase from the list below. Each phase is small enough to finish and feel good about, and you only move on once the current one actually works. There's no deadline here except your own.

## Distribution

Where your first 10 users already are, and the first move to reach them. Plan this before launch, not after.

Where they gather: r/declutter, the moving subreddits, and local "moving sale" Facebook groups. This is the same place the idea got validated — the pain is already being talked about out loud there.

The first move: not a launch link. Show up and be genuinely useful in those communities for a couple of weeks, then tell one honest "I built this because I had a pile too" story. The community is the launch.

For the real ClearList, a single honest Reddit post is what produced its first traction. The channel is the launch.

## Growth Loop

How using the app quietly creates the next user, with no extra marketing.

Every sale page is a public, good-looking, shareable link. Buyers and browsers see it — and a few of them think "I've got a pile too" and become sellers. The arrow that closes the circle is the whole point.

    flowchart LR
        A[Seller publishes a sale page] --> B[Shares the link in their community]
        B --> C[Buyers + browsers see a clean sale page]
        C --> D[A few realize they have a pile too]
        D --> E[They sign up and publish their own]
        E ==>|the loop closes| A
        linkStyle 4 stroke:#4f46e5,stroke-width:3px

Enabling feature

The public, good-looking, shareable sale page (it's already on the V1 list).

The one number to watch

New sellers per shared sale page. If that's near zero, the loop isn't real yet, and r/declutter is the growth engine instead.

Cold start · the loop needs critical mass to spin

A loop is an engine, and an engine has to turn over the first time. The browse-by-city directory is worthless until a city is dense, so it stays behind a threshold. Three moves get it spinning:

- 1. Single-player mode first. A lone seller is useful on day one (clear the pile, share one link), so you launch on that, no crowd required, and nobody ever lands on an empty room.
- 2. Hold the directory behind a threshold. Open a city's browse page only once it crosses ~50 live sale pages. That's the minimum liquidity, the number that says "safe to open the doors here."
- 3. Seed the hard side. Sellers are harder to get than buyers (someone has to list first), so the early push is seller-side, one city at a time.

## Build Phases

The whole journey as a set of achievable steps, in order, instead of one terrifying leap.

1. 1

   Project setup and folders

2. 2

   Database + the data model (sellers, items, sales)

3. 3

   Login (sign up, log in, log out)

4. 4

   Core: batch photo upload → AI groups, writes, and prices → review screen

   This is the heart of the whole app. It's the part that beats the donation bag.

5. 5

   The public sale page + shareable link

6. 6

   Reserve-an-item + local pickup

7. 7

   Polish, error handling, the low-confidence review flow

8. 8

   Payments (the paid tier)

9. 9

   Pre-launch (privacy policy, address rule, security pass, safe-meetup copy)

10. 10

    Deploy

═══════════════════════════════════════════════════════════

🔖 CHECKPOINT: The Core Batch Engine

═══════════════════════════════════════════════════════════

📍 WHERE WE ARE

"We just built the heart of the whole thing. You can drop in a pile of photos and get back a full set of listings — grouped, written, and priced — that you only have to skim and fix."

🔧 WHAT WE JUST BUILT

- A screen that takes many photos at once instead of one at a time.

- The AI step that groups photos into items, writes each listing, and researches a price for it.

- A review screen that shows you the ones it's least sure about first.

💡 WHY WE BUILT IT THIS WAY

"Remember how we realized the real competition is the donation bag, not eBay? That's why the very first thing we built is the batch, not a prettier single listing. Beating 'just donate it' only works if a whole pile takes one session, so the batch had to come first."

📋 WHAT'S NEXT

"Next we'll turn that batch into a public sale page with a link you can share — the thing your buyers actually see."

❓ QUESTIONS?

"Does this make sense? Want to run a real pile of photos through it before we move on?"

Wait for the user before continuing.

═══════════════════════════════════════════════════════════

That's a real, complete app.

People have built companies on less.

## Things to Handle Before Launch

The stuff beginners get blindsided by. A couple of these are genuinely serious.

Payments

Do this now

Apply to your payment provider early, before you write a single line of payment code. Approval can take time.

Privacy — the home-address rule

Must handle

Local pickup means strangers meeting. The seller's home address stays hidden until a buyer is actually committed. This has to be enforced in the code, not just promised in a policy. You also need a real privacy policy before launch.

Security — keep your keys safe

Must handle

Passwords always scrambled, never stored as plain text. API keys live in a protected `.env` file, never written directly into the code where they could leak. Do this from day one.

Safety — safe-meetup guidance

Before launch

Show simple safe-meetup guidance for local pickups, and never use fake urgency ("3 people watching!") to pressure buyers. The app should win when stuff sells, not when people panic.

## Open Questions

Two real decisions still worth talking through — not blockers, just choices.

? Group photos into items fully automatically, or let the seller confirm the grouping before pricing?

? One flat price suggestion, or a range with the comparable sales shown so the seller picks?