MilestonePay

MilestonePay is a platform that makes payments between freelancers and clients safer and more transparent by connecting payments to actual project progress.

Comment

Inspiration

Freelance work suffers from a classic two-sided trust gap:

  • Clients worry about paying upfront before deliverables meet expectations.
  • Freelancers worry about delivering weeks of engineering or design work only to face scope creep, delayed feedback, or unpaid invoices.

Traditional escrow platforms lock funds behind opaque manual processes, while generic payment links don't understand project milestones or technical deliverables. We built MilestonePay to combine PayPal’s Authorize-and-Capture escrow model with multi-step LangGraph AI agents so funds are committed upfront, milestone plans are structured and fair, submissions are objectively inspected against real code and screenshots, and humans always stay in control of releasing payments.

What it does

MilestonePay is an end-to-end, role-based milestone payment platform for Clients and Freelancers:

  1. Upfront PayPal Authorization (Zero Premature Charge): Clients authorize the total project budget $B$ upfront via PayPal (AUTHORIZE intent) without capturing the full balance immediately.
  2. AI Project Requirement Analyzer & Milestone Planner: Given a project brief, total budget, and deadline, a 6-node LangGraph workflow breaks requirements into engineering tasks, groups them into sequential milestones with clear acceptance criteria, and reconciles budgets and deadlines mathematically.
  3. Structured Milestone Submissions: Freelancers submit deliverables—GitHub repository links, deployed URLs, documentation, and UI screenshots—with versioned submission history and in-app notifications.
  4. AI Deliverable Evaluation Agent: Before a client approves a milestone, an evaluation agent inspects the actual linked GitHub repository (commits, file tree, README, package.json, and relevant source files), decodes attachments, analyzes screenshots using a vision model, and compares observed evidence against every acceptance criterion.
  5. Human-in-the-Loop Partial PayPal Captures: Clients review the AI evaluation report and explicitly trigger milestone approval. The backend then executes a PayPal partial capture for that milestone's exact amount $p_i$, updating remaining authorized funds until final capture or voiding unused authorization.
  6. Context-Grounded AI Project Assistant: Both clients and freelancers can ask questions about progress, delay risks, escrow status, or evaluation disagreements—grounded live in MongoDB project, milestone, submission, and payment state.

How we built it

We structured MilestonePay across four coordinated layers:

1. Payment & Escrow Engine (PayPal + Express 5)

  • Built on Node.js, Express 5 (ESM), MongoDB Atlas, and Mongoose with PayPal Server SDK (@paypal/paypal-server-sdk) on the backend and @paypal/react-paypal-js (SDK v6 API) on the frontend.
  • Implemented an AUTHORIZE → partial CAPTURE → final CAPTURE / VOID lifecycle with idempotency safeguards and verified PayPal webhook handlers (verifyWebhook) so frontend callbacks are never blindly trusted for payment completion.
  • Across $n$ milestones, total project authorization $B$ satisfies exact conservation:

$$B = \sum_{i=1}^{n} p_i, \qquad \text{Remaining Escrow} = B - \sum_{k \in \text{Captured}} p_k$$

2. Multi-Role Web Application (React 19 + Vite 8)

  • Built separate Client and Freelancer dashboards with React 19, Vite 8, React Router v7, Axios, and Lucide React.
  • Implemented JWT authentication (bcrypt + jsonwebtoken), protected routes, project creation with AI milestone previewing, milestone submission modals, PayPal checkout and capture panels, evaluation report drawers, and real-time notification feeds.

3. LangGraph.js AI Agents (@langchain/langgraph + Groq)

We designed three stateful graphs inside backend/src/ai/graphs/ powered by Groq (@langchain/groq) and Zod v4 structured outputs (with automatic JSON-mode fallback):

  • Milestone Generator Graph (6 nodes + validation retry loop): analyzeRequirements → breakDownTasks → planMilestones → allocateBudgets → validatePlan (conditional retry) → finalizeOutput.
  • Deliverable Evaluation Graph (5 nodes + verification retry loop): requirementRetrieval → submissionAnalysis → evaluation → verification (conditional retry) → reportGeneration.
  • Project Assistant Graph: Loads live MongoDB project/escrow snapshots, classifies user intent (progress_summary, milestone_requirements, delay_risk, payment_escrow, evaluation_disagreement, general), and routes through specialized reasoning nodes.

4. Deterministic Math & Security Guardrails

Rather than trusting LLMs with financial arithmetic or unverified URLs, we paired agent reasoning with deterministic code:

  • Cent-Exact Largest-Remainder Allocation: Total budget $B$ is converted into integer cents $C = \lfloor 100B + 0.5 \rfloor$ and distributed via largest-remainder rounding so there is zero floating-point drift:

$$c_i = \lfloor w_i C \rfloor + r_i, \qquad \sum_{i=1}^{n} c_i = C$$

  • Deterministic Evaluation Scoring: After the LLM evaluates each criterion individually, the final score is computed strictly in code:

$$\text{overallScore} = \operatorname{round}!\left(\frac{|R_{\text{completed}}|}{|R_{\text{total}}|} \times 100\right)$$

  • SSRF Protection & Human-in-the-Loop: External submission URLs are checked against private IPv4/IPv6 ranges, loopback, and cloud metadata IPs before fetching, and AI agents are strictly forbidden from approving milestones or calling PayPal capture/void APIs.

Challenges we ran into

  • Preventing LLM Financial & Scheduling Drift: Language models frequently produce milestone amounts that don't quite sum to the project budget (e.g., off by $0.01) or generate out-of-order deadlines. We solved this with a validation retry loop inside LangGraph followed by deterministic cent-exact reconciliation (reconcileMilestoneBudgets) and monotonic deadline clamping.
  • Zod v4 + Structured Output Compatibility: Integrating Zod v4 schemas cleanly with ChatGroq.withStructuredOutput required careful schema testing and a JSON-mode fallback inside our invokeStructured wrapper so workflows never fail silently on schema edge cases.
  • Honest Deliverable Inspection vs. Hallucination: When a freelancer links a private or unreachable GitHub repository, an AI evaluator might guess code contents from the repo name. We built explicit failure flags (githubAccessible: false with the exact error) and prompt constraints so the evaluator refuses to fabricate unseen evidence.
  • Parallel 4-Member Integration Without Conflicts: With separate team members owning PayPal foundation, MongoDB/auth/CRUD APIs, React UI, and LangGraph AI agents, keeping frontend and backend contracts aligned required building a clean service layer (aiService.js) and API contracts upfront so mocked AI flows could swap seamlessly to live LangGraph endpoints.

Accomplishments that we're proud of

  • Real End-to-End Escrow Flow: Working PayPal Sandbox AUTHORIZE + partial milestone CAPTURE + VOID + webhook verification integrated directly with MongoDB project and milestone state.
  • Three Production-Structured LangGraph Agents: Stateful multi-node graphs with conditional retry edges, GitHub REST API inspection, multimodal vision analysis for UI screenshots, and context-aware dispute assistance.
  • Zero Financial Guesswork & Strict Safety Boundaries: Exact cent parity across all generated milestones, deterministic evaluation scoring, SSRF URL filtering, Helmet + rate limiting, and fail-fast checks for missing JWT_SECRET or GROQ_API_KEY.
  • Automated Test Coverage Across Backend & Frontend: Verified with automated unit and workflow test suites (13 backend tests across 8 suites covering Zod binding, budget/schedule math, SSRF/GitHub inspector, all 3 LangGraph workflows, and auth/AI controllers; plus 5 frontend tests, ESLint, and Vite production build).

What we learned

  • Pair Probabilistic AI with Deterministic Invariants: LLMs excel at breaking down ambiguous specs and synthesizing repository evidence, while traditional code should always own currency math, scoring formulas, deadline bounds, and state transitions.
  • Payment State Belongs on the Backend: Never trust a client-side checkout callback alone—relying on backend PayPal authorization/capture responses and verified webhooks prevents race conditions and duplicate captures.
  • Guardrails Make AI Trustworthy in Fintech: Keeping humans in the loop before moving real money turns AI from a liability into a high-leverage review assistant.

What's next for MilestonePay

  • PayPal Live Production Onboarding & Multi-Party Payouts: Extend Sandbox authorization/capture flows into full production onboarding with PayPal Payouts for automated freelancer disbursement and platform fee splits.
  • Multi-File Cloud Storage & Live Preview Sandboxes: Support direct artifact uploads (S3/R2) and automated test-runner/build verification inside ephemeral sandboxes during deliverable evaluation.
  • Dispute Resolution & Change-Order Workflows: Add structured milestone renegotiation, scope-amendment approvals, and AI-assisted mediation summaries when clients and freelancers disagree on an evaluation.
  • Webhook-Driven Real-Time UI Updates: Push WebSocket/SSE updates to dashboards the moment PayPal webhooks confirm captures or LangGraph finishes evaluating a submission.

Built With

Share this project:

Updates

Submission history