YardScout

Find a good one.
Discover neighborhood garage sales and plan a better Saturday.

---

What is YardScout?

YardScout helps people find nearby garage sales, browse them on a map, and plan a route between stops. It also includes a separate admin area for reviewing listings and running the supported scrapers.

Open the live site · Try the iPhone preview · See the roadmap · Read the license

YardScout is a map-first garage-sale finder for people who want to discover local sales, save the best stops, and build a route for the weekend. It is also a practical open-source project for learning Flask, SQLite/PostgreSQL, scraping with source permissions, PWA design, and Android packaging.

Features

• Find sales: Browse map pins and listings, search nearby, and open a sale for details.
• Search precisely: Filter the listings API by keyword (q), ISO date window (date_from and date_to), source, and bounded result count.
• Map-friendly API: Lightweight clients can request validated latitude/longitude bounds and a public listing summary from /api/summary.
• Save and filter: Signed-in users can save listings across devices and filter by date, distance from their location, keyword, or saved status.
• Plan a route: Choose a weekend date, add up to eight sales, pick a starting point, and get an estimated driving order. Open the stops in Google Maps for directions.
• Post a listing: Add a sale location, date, title, and description.
• Follow creators: Follow a signed-in listing creator and receive an immediate in-app notification when they post a new sale. Optional SMTP settings can also deliver the notification by email.
• Install on iPhone: Add YardScout to your iPhone Home Screen from Safari for an app-like experience. The PWA shell uses network-first loading and does not cache private API responses.
• Mobile polish: Use the in-app install prompt, one-tap listing refresh, native sharing, and OS share-target support when YardScout is installed.
• Admin tools: Review listings, add sales, extract text from screenshots, run supported scrapers, check scan progress, and download a private data backup.
• Automatic cleanup: Listings are removed after the sale date has passed by seven days.
• Fast health checks: The hosted service exposes /healthz for deployment readiness checks.
• Security defaults: Production requires an explicit secret key and admin email, rejects cross-origin mutations, sends browser hardening headers, and requires verified Google email claims.

For a desktop demonstration of the iPhone layout, open /iphone-preview. The preview is only a visual frame; the same responsive PWA is the installable experience on a real iPhone.

The route planner requests estimates from the public OSRM service. It has no live traffic or service guarantee, and YardScout does not save routes.

Saved listings are stored against the signed-in account. Location filtering uses the device location only in the browser; YardScout does not store that location. The listings API supports optional bounded source and limit query parameters for lightweight clients and integrations.

Contributing

New here? Start with CONTRIBUTING.md, then look for issues labeled good first issue or help wanted. Bug reports and feature requests have guided forms, and every pull request runs the Python test suite through GitHub Actions.

Please do not add unauthorized crawlers or commit credentials, private backups, or database files.

Scraper coverage

YardScout only runs sources with supported access:

Source	Current coverage
eBrandon	Garage-sale listings around Brandon, Manitoba
GarageSaleFinder	Owner-authorized pages for U.S. locations
Ticketmaster	Optional event lookup when an API key is configured

The resumable regional scan checks 70 hubs; it is not an exhaustive North American crawl. Facebook Marketplace, Kijiji, Craigslist, and other sites are not automatically scanned without approved access.

Run locally

Requires Python 3.12 or newer.

git clone https://github.com/DevarshP610/YardScout.git
cd YardScout
py -3.12 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -r requirements.txt

Set the required app and Google OAuth values in your PowerShell session. Register http://127.0.0.1:8080/auth/callback as an authorized redirect URI in Google Cloud. Keep credentials private; never add them to Git.

$env:SECRET_KEY = "replace-with-a-random-secret"
$env:APP_ENV = "development"
$env:ADMIN_EMAIL = "you@example.com"
$env:GOOGLE_CLIENT_ID = "your-client-id"
$env:GOOGLE_CLIENT_SECRET = "your-client-secret"
python app.py

ADMIN_EMAIL is required for production admin access. YardScout intentionally has no hard-coded administrator account; leaving this unset disables admin-only actions.

Open http://127.0.0.1:8080. Local development uses SQLite by default. Set DATABASE_URL to use PostgreSQL; set TICKETMASTER_API_KEY to enable the optional Ticketmaster lookup.

To enable immediate email notifications for followed creators, configure SMTP_HOST, SMTP_PORT, SMTP_USERNAME, SMTP_PASSWORD, and SMTP_FROM. Leave these unset to use in-app notifications only. Browser push notifications are planned separately and are not enabled by these settings.

Android build

The Capacitor wrapper targets Android SDK 35 and requires JDK 21 and Node.js 20 or newer. From mobile:

npm install
npm run android:build:debug

The debug APK is written to mobile/android/app/build/outputs/apk/debug/app-debug.apk. The wrapper enforces HTTPS, excludes private app data from Android backup and device transfer, and uses the same account-backed saved listings as the web app.

Hosting and data safety

The hosted app runs on Render. Its free web service has ephemeral storage, so use PostgreSQL for hosted data; local SQLite files can be lost on restarts or deploys. The admin Data safety panel shows the selected database and provides a private JSON backup. Render's free PostgreSQL databases expire after 30 days; check provider limits and retention before relying on a free plan.

Before switching databases:

1. Download a backup from Admin → Data safety and keep it private.

2. Create an empty PostgreSQL database and set its connection string as DATABASE_URL in Render. Never commit or share the value.

3. Restore from the repository root:

   $env:DATABASE_URL = Read-Host "Paste the database connection string"
   try {
     .\.venv\Scripts\python.exe scripts\restore_backup.py .\yardscout-backup-YYYYMMDDTHHMMSSZ.json
   } finally {
     Remove-Item Env:DATABASE_URL -ErrorAction SilentlyContinue
   }

   The restore tool refuses to overwrite a non-empty database unless --replace is explicitly supplied.

4. Set the same DATABASE_URL in Render, redeploy, confirm the admin panel reports PostgreSQL, and download a fresh backup.

Keep a backup outside the hosting provider. YardScout does not back up data automatically or guarantee recovery from an inaccessible service.

Roadmap

Planning estimate: 33–50 focused hours, or about 6–13 working weeks at 4–6 hours per week. Estimates can shift with school, testing, and source permissions.

When	Focus
Weeks 1–2	Finish persistent database setup and recovery checks; add automated checks for pushes and pull requests.
Weeks 3–4	Improve scraper reporting, retries, and interrupted-run handling.
Weeks 5–6	Research Canadian sources; add an adapter only when access and listing quality are verified.
Weeks 7–8	Add map filters and listing-quality feedback, including duplicate and stale checks.
Weeks 9–10	Add saved sales, address mobile and accessibility issues, and prepare a release and feedback path.

See ROADMAP.md for definitions of done, effort estimates, and project guardrails.

Project files

File	Purpose
app.py	Flask routes, authentication, and database operations
scraper.py	Supported source adapters and regional scans
templates/index.html	Public map, listings, and route planner
templates/admin.html	Admin tools
tests/	Automated tests
render.yaml	Render deployment configuration

License

YardScout is licensed under the PolyForm Noncommercial License 1.0.0. Commercial use requires permission from the copyright holder. This is source-available, not OSI-approved open source; see the license for terms.