ReliefOS

Tagline

Many NGO requests, one optimized purchase — paid with PayPal, orchestrated by AI agents, approved by humans.

Inspiration

When a flood or cyclone hits, dozens of NGOs scramble for the same water, food and shelter. Each one buys separately, pays more, competes for the same supplier stock and loses track of what actually arrived.

We wanted one shared system that pools demand, moves money safely and accounts for every unit until the NGO confirms it received it.

What it does

ReliefOS 2.0 is an AI-powered command center for collective emergency procurement.

  • Collective demand: NGO relief requests for an emergency are consolidated per product and ranked by urgency. Duplicate or conflicting requests are flagged, never silently merged.

  • Supplier comparison: Stored offers are ranked by price, delivery time and reliability, with a documented risk score based on real failure history. Unavailable or expired offers are excluded, with the reason shown.

  • Optimized purchase: A deterministic optimizer buys within budget and capacity and splits stock fairly across NGOs. The flow from NGOs to products to suppliers is shown as a Sankey chart.

  • Human approval: Plans and replanning proposals only proceed after a named coordinator approves them.

  • PayPal Sandbox payments: INR totals are converted to USD at a dated reference rate, paid through the PayPal Orders API, captured server-side and verified against PayPal. Capturing a payment creates the delivery records.

  • Delivery tracking: Every supplier → NGO shipment is tracked from dispatch to NGO receipt. Short deliveries are recorded, and each shipment has a timeline and a route on the map.

  • Supplier failure recovery: A real or simulated failure produces a versioned proposal.

    • An unpaid plan gets a replacement.
    • A paid plan gets an amendment that covers only the shortfall.
    • An independent Revalidation Agent and the server re-check the proposal on fresh data, and a human commits it.
  • Agent Studio: An animated agent network, a step-by-step replay of every MCP tool call, and an AI-written explanation of each run.

  • Audit trail and AG Grid: Every plan, approval, payment, delivery and decision is logged. All operational tables run on AG Grid with search, filters and CSV export.

How we built it

Frontend: React 19 and Vite with TanStack Query. AG Grid Community powers every table: quick search, column filters, money and quantity columns, pagination, CSV export and a custom dark theme. Recharts draws the Sankey, donut and area charts, and Leaflet draws the routes map.

API: Express 5 and Prisma 6 on PostgreSQL (Neon). The API is the only writer to the database. It owns the optimizer, approvals, PayPal integration, deliveries, replanning, validation, idempotency keys, plan versioning and the audit log.

PayPal: Orders API v2 in the Sandbox (create, verify, capture), webhook signature verification, checkout restricted to coordinators, and a dated INR → USD rate (Frankfurter) stored with every payment.

Agents: A Python FastAPI service with an Orchestrator plus Demand, Supplier, Allocation, Fulfilment, Replanning and Revalidation agents.

Each agent has its own list of allowed tools and calls them through a real MCP client session.

Every step is saved as a trace.

Workflows pause for human approval and resume after the human decides.

MCP server: Built with the official MCP Python SDK (FastMCP), served over Streamable HTTP and stdio. It has 36 tools, 5 resources and 4 prompts, with separate read and write permissions and token authentication.

AI: Groq (openai/gpt-oss-120b) writes plain-language explanations of each workflow. Claude Code can drive the same MCP server through .mcp.json.

Challenges we ran into

  • Keeping AI away from money: We separated explanation (the LLM), proposal and validation (agents plus the deterministic optimizer) and commitment (a human). No MCP tool can approve, pay or confirm delivery.

  • Replanning a plan that is already paid: We couldn’t rewrite financial history, so we added amendment plans that cover only the failed or short-delivered quantity.

  • Concurrency and retries: Plan versions, revalidation at approval time and idempotency keys make sure an agent retry never creates a duplicate.

Accomplishments that we’re proud of

  • One working flow on real stored data: demand → optimization → human approval → PayPal Sandbox payment → delivery → NGO receipt.
  • Independent revalidation: the agent and the server must agree, or a human reviews the proposal.
  • A real MCP server that serves our own agents and external clients like Claude Code, with permissions enforced in one place.
  • 21 API tests and 23 Python tests, covering MCP tool discovery, permission enforcement and full agent workflows.

What we learned

MCP draws a clean line between AI and the system of record. The same tools serve our agents, Claude Code and any other client, and permissions live in one place.

Keeping numbers deterministic and letting the LLM only explain made the system both trustworthy and easy to demo.

What's next for ReliefOS

  • Live PayPal payouts to suppliers.
  • A self-service portal where suppliers keep their own offers up to date.
  • SMS or WhatsApp receipt confirmation for NGOs in the field.
  • Multi-currency budgets for international donors.
  • Predicting demand from disaster severity and past requests, so purchasing can start before the requests arrive.

Built With

Share this project:

Updates

Submission history