CommonKind Map

CommonKind (CK) turns neighbor generosity into real meals. Give funds, local hubs issue QR meal vouchers, families redeem at partner eateries. Simple, transparent, and trackable community care.

Comment

CommonKind (CK) — Neighbor Meal Vouchers on Cloud Run

Inspiration

Food insecurity is hyper-local. Neighbors want to help, restaurants want to serve, and families need dignity—not paperwork. CommonKind is a love letter to community logistics: turn goodwill into hot meals with zero stigma and radical transparency.

Why it matters

Dignity. Local-first. Transparency. Speed. CK is simple enough for a church, library, or clinic volunteer to run from a phone. Donations become meals at nearby hubs in minutes.

What it does

CommonKind converts donations → QR meal vouchers → redeemed meals at partner eateries, with live capacity, basic fraud resistance, and a privacy-safe activity feed.

What's built for this hackathon (MVP)

  • Family-size–aware vouchers: "Show voucher" prompts for household size, encodes count & expiry into the voucher.

  • Issuance & Redemption flow:

    • Issue: single-use voucher with short expiry (QR).
    • Redeem: scan/enter code → auto-decrements hub capacity; prevents double use.

  • Map & Hub details: Leaflet map, search with visible outline, distance slider, hub cards with offer/capacity.

  • Donations (mock): pick a hub or general fund → updates impact counters.

  • Admin UX (demo): login modal → Admin dashboard with pending "Become a Hub" applications, approve to add hubs.

  • Impact stats: lightweight, privacy-safe activity list; no PII stored.

  • AI Chat: Gemini 2.5 Flash answers local questions in EN/ES with graceful fallback (no demo-breaking errors).

  • API: stateless endpoints on Cloud Run:
    /healthz, /api/hubs, /api/voucher/issue, /api/voucher/redeem, /api/admin/login, /api/admin/me, /api/ai.

Notes for judges: All data is seeded demo content; tokens/IDs are ephemeral; no real payments/PII.

Services (Cloud Run)

Purpose Resource Type URL / Trigger
Frontend web app (React/Vite) commonkind Cloud Run Service https://commonkind-dijm3qx5ya-uc.a.run.app
Backend API (Express + Gemini) commonkind-api Cloud Run Service https://commonkind-api-197600244131.us-central1.run.app
(base: /api)
Nightly reset (restore hub caps, clear vouchers) commonkind-reset Cloud Run Job Invoked by Cloud Scheduler (OIDC); hits POST /api/admin/reset with x-admin-secret
Scheduler (midnight America/Chicago) reset-commonkind-daily Cloud Scheduler Triggers commonkind-reset daily @ 00:00 CT

Demo links

Quick checks:

  • GET /hubs → hub list
  • POST /voucher/issue { hubId } → { id, expiresAt }
  • POST /admin/login { password } → { token } (demo pw via env)
  • POST /ai { question } → Gemini-powered answer (≤ ~70 words)

How to test (60-second tour)

  1. Open the Frontend → click a hub → Show voucher → enter family size → see QR/code.
  2. Go Admin → Scanner → scan/enter the code → Redeem.
  3. Return to the map: hub's "vouchers remaining" decreased; activity feed shows "issued" + "redeemed".
  4. Open CK Chat and ask: "Where can I use a CK voucher?" or "closest hub to 76028?".

Architecture (why Cloud Run)

Two stateless services + one scheduled job:

  • Frontend (Service): Vite/React SPA on Cloud Run.
  • API (Service): Node/Express on Cloud Run (in-memory demo store seeded from JSON; Gemini 2.5 Flash via Generative Language API v1beta).
  • Nightly Reset (Job): Cloud Run Job called by Cloud Scheduler using OIDC; authenticated call to /api/admin/reset with x-admin-secret.

Why Run

Instant HTTPS, autoscale to zero, simple buildpacks, no servers to manage; perfect for city-scale community pilots.

Stack:
React + Vite + Tailwind + Leaflet, html5-qrcode (scan), Node/Express, Gemini 2.5 Flash (v1beta), Secret Manager, Cloud Build → Cloud Run, Cloud Scheduler.

Security posture (demo):
Short-lived admin bearer tokens, job-to-API shared secret header, CORS restricted to frontend origin, no PII persistence.

Fraud & privacy posture (MVP)

Fraud guard (baseline):

Single-use IDs, short expiries, server-side double-spend checks, atomic decrement on redeem.

Privacy:

Recipients anonymous by design; no names/addresses collected; only non-PII activity counts.

What I learned

Designing single-use, offline-tolerant vouchers and the micro-UX that makes field workflows smooth (big QR, one-tap redeem, clear capacity signals). Shipping clean, stateless boundaries fast on Cloud Run, and using Gemini for context-aware, bilingual support.

What's next

  • Delivery & access: SMS/email vouchers, kiosk mode, multilingual UI, WCAG hardening.
  • Ops: scheduled expiry sweeps, rate-limits, hub/device allowlists, Stripe for real donations, persistent Firestore/Postgres.
  • Governance: exportable audit logs, role separation (Hub/Merchant/Admin), multi-tenant city/NGO views.
  • Ecosystem: open APIs + starter kit so any town can launch a CK hub in a weekend.

Built With

Share this project:

Updates