TRUSTLANCE
A full-stack freelance marketplace featuring integrated application-level escrow protection, transaction-safe milestone releases, and an administrative dispute board.
Vulnerability in Milestone Approvals & Payment Disputes
Traditional freelance boards suffer from asymmetrical financial risk: freelancers risk delivering unpaid work when clients withhold payments, while clients risk paying for substandard or missing deliverables without mediation. Ad-hoc payment integrations frequently leave contracts in inconsistent states during network failures or unilateral cancellations.
Explicit Escrow State Machine & Immutable Audit Trails
Engineered a deterministic escrow state machine. Funds deposited by clients are locked into milestone contracts within Neon PostgreSQL via Prisma transactions. Disbursements occur only when explicit cryptographic approval criteria are satisfied, backed by an administrative dispute adjudication board and permanent audit logs.
Escrow Lifecycle & State Machine
Every contract transitions through strictly guarded phases, preventing invalid withdrawals or bypassed reviews:
CREATED
Client and Freelancer agree on terms. Milestone value is defined.
FUNDED
Milestone funds committed by client. Balance locked via Neon PostgreSQL transaction.
IN_PROGRESS
Freelancer executes deliverables with structured milestone proof and status logging.
SUBMITTED
Client reviews deliverables for formal verification.
Client formally signs off. Funds are instantly unlocked and credited to the freelancer account with mutual review generation.
If terms are contested, contract escalates to Admin. Administrator reviews deliverables and resolves via: Full Release, Full Refund, or Partial Split.
Role-Based Access Control (RBAC)
Permissions are enforced at the API route and database query layer to prevent privilege escalation:
- • Create projects & deposit escrow milestones
- • Review submitted freelancer proposals
- • Access private workspaces for messaging
- • Request modifications or release funds
- • Escalate contested work to system admins
- • Browse open project marketplace
- • Submit proposals with counter-offer rates
- • Submit milestone deliverables and status logs
- • Raise disputes if client withholds approval
- • Bidirectional reputation rating and reviews
- • Adjudicate active disputes (Release / Refund / Split)
- • Monitor platform TVL (Total Value Locked)
- • Inspect account violation & abuse flags
- • Audit immutable system action logs
- • System-wide user moderation
Architectural Stack & Decisions
| LAYER | TECHNOLOGY | TECHNICAL RATIONALE |
|---|---|---|
| Framework | Next.js 16 (App Router) | Server Component rendering, API route security, streaming SSR. |
| Database & ORM | Neon PostgreSQL + Prisma ORM | Serverless branchable Postgres with ACID transactions for escrow states. |
| Authentication | NextAuth.js | Session verification, credentials support, and protected route handlers. |
| SMS Verification | Twilio Service API | Two-factor identity verification and milestone transaction security. |
| Validation & Security | Zod Schema + Bcrypt Hashing | Strict runtime contract payload validation and secure salted credential storage. |
| Design System | Tailwind CSS | Performant utility-first responsive styling with strict monochrome theme. |