Inspiration

Every freelancer and every client knows the same fear. Clients worry about paying upfront for work that doesn't match what was promised. Freelancers worry about delivering and then chasing payment. Most platforms settle this with trust or with slow manual review.

We wanted to replace "trust me" with evidence: agree on acceptance criteria up front, check the delivered work against them, and move money only when the client approves.

What it does

MilestoneGuard AI is a milestone-based payment release workflow for freelance projects.

  1. Define milestones. The client creates a project and milestones. AI drafts 3-5 acceptance criteria per milestone, which the client can edit.
  2. Fund with PayPal. The client pays for a milestone through PayPal. The amount is always read from the database, never from the browser, and the order is captured server-side.
  3. Submit work. The freelancer submits a GitHub repository or live URL.
  4. AI verification. The app collects evidence (file tree, README, package.json and key source files) and the AI checks each criterion, returning met / partial / missing with file-level evidence and reasoning.
  5. Client decision. The client reviews the report, then approves or requests a revision with a note. Revisions trigger a fresh verification and the reports are kept side by side.
  6. Payout. On approval, the server sends a conditional PayPal payout to the freelancer. [If a real Payouts call fails, the app records a clearly labelled "Simulated payout".]

Every state change is enforced on the server and written to an activity timeline.

How PayPal is used

  • Orders v2: create and capture, with server-side amounts and idempotent capture
  • Webhooks: PAYMENT.CAPTURE.COMPLETED with signature verification, as a backup confirmation path
  • Payouts API: conditional release to the freelancer after approval
  • Everything is tested in the PayPal sandbox

How AI is used

  • Criteria drafting: turns a one-line milestone into editable acceptance criteria
  • Verification: compares the submission's evidence with each criterion. The model must cite only evidence present in the snapshot and mark "missing" when none exists. Output is validated against a strict schema, with one retry on malformed output.
  • Model: [Google Gemini, exact model name used]

How we built it

Next.js (App Router), TypeScript, Tailwind CSS, Prisma with SQLite, zod validation, the GitHub API for evidence, PayPal Orders/Webhooks/Payouts, and an LLM for criteria and verification. The code was built with an AI coding assistant and reviewed and tested by us.

Challenges

  • Honest claims. This is a platform payment followed by a conditional payout. It is not regulated escrow, and we say so in the app and the README.
  • Trusting AI output. We forced structured JSON, evidence-only citations and schema validation so the AI can't invent files.
  • State safety. Preventing double funding, early approval and wrong-role actions had to be enforced on the server, not the UI.
  • Time. We built the whole workflow during the hackathon window.

What we learned

Payments and AI work best together when AI produces evidence and a human plus a payment rail make the final decision.

Limitations

  • Verification is static analysis. Code is not executed.
  • Sandbox only; no real money moves.
  • [Payouts may be simulated depending on sandbox availability.]

What's next

Test execution in a sandbox, support for design and document deliverables, dispute handling, and PayPal multiparty features for true held-funds release.

Built With

Share this project:

Updates