🛒 Trolley

Build your cart once. Reorder it in one tap. Never run out, never forget.

Theme 2 — Amazon Now: Reimagining Urgent Shopping · HackOn with Amazon, Season 6.0

Trolley is a feature inside the Amazon shopping experience that lets a customer save any cart as a named, reusable bundle (a Trolley), reorder the whole thing in one tap, and rely on an AI agent that auto-substitutes out-of-stock items (with a reason), suggests commonly-forgotten add-ons, and surfaces the right Trolley before festivals and saved dates.

It lives in two routes — the Main dashboard (/) and Amazon Fresh (/fresh) — with an identical Trolley experience and a distinct Trolley Teal identity. Violet marks every AI moment.

---

What's in this repo

Trolley/
├── api/                 FastAPI backend + Trolley Agent
│   └── app/
│       ├── db/          SQL core (RDS/MySQL → SQLite locally) + DynamoDB-style JSON store
│       ├── agent/       Trolley Agent: rule engine + Bedrock adapter
│       ├── routers/     trolleys · checkout · calendar · templates · products
│       └── seed/        ~80-SKU catalog, orders, templates, festival calendar
├── web/                 Next.js 15 (App Router) frontend
│   ├── app/             / · /fresh · /trolley · /trolley/[id] · /trolley/create
│   ├── components/      TopNav · TrolleyHub · ReorderReview · CalendarNudge · …
│   └── lib/             api client · Zustand basket · types · tokens
└── .kiro/steering/      Build decisions auto-included by Kiro (stack + design tokens)

The local prototype runs with zero AWS: SQLite stands in for Amazon RDS (MySQL), a JSON file stands in for DynamoDB, and the agent runs a deterministic rule engine (demo-safe). The polyglot split and the DynamoDB-shaped data interface mirror production exactly — and the Bedrock adapter is wired and ready to flip on.

---

Run it locally (Windows, macOS, Linux)

Requirements: Python 3.10+ · Node 18+

⚡ Quick Start (one command)

python start.py

This starts both backend (port 8000) and frontend (port 3000) in parallel with automatic dependency setup.

That's it! Open http://localhost:3000 in your browser.

📚 Manual Setup (if needed)

Backend (port 8000):

cd api
python -m venv .venv
# On Windows:   .venv\Scripts\activate
# On macOS/Linux: source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env
python -m app.seed.seed
uvicorn app.main:app --reload --port 8000

API docs: http://localhost:8000/docs

Frontend (port 3000, in a new terminal):

cd web
npm install
cp .env.local.example .env.local
npm run dev

Open http://localhost:3000

---

The demo script (hero flow)

1. Open /trolley → the hub shows Priya's saved Trolleys + a calendar nudge.
2. Open Monthly Grocery → tap Reorder with AI.
3. Watch the agent "think", then the review: out-of-stock items show a violet AI swapped chip + a one-line reason; a You may also need strip suggests ≤2 add-ons.
4. To demo a live substitution on stage: in api/, edit app/seed/catalog.py and set an item's in_stock to False (e.g. p_atta_aashir_5), re-run python -m app.seed.seed, reorder again — the agent swaps it to the closest in-stock match.
5. Back on the hub, tick two Trolleys → Combine → merged, de-duplicated checkout.
6. Switch to /fresh → same Trolley feature, grocery context.

---

Personalised calendar + smart delivery reminders

Open /calendar (or the bell in the nav). It's a personal calendar — mark birthdays, festivals, meetings — and you can link a saved Trolley to any event. The reminder engine then works backwards from delivery time:

order-by date = event date − (max delivery time of the Trolley's items)

so the reminder fires early enough that everything arrives before the day. Example: a friend's birthday on the 6th + a Trolley whose slowest item takes 5 days → the "order now" reminder appears on the 1st. Due reminders show a count on the nav bell and a banner on the home/hub.

Per-item delivery times live in api/app/enrich.py (CATEGORY_DELIVERY); fresh items are 1–2 days, household/electronics 3–5. Re-run python -m app.seed.seed to load the demo events (including a friend's birthday linked to the Diwali Box).

Switching the AI to live Amazon Bedrock

The rule engine is the default and the guaranteed fallback. To use real Bedrock:

# api/.env
AGENT_MODE=bedrock
BEDROCK_REGION=ap-south-1
BEDROCK_MODEL_REASONING=anthropic.claude-3-5-sonnet-20241022-v2:0
BEDROCK_MODEL_FAST=amazon.nova-lite-v1:0

Ensure AWS credentials with bedrock:InvokeModel are available (env / profile / role) and model access is granted in the Bedrock console. On any Bedrock error the agent falls back to rules automatically, so the demo can never break.

To use real Amazon RDS instead of SQLite, set DATABASE_URL to your MySQL DSN (mysql+pymysql://user:pass@host:3306/trolley) and pip install pymysql.

---

API surface

Method	Path	Purpose
GET	/trolleys?userId=	List a user's Trolleys
POST	/trolleys · /trolleys/from-order · /trolleys/from-template	Create
GET/PUT/DELETE	/trolleys/{id}	Read / edit / delete
POST	/trolleys/{id}/reorder	Run the Trolley Agent → review basket
POST	/checkout/merge · /checkout/confirm	Merge multiple · place order
GET	/calendar/upcoming?userId=	Upcoming events → matching Trolleys
GET	/templates · /products?route=&q= · /orders	Gallery · catalog · history

Built for HackOn with Amazon S6.0 — Start with the customer. Work backwards. From need to done.