ScopeProof

Inspiration

Freelancers rarely lose money because they forget to invoice. They lose it in the gap between what the contract says and what actually happened in the email thread.

A client asks for "one small extra" in an email. You send a price. They say "sounds good" or they go quiet. Three weeks later, when you invoice, you're digging through dozens of emails to answer:

• Was this extra actually approved, or just requested?
• Which price was final, the first quote or the revised one?
• Was the work accepted, so it's billable now?

Get it wrong one way and you under-bill. Get it wrong the other way and you bill for something the client never approved, which leads to disputes, delayed payments and damaged trust. We wanted a tool that treats an invoice the way a lawyer treats a claim: every line needs evidence.

What it does

You upload the contract and the client emails. The app finds the work that was actually agreed and drafts an invoice where every line is backed by an exact quote from the source documents. Anything unproven gets flagged for your review instead of billed.

  Contract + emails (.zip / .eml / .pdf)
                 │
                 ▼
   ┌───────────────────────────┐
   │ 1. Upload & extract       │  authors, recipients, dates, threads
   └─────────────┬─────────────┘
                 ▼
   ┌───────────────────────────┐
   │ 2. AI analysis (RAG)      │  finds milestones, extras, prices,
   │                           │  approvals and acceptance
   └─────────────┬─────────────┘
                 ▼
   ┌───────────────────────────┐
   │ 3. Human review           │  quotes + flags, approve / edit / exclude
   └─────────────┬─────────────┘
                 ▼
   ┌───────────────────────────┐
   │ 4. Invoice & payment      │  confirm, send via PayPal, track status
   └───────────────────────────┘

Example: a website project with three possible line items.

Key features

• Projects: one per client, with client details and currency.
• Smart upload: drop a ZIP or individual .eml, .pdf, .txt and .md files. Text is extracted while keeping sender, recipients, date and reply threading. Duplicates are skipped automatically.
• Evidence for every line: click any quote to open the original email with that sentence highlighted.
• Flags that protect you: missing approval, conflicting prices, unclear price, work not delivered yet, low confidence.
• Human in control: nothing is billed automatically. You approve, edit or exclude each item, and approving a flagged item requires an explicit confirmation.
• Invoice and payment: confirming the invoice locks the reviewed items. You then send it through PayPal (sandbox) and track its status from sent to paid.

How we built it

The pipeline

1. Ingestion: ZIP archives are expanded safely in memory, with limits on file count and total size to block zip bombs. Emails are parsed into author, recipients, date and message IDs, and quoted replies are stripped so the same text isn't counted twice.
2. Retrieval: documents are split into chunks that keep their exact character positions in the original text. The AI first lists every candidate work item across all chunks, so small extras aren't missed. It then retrieves evidence for each item using vector similarity plus exact-term matching.
3. Structured decisions: for each work item, the model returns strict JSON (price, approval, readiness and citations), which is validated with Pydantic.
4. Verification (don't trust the AI):
   • every cited quote must exist word for word in the source text;
   • "approval" and "acceptance" only count if the email came from the client's address;
   • the price must actually appear in a cited quote, in the project currency;
   • anything that fails is flagged rather than silently accepted.
5. Review and invoicing: approved items become invoice lines. The payment provider sits behind a small interface, so the app worked end to end with a placeholder while the PayPal integration was built in parallel.

We split the work across three people: document management and the full UI, the RAG analyzer, and the PayPal integration. The analyzer and payment provider each sit behind a small, agreed interface, so all three parts could be built in parallel and plugged in without changing the UI or API.

Challenges we ran into

• AI hallucinating evidence. Language models will happily "quote" sentences that don't exist. We added a strict verification layer: quotes are matched against the stored text, and items without a verified quote are flagged as unsupported.
• "Requested" vs "approved". A client asking for something, or a freelancer proposing a price, is not approval. We had to encode who said what, and when, using email authorship and dates, and handle revised and cancelled prices.
• Messy email data. Quoted replies, attachments, HTML bodies and inconsistent headers all had to be normalized without losing the metadata that proves who agreed to what.
• PayPal sandbox details. Invoices must be sent from the exact sandbox business account that owns the API credentials, otherwise PayPal rejects them with USER_NOT_FOUND. Payment status also needed both webhooks and polling to stay reliable.
• Framework edge cases. Next.js 16 keeps hidden pages mounted, and a modal left open on a hidden page made the whole app unclickable. We tracked it down and fixed it at the component level.

Accomplishments that we're proud of

• A complete, working flow: upload → analysis → review → invoice → send → payment tracking.
• Evidence-first design: every suggested line links to the exact sentence that justifies it, one click away.
• The AI is cautious by design: when evidence is weak, items get flagged rather than billed, so the tool never charges a client for unapproved work.
• Clean, pluggable architecture: the analyzer and payment provider can be swapped through configuration alone.
• Tested and safe: automated tests for extraction, RAG validation and PayPal flows; protection against zip bombs; and sandbox-only payment access.

What we learned

• With AI in a financial workflow, validation matters more than generation. The model proposes, the code verifies, and a human decides.
• Retrieval-augmented generation works best when you keep exact source positions, which makes citations checkable rather than approximate.
• Agreeing on interfaces first let a three-person team build the UI, AI and payments in parallel without blocking each other.
• Real-world documents (email threads especially) are far messier than examples, and handling them well is a large part of the product.

What's next for ScopeProof

• Gmail / Outlook sync: import threads directly instead of uploading ZIPs.
• Persistent vector search with pgvector, for large projects and faster re-analysis.
• Live PayPal and more providers (Stripe, bank transfer), plus PDF invoice export.
• Work logs and time tracking for hourly billing with evidence.
• Client-facing evidence view: share the proof behind each line with the client to resolve disputes before they start.
• Model evaluation: measure analysis accuracy against labeled project datasets.

Built With

• alembic
• fastapi
• next
• openai-sdk
• paypal-sandbox
• pydantic
• python
• react
• sqlalchemy
• typescript