DropSafe AI

Problem: Vague delivery instructions in Bangladesh cause frequent parcel theft, especially for high-value items in risky areas.

Comment

Inspiration

What it does

How we built it

DropSafe AI

DropSafe AI is a Bangladesh-focused checkout risk engine for safer last-mile delivery. It evaluates a Dhaka delivery request before the order is placed, explains the local delivery risk, suggests safer handoff options, and rewrites courier instructions when an unattended drop-off looks unsafe.

The application uses a deterministic TypeScript risk engine as the source of truth so checkout decisions stay reliable without external services. Gemini can optionally enrich the customer-facing explanation when configured, but it does not change the deterministic score. See the current implementation spec in DropSafe design.

Bangladesh Problem And Solution

Problem: Bangladesh e-commerce merchants and couriers often need to make delivery decisions from free-text notes such as "leave at gate", "front steps", or "no one home". In dense Dhaka neighborhoods, an expensive unattended parcel can become harder to recover once the courier leaves. The public context package is intentionally narrow and source-dated: for example, the Mohammadpur profile references public reports about local law-and-order concerns and CCTV or policing responses from BSS, The Daily Star, and The Business Standard.

Solution: DropSafe AI acts as a checkout safety layer. It scores the order using delivery details, item value, drop-off type, timing, and a small Bangladesh area-context table; then it recommends practical Dhaka handoff options such as guard desk delivery, signature, courier pickup counter, or evening handoff. Low-risk orders can continue, medium-risk orders show safer options, and any API result marked interventionRequired requires a safer alternative before the protected order action is enabled. The behavior is documented in Risk rules and implemented in lib/risk-engine.ts.

System Flow

flowchart LR
  Customer["Customer checkout"] --> Details["Delivery details\naddress, notes, window, item value"]
  Details --> API["POST /api/assess-risk"]
  API --> Validate["Validate request\nrequired fields + limits"]
  Validate --> Context["Bangladesh area context\nrisk band + source date"]
  Context --> Engine["Deterministic risk engine\nscore, level, alternatives"]
  Engine --> Gemini{"GOOGLE_GEMINI_API_KEY set?"}
  Gemini -- "No" --> Result["Stable deterministic result"]
  Gemini -- "Yes" --> Enrich["Gemini copy enrichment\nreasoning + options + courier note"]
  Enrich --> Guardrail["Keep deterministic\nscore and level fixed"]
  Result --> Decision{"Risk level"}
  Guardrail --> Decision
  Decision -- "LOW" --> Proceed["Place order"]
  Decision -- "MEDIUM" --> Warn["Warn and suggest safer options"]
  Decision -- "HIGH / CRITICAL" --> Require["Require safer alternative"]
  Warn --> Instructions["Updated courier instructions"]
  Require --> Instructions
  Instructions --> Plan["Safer delivery plan"]

Product Surface

  • Shop homepage with Bangladesh-available product categories and checkout state.
  • Bangladesh safe, medium, and critical preset risk scenarios.
  • POST /api/assess-risk route in app/api/assess-risk/route.ts.
  • Deterministic scoring in lib/risk-engine.ts.
  • Bangladesh area profiles in data/bangladesh-risk-context.ts, with updatedAt and source links included in API responses.
  • Optional Gemini enrichment in lib/gemini-risk-client.ts.
  • Risk panel with low, medium, high, and critical states.
  • Safer delivery alternatives that update courier instructions.
  • Success receipt popup after protected order placement.
  • Session operations panel with assessments, interventions, secured orders, and protected value.
  • Prisma schema prepared for persistence; the current assessment flow can run without a database.

AI Data Processing

DropSafe currently processes only the checkout fields needed for the assessment: delivery address text, city, property type, delivery notes, delivery window, item value, drop-off type, and optional product metadata. The API validates the request, looks up matching Bangladesh area context, calculates a deterministic score, and returns a structured result with reasoning, safer alternatives, rewritten instructions, source type, and timestamp. The response shape is defined in types/delivery.ts.

If GOOGLE_GEMINI_API_KEY is not set, no Gemini request is made. If the key is set, Gemini receives the delivery payload plus the deterministic result and local context, then returns only copy improvements. The code explicitly tells Gemini not to change the fixed score or level, not to claim live browsing, and to use the supplied local context as the only neighborhood web context. If Gemini times out or returns unusable JSON, the deterministic result is returned unchanged.

Assessment responses currently mark persisted: false until database logging is enabled. DropSafe should not be used as a real-time safety feed, police report substitute, or final risk model without data governance, privacy review, monitoring, and validation.

How It Helps Bangladesh

DropSafe is designed around practical delivery interventions rather than broad surveillance claims. For Bangladeshi merchants, it can flag risky unattended instructions before fulfillment. For customers, it turns a vague warning into concrete safer options. For couriers, it produces clearer handoff instructions that reduce ambiguity at the gate, reception desk, pickup counter, or customer handoff point.

The Bangladesh context is deliberately cautious. It includes source-backed profiles for a few Dhaka-area examples, including elevated-risk signals for Mohammadpur / Bosila and access-control signals for Banani DOHS / Gulshan, where DropSafe references the Banani DOHS public note on 24/7 security and surveillance. Unknown or unmatched Bangladesh addresses fall back to a medium-risk context and rely on property type, item value, timing, notes, and handoff security.

Tech Stack

  • Next.js 14 App Router
  • TypeScript
  • Tailwind CSS
  • Deterministic TypeScript risk engine
  • Optional Google Gemini enrichment through @google/generative-ai
  • Prisma schema for Vercel Postgres persistence
  • Vercel-ready build configuration

Quick Start

pnpm install
pnpm run dev

Open http://localhost:3000.

Run local checks:

pnpm run typecheck
pnpm run lint
pnpm run build

Environment

The deterministic local mode does not require environment variables. Copy .env.example to .env.local only when enabling optional external services.

# Required only for Gemini-assisted copy generation.
GOOGLE_GEMINI_API_KEY=
GEMINI_MODEL=gemini-1.5-flash

# Persistence values.
POSTGRES_PRISMA_URL=
POSTGRES_URL_NON_POOLING=

# Documented thresholds for the deterministic engine.
RISK_THRESHOLD_MEDIUM=40
RISK_THRESHOLD_HIGH=71
RISK_THRESHOLD_CRITICAL=90

NEXT_PUBLIC_APP_URL=http://localhost:3000

Notes:

  • Gemini enrichment is optional and defensive; the deterministic score remains authoritative.
  • Database variables are present for persistence work and are not required for local assessment.
  • Risk threshold variables are documented placeholders; the current engine still hardcodes thresholds in lib/risk-engine.ts.
  • Keep real secrets in .env.local or the deployment platform, not in committed files.

Deployment

For Vercel deployment:

  1. Import the repository into Vercel.
  2. Use the default Next.js build settings.
  3. Add GOOGLE_GEMINI_API_KEY only if Gemini copy enrichment should run in production.
  4. Add Postgres variables only after persistence is implemented and enabled.
  5. Set NEXT_PUBLIC_APP_URL to the production origin.
  6. Deploy, then run the safe, medium, and critical risk scenarios to verify behavior.

Checkout Flow

  1. Choose a product from the shop grid.
  2. Use one of the scenario buttons:
    • Safe: office reception delivery.
    • Medium: Dhanmondi house/front-gate delivery.
    • Critical: Mohammadpur apartment front-steps delivery for a high-value product.
  3. Click Assess delivery risk.
  4. When the result requires intervention, select a safer option before placing the protected order.

Project Structure

app/
  api/assess-risk/route.ts
  layout.tsx
  page.tsx
components/shop/
  ProductGrid.tsx
  RiskPanel.tsx
  ShopExperience.tsx
data/
  bangladesh-risk-context.ts
  shop-products.ts
  risk-scenarios.ts
lib/
  gemini-risk-client.ts
  risk-engine.ts
  utils.ts
prisma/
  schema.prisma
types/
  delivery.ts
docs/
  product/
  technical/
  setup/
  superpowers/

Documentation

Treat this README and the current source files as the source of truth for the application behavior.

Challenges we ran into

Accomplishments that we're proud of

What we learned

What's next for DropSafe AI

Built With

Share this project:

Updates

Submission history