Inspiration

Freelancers rarely lose money in one big dispute. They lose it one message at a time: "could you also add a testimonials section?", "can someone be on call this weekend?". Each request looks small, nobody re-reads the contract, and the extra work ships unpaid. We wanted a tool that answers one question instantly and honestly: is this request covered by what we agreed, and if not, how do I get paid for it?

What it does

  1. Understands the contract. Upload an agreement (PDF or text). Google Gemini extracts milestones, amounts, deliverables and payment terms, and every value is tied to an exact quotation from the document, with its page number.
  2. Checks every client request. Paste client messages. Each request is classified as In scope, Out of scope or Ambiguous, citing the exact contract clause that decides it.
  3. AI proposes. Evidence decides. ScopeShield never trusts the model's opinion on its own. The server re-locates every quote in the original text and rejects anything it can't verify, and the overall verdict ("Scope change detected: 1 of 3 requests is outside the agreement") is computed from verified findings, not from the model's summary. In our live tests, this caught the model's own overall verdict being wrong.
  4. Turns new work into payment. Out-of-scope work becomes a change order with the freelancer's price. The client accepts it in their own view. ScopeShield then creates a PayPal invoice for it (sandbox), sends it only after explicit confirmation, and syncs the status until it shows Paid.
  5. Keeps a record. An Evidence Pack PDF bundles the quotations, findings, decisions and invoice history.

A human approves every step. AI never sets prices, approves work or sends invoices.

How we built it

  • Backend: FastAPI, SQLAlchemy + Alembic, SQLite. Frontend: Next.js 16, React 19, TypeScript.
  • Google Gemini API: structured extraction and scope analysis. The contract is sent as numbered segments; the model must cite a segment and an exact quote, which the server verifies against the source text.
  • PayPal Invoicing API (sandbox): OAuth with token caching; idempotency keys and a durable intent record before every network call (no duplicate invoices); failures classified as "provably not created → safe to retry" versus "ambiguous → reconcile"; status sync including PAID; change-order invoices kept separate from milestone totals.
  • Quality: 1,160+ automated backend tests plus frontend tests, run on both Windows and Linux.
  • Hosting: Azure VM with HTTPS (Caddy + Let's Encrypt), nightly encrypted backups with a tested restore, and isolated judge accounts.

Challenges we ran into

  • Models paraphrase quotes and miscount positions. We stopped trusting model offsets: unique quotes are located by their text, and repeated phrases must match the cited contract segment.
  • Real-world PDFs are messy (tables, "$" without a currency code). We moved from all-or-nothing to per-field validation: unverifiable fields are left blank and flagged for review, never guessed.
  • Gemini refused requests from one cloud region even though the country was supported. We probed another region with a throwaway server and moved the deployment there.
  • Payment failure states. A failed PayPal call must never permanently lock work when the invoice provably wasn't created. This was proven against the real PayPal sandbox when a missing app permission caused a failure, and the retry reused the same attempt with no duplicate invoice.

Accomplishments that we're proud of

  • The complete loop works on the live site: contract → AI scope check → change order → client acceptance → PayPal invoice → Paid.
  • Every claim the AI makes is backed by text you can click and find in the original contract.

What we learned

Grounding beats prompting: the most reliable improvements came from verifying model output on the server, not from asking the model to be more careful.

What's next for ScopeShield

Importing client messages from email and chat exports, multi-currency support, and moving from the sandbox to live PayPal after a proper review.

Honest limitations

Not legal advice. PayPal runs in sandbox mode only. Client messages are pasted in by hand, and the sender isn't verified.

Built With

Share this project:

Updates

Submission history