-
-
Milestones in English: exact budget allocation, deadlines, acceptance criteria and a recorded fictional work review.
-
English demo overview: fictional coffee-shop project, milestone progress, clarity flags and Sandbox-only payments.
Inspiration
A freelance project can start with a friendly brief and end with two different ideas of what was promised. FairDeal AI helps a client and freelancer make expectations explicit before work begins and revisit the same written terms when a disagreement appears.
What it does
A user describes a project, budget and deadline. Gemini drafts an editable agreement covering scope, deliverables, exclusions, acceptance, revisions, ownership and milestones. The risk scanner identifies unclear wording and proposes changes for human review. Each milestone has an amount, date and definition of done; submitted work and acceptance are recorded separately.
PayPal Sandbox is central to the workflow. The server creates an Orders v2 order from the saved milestone amount, redirects the buyer to PayPal for approval, captures an approved order only after an explicit confirmation, and independently retrieves the order to verify the completed capture. The workspace preserves Order IDs, Capture IDs and unresolved statuses. It never represents an example as a successful payment.
When expectations differ, the mediator compares both statements with the saved agreement and unverified work evidence. It cites actual clauses, identifies missing evidence and suggests a nonbinding next step. AI never approves work or decides whether to transfer money. The interface supports English and Russian.
How it was built
The app uses Next.js, React, TypeScript, Node.js, SQLite, Zod, custom CSS and Lucide icons. PayPal and Gemini requests run on the server; credentials stay outside the browser. Gemini 3.5 Flash-Lite returns structured JSON, validated for dates, exact milestone totals and matching clause quotations. Local templates and clarity checks remain available with explicit demo labels when live AI is unavailable.
Challenges
Payment approval is not the same as capture. The payment adapter implements persisted idempotency references, duplicate-order protection, amount and project-reference checks, and recovery through a fresh provider lookup after an uncertain response. Live AI testing also exposed a past milestone date and an unavailable model endpoint; the current adapter supplies today's date, rejects past dates for new agreements, and uses the working model endpoint. Translating saved examples while preserving original contract text and payment records required a separate presentation dictionary.
Accomplishments
The local coffee-shop walkthrough includes agreements, reviewed risk findings, milestone evidence and clause-grounded mediation. Two real PayPal Sandbox captures of $90 and $120 were independently verified, totaling $210 in test funds. Live Gemini agreement creation, risk scanning and mediation were also verified. A clean source copy passed 21 automated tests, two HTTP workflow tests and a production build. These checks are documented in the public repository; they are prototype verification, not production certification.
Lessons learned
Reliable AI assistance needs validation and visible sources. Reliable payments need provider verification and explicit human decisions. Keeping work acceptance, payment approval and mediation separate makes the product easier to understand and test.
What's next
Authenticated collaboration, durable shared storage, versioned change requests, hosted access and broader accessibility and provider-error testing. The current version is a working single-user local prototype, not an escrow service, a signed-contract system or legal advice.
Run and test
Source and MIT license: https://github.com/anuarovalihan6-cmyk/fairdeal-ai Use Node.js 24+, run npm ci and npm run dev, then open http://localhost:3000. The README includes Windows launch scripts, complete setup steps and verification notes. Without credentials the labeled offline workflow runs locally; real Sandbox payments and live inference require the evaluator's own PayPal Sandbox and Gemini credentials, configured privately through SETUP.cmd or .env.local. No public hosting or paid service is required for the offline demo.
Log in or sign up for Devpost to join the conversation.