# EmptyBoxes.org
> Free cardboard box exchange. Print a sign. Stack your boxes. Someone nearby takes them.

EmptyBoxes.org is a hyperlocal circular economy platform for cardboard box redistribution. Box donors print a QR-coded sign, stack their boxes beneath it, and set a "gone at" deadline. Neighbors scan the QR to claim boxes and optionally say thanks — credits that go to a local charity (default: Issaquah Food Bank). The drop code printed on each sign is also the permanent institution code for that address, preventing duplicate registrations across sessions.

## Core Concepts

- **Drop**: A box donation event. One address = one institution code. The code persists across sessions — returning donors update the time/date on the same code rather than creating a new one.
- **Institution Code**: A 6-character alphanumeric identifier (e.g. `pfyurz`) that permanently represents a physical address in the EmptyBoxes network. Printed on the sign and encoded in the QR.
- **CharityLoop**: When a neighbor scans the QR and taps "Say Thanks," the thanks count increments on the institution's record. Tips are credited to the donor's named charity.
- **Gone At**: The deadline time printed large on the sign. After this time the boxes go to recycling. Donors update this field each session — the institution code stays fixed.
- **Address Dedup**: The sign form checks the typed address against all known institutions before creating a new one. If a match is found, the returning donor flow reuses the existing code (PATCH, not POST).

## Public API — No Auth Required

Base URL: https://emptyboxes.org

### Drops (Institution Records)
- GET  /api/emptyboxes/drops/:code — Retrieve institution record by code. Returns: { id, code, address, org_name, charity_name, charity_url, gone_at_time, gone_at_date, box_description, thanks_count, active, created_at }.
- POST /api/emptyboxes/drops — Register a new institution/drop. Body: { address, org_name, charity_name, charity_url, gone_at_time, gone_at_date, box_description }. Returns the full record with generated code.
- PATCH /api/emptyboxes/drops/:code — Update an existing institution's sign details (returning donor). Body: { gone_at_time, gone_at_date, box_description, charity_name, charity_url }.
- POST /api/emptyboxes/drops/:code/thanks — Record an anonymous thanks. Increments thanks_count. Returns { thanks_count }.

### Address Lookup (Dedup)
- GET /api/emptyboxes/lookup?address=:address — Check if an address is already registered. Returns { found: bool, institution?: drop }. Used by the sign form to prevent duplicate institution codes for the same physical address.

### QR Code
- GET /api/emptyboxes/qr?url=:url&color=:hex&light=:hex&size=:px — Generate a QR code as SVG. Color defaults: dark=#2C1810 (kraft brown), light=#FBF5E6 (cream). Size in pixels (default 400). Response: image/svg+xml, cached 1h.

## Developer Resources

- OpenAPI spec: https://emptyboxes.org/api/emptyboxes/openapi.json
- Machine-readable endpoint manifest: https://emptyboxes.org/.well-known/srr.json
- AI plugin manifest: https://emptyboxes.org/.well-known/ai-plugin.json
- Sitemap: https://emptyboxes.org/sitemap.xml

## Design Principles

1. No accounts, no tracking. Institution codes are address-anchored, not identity-anchored.
2. Charity-first. Every sign credits a local food bank or charity. Defaults to Issaquah Food Bank.
3. Hyperlocal. Addresses are stored for dedup only. No geocoding, no map UI — just a sign and a stack of boxes.
4. Printable-first. The primary artifact is an 8.5×11" letter-size sign with a QR code, designed to be printed on a home printer.