Inspiration
Freelance work often breaks down at the moment a contract becomes real delivery. A brief can sound clear to both parties, but clients and freelancers frequently disagree about what "done" actually means. Payment then becomes disconnected from evidence of completed work either withheld beyond delivery or released without any verification.
I built TrustBroker AI to close that gap: define measurable acceptance criteria before work starts, submit and inspect delivery evidence criterion by criterion, preserve the client's decision-making authority and coordinate milestone payments directly through the PayPal APIs.
What it does
A client writes a plain-language project brief. TrustBroker generates a structured Statement of Work (SOW) — milestones, budgets, deadlines and objective acceptance criteria using Groq LPU inference in under a second. Both parties sign a cryptographic SHA-256 fingerprint of the agreed SOW before any money moves.
Freelancers discover open contracts on a marketplace and apply with portfolio links and proposals. An AI vetting engine scores candidates on skills, deliverable quality and project fit without penalising newcomers who lack a contract history on the platform.
Once a contract is active the client funds the milestone using PayPal Orders v2 via PayPal Smart Buttons. The backend records a real PayPal Order ID and Capture ID — no synthetic values.
The freelancer then submits evidence: a GitHub repository, a live deployment URL, screenshots, test output and delivery notes. TrustBroker evaluates every acceptance criterion individually through specialised adapters:
- HTTP Probe — validates the live URL, HTTPS and response latency
- Repository Adapter — inspects GitHub for required file structure and manifests
- Vision Adapter — analyses screenshots against UI requirements using a multimodal model
- Document Adapter — reads delivery notes and PDF attestations
A matching filename or a successful HTTP 200 is never automatically treated as proof that a feature works. Ambiguous, incomplete or subjective evidence is marked Needs Review rather than converted into a fabricated pass.
The client reviews the AI assessment and makes the final authorisation decision. Clicking Authorize PayPal Payout submits the disbursement directly to the freelancer's PayPal email via the PayPal Payouts API with an idempotency key tied to the milestone ID. Status is shown accurately as submitted or pending until PayPal confirms.
An Analytics Studio backed by AG Grid provides operational ledgers and KPI cards for both roles. A workspace-scoped AI Copilot summarises live contract, verification and payment data without replacing the authoritative ledger.
How we built it
- Backend — Python 3.12, FastAPI and SQLModel on a PostgreSQL database via Supabase. Alembic manages migrations. Supabase Auth handles JWT session verification and Supabase Storage holds private deliverable evidence.
- Frontend — React 19 and TypeScript built with Vite and styled with Tailwind CSS. AG Grid Enterprise powers the financial ledger tables. AG Studio provides the operations dashboard and embedded Copilot.
- Payments — PayPal Orders v2 for milestone funding captures and the PayPal Payouts API for disbursements. A webhook listener reconciles asynchronous PayPal events against internal payment state.
- AI — Groq LPU is the primary inference provider for SOW drafting, applicant vetting and evidence verification. OpenRouter serves as a free-tier secondary fallback and DeepSeek is an optional paid tertiary fallback. When any provider returns a 429 rate limit the system skips to the next provider immediately — no sleep, no retry on the same endpoint.
- Safety — A deterministic PolicyEngine enforces four non-negotiable preconditions before any payout can execute: the caller must be the verified contract client, the milestone must have passed verification, a PayPal capture must be on record and the freelancer must have a registered payout email. AI never bypasses this gate.
- Tests — A 90-test regression suite covers PayPal integrity, SSRF protection, CORS security, authentication boundaries and the full verification pipeline.
Challenges we ran into
Making the system truthful under imperfect evidence. The hardest design decision was choosing what the system should do when evidence is ambiguous — a live URL that returns 200 but is behind bot protection, a screenshot that shows a login screen rather than the feature, or a repository that exists but lacks the required implementation. The answer had to be an explicit human-review state rather than a silent pass.
Keeping payment states consistent with PayPal's asynchronous behaviour. PayPal Sandbox payouts move through submitted, processing, unclaimed, failed and confirmed states independently of the application. I modelled this as a provider-backed state machine and updated the UI to reflect only what the provider had confirmed, not what the application had requested.
Provider rate limits causing verification hangs. The original retry logic slept for several seconds before moving to the next AI model, causing verification to stall for minutes when Groq returned a 429. The fix was to return a sentinel value from the attempt function, propagate it through the retry wrapper and immediately continue to the next model in the cascade without any sleep penalty.
Preventing the AI Copilot from reasoning outside its data boundary. The workspace-scoped Copilot required explicit context injection and strict prompt boundaries to stop it from generating responses about data not present in the current user's contracts and ledger.
Accomplishments that we're proud of
Building a closed-loop freelance payment workflow as a solo developer — from plain-language brief through AI-generated SOW, marketplace application, PayPal milestone funding, multimodal evidence verification and policy-governed payout disbursement — that executes real PayPal Sandbox API transactions end to end.
The evidence-first verification design is the technical result I value most. Rather than optimising for fast passes, I deliberately designed for principled uncertainty: every adapter failure, every ambiguous screenshot and every unavailable provider routes to human review rather than fabricating a result. AI supports the client's decision — it does not make it.
The PolicyEngine is a small but critical piece of the architecture. Its four-condition gate means there is no path through the system where an AI evaluation alone releases funds. That boundary is enforced in code, not just in documentation.
What we learned
AI should support decisions rather than hide uncertainty. The most reliable AI product design I found requires strict structured output validation, provider fallbacks at every level, explicit human-review states for ambiguous results and a hard boundary between evidence assessment and financial authorisation.
Payment integrations must be modelled as provider-backed state machines rather than simple successful API calls. Claiming a payout is complete before the provider confirms it is a product accuracy failure — not a minor display issue.
Performance bugs in AI systems often look like reliability bugs. The multi-minute verification hangs were not caused by slow models but by sleeping retry logic that blocked the fallback cascade. Fixing the control flow, not the timeout, resolved the problem.
What's next for TrustBroker AI
- Streaming payments tied to pull request merges. Rather than a single payout per milestone, incremental micro-payments could be released as specific GitHub pull requests are merged and verified against criteria — connecting delivery evidence directly to incremental compensation.
- Multi-currency PayPal Payouts. The current implementation handles USD. Extending to global currencies with PayPal's foreign exchange capabilities would make the platform viable for cross-border contracts.
- Richer delivery adapter coverage. Adding Figma design file inspection, mobile test flight build verification and cloud infrastructure provisioning checks would bring the evidence pipeline closer to covering the full breadth of freelance deliverable types.
- Structured dispute resolution. When a client requests revision, the freelancer should be able to submit a counter-evidence package that the system re-evaluates against the same criteria without overwriting the original assessment record.
- Production PayPal integration. Moving from Sandbox to live PayPal APIs requires production app approval, webhook signature enforcement and regional compliance review. The groundwork is already in place.
Built With
- ag
- ai
- api
- computer
- deepseek
- fastapi
- grid
- groq
- multimodal
- openrouter
- orders
- payouts
- paypal
- postgresql
- python
- react
- render
- sandbox
- sqlmodel
- studio
- supabase
- tailwind
- typescript
- vision
- vite
