ScopeDiff

Turn "one small change" into an evidence-backed change order: Gemini cites both texts, the freelancer sets prices, and the client pays only for approved extras with PayPal.

Comment

Inspiration

Freelancers and overseas clients often read the same revision request differently. "Just one small change" can be covered by the original agreement, or it can be new work. ScopeDiff makes that difference visible before the extra work starts, without asking AI to decide who is right or to touch anyone's money.

What it does

  1. The freelancer pastes the original agreement and the client's new request.
  2. Gemini splits the request into items and labels each one included, outside scope, or unclear, citing exact quotes from both texts. The server checks that every quote really appears in the originals; an invented quote is rejected and the analysis is retried.
  3. The freelancer confirms a price for each outside-scope item (AI only suggests a basis). Unclear items become a short question for the client.
  4. The client opens a signed approval link, selects the extras they agree to, and pays with PayPal. The server recalculates the total from the signed record, creates an order with the Orders API (one line item per extra) and captures it after approval.
  5. In the freelancer's payment trail, ScopeDiff reads the order back from PayPal. If an approved item is cancelled, the freelancer refunds exactly that item with a partial refund from the Payments API. The client's link cannot issue refunds.

How we built it

  • Vanilla JavaScript front end and a dependency-free Node.js 22 serverless API, deployed on Vercel.
  • Gemini (gemini-3.8-flash) with a JSON response schema for item classification and quote extraction, plus server-side quote verification.
  • PayPal JavaScript SDK and REST APIs in the sandbox: OAuth 2.0 client credentials, POST /v2/checkout/orders, POST /v2/checkout/orders/{id}/capture, GET /v2/checkout/orders/{id}, GET /v2/payments/captures/{id}, POST /v2/payments/captures/{id}/refund, GET /v2/payments/refunds/{id}.
  • No database: each change order is an HMAC-signed token with separate freelancer and client roles; payment state is always read back from PayPal; every create, capture and refund call carries a PayPal-Request-Id idempotency key. Money is handled in integer cents.
  • Cost guards: per-IP hourly and daily analysis limits.
  • The code and documentation were written with AI coding agents.

Challenges we ran into

Authentic quotations do not guarantee a correct interpretation, so ScopeDiff combines strict source checks with visible evidence and mandatory human price confirmation. Serverless instances do not share memory, so we removed server-side storage entirely and moved to signed tokens plus PayPal as the source of truth. A first version let anyone holding the client link issue refunds; we split freelancer and client tokens so only the freelancer can refund.

Accomplishments that we're proud of

The full loop works end to end on the live demo: AI scope analysis with verified quotes, human pricing, client approval, PayPal sandbox capture, and a per-item partial refund. Tampered amounts, forged tokens, duplicate refunds and client-side refunds are all rejected.

What we learned

A useful AI payment workflow needs clear boundaries: AI explains, humans agree, and deterministic server code moves the money.

What's next

Authenticated accounts instead of bearer links, webhook reconciliation, multi-currency support, and usability testing with freelancers.

Share this project:

Updates

Submission history