Skip to content

README.md

Latest commit

 

History

History
147 lines (115 loc) · 5.12 KB

README.md

File metadata and controls

147 lines (115 loc) · 5.12 KB
Raw

TrustLance — Secure Escrow Freelance Marketplace

TrustLance is a production-grade, secure freelance marketplace featuring integrated application-level escrow-style payment protection, dispute resolution boards, and a network social directory.

The application is built using Next.js (App Router), TypeScript, Tailwind CSS, Prisma ORM (with PostgreSQL), NextAuth.js, Razorpay payment gateway integrations, and SendGrid mail systems.

1. Product Summary & User Roles

TrustLance operates with three primary, distinct user roles:

A. Client

  • Capabilities:
    • Create and fund projects by depositing escrow balances (milestones).
    • Review submitted proposals from freelancers.
    • Select and assign freelancers to start a contract.
    • Access private workspaces for real-time project messaging.
    • Request modifications or approve deliverables to release escrow funds.
    • Escalate unresolved disputes to system administrators.
    • Submit bidirectional reputation ratings and reviews upon completion.

B. Freelancer

  • Capabilities:
    • Search and browse open projects in the marketplace directory.
    • Submit proposals with optional counter-offer pricing.
    • Access private contract workspaces upon selection.
    • Upload files and links to submit milestones.
    • Raise disputes if work is rejected or funds are withheld.
    • Rate and review clients after project release.
    • Build professional networks via bidirectional connection requests.

C. Admin

  • Capabilities:
    • Adjudicate active disputes (options: release to freelancer, refund to client, or split).
    • Monitor aggregate statistics (total users, active escrows, total value locked).
    • Inspect profile flag/violation reports.
    • Audit system-wide action histories via database audit logs.

2. Design System

The platform uses a high-contrast Indigo-based theme, featuring a strict black-and-white color layout to ensure visual clarity.

  • **Background **: #000000 (True Black)
  • Surface: #FFFFFF / #111111 (Near Black)
  • Surface Elevated: #FFFFFF / #1a1a1a (Dark Gray)
  • Accent Primary: #4F46E5 (Indigo) / #6366F1 (Light Indigo)
  • Typography: Inter / Sans-serif system default, using strict font and spacing scales.
  • Icons: Lucide-React exclusively.

3. Technology Stack

  • Framework: Next.js 16.2.10 (App Router)
  • Database: PostgreSQL hosted on Neon, managed via Prisma ORM
  • Authentication: NextAuth.js (Session-based, with credentials and Google OAuth provider support)
  • Payment Gateway: Razorpay (Checkout & Orders API, verified with signature checking and webhook handlers)
  • File Storage: AWS S3 (Presigned URLs for secure file uploads)
  • Emailing Service: SendGrid (Transactional emails for onboarding, milestones, payments, and disputes)
  • Testing: Jest + ts-jest

4. Database Setup & Seeding

Seeding Accounts

The database contains pre-configured test overrides with pre-completed user profiles.

Role Email Description Profile Details
Admin thusharyyy@gmail.com System administrator account Pre-completed profile
Client thushar2410612@ssn.edu.in Client test account Pre-completed business profile
Freelancer thushar.tl.dev@gmail.com Freelancer test account Pre-completed skills/bio profile

Setup Instructions

  1. Initialize database schema: 
    npx prisma db push
  2. Populate the database seed overrides: 
    npx prisma db seed

5. Local Development Setup

Follow these steps to run the application locally:

  1. Clone & Install Dependencies: 
    npm install
  2. Environment Configuration: Create a .env file in the root directory based on .env.example: 
    cp .env.example .env
    Provide valid keys for Database, NextAuth, SendGrid, Razorpay, and AWS S3.
  3. Run Dev Server: 
    npm run dev
    Open http://localhost:3000 to view the homepage.

6. Vercel Deployment Guide

To deploy this project to Vercel:

  1. Import the repository in the Vercel Dashboard.
  2. In the Build and Output Settings, keep all commands at their default values. The build command will automatically run: 
    npm run build
    (which triggers prisma generate && next build as configured in package.json).
  3. Add the following Environment Variables under the project settings:
    • DATABASE_URL (Neon PostgreSQL database URL)
    • NEXTAUTH_SECRET (Random secret key)
    • NEXTAUTH_URL (Your production Vercel domain, e.g., https://your-project.vercel.app)
    • GOOGLE_CLIENT_ID & GOOGLE_CLIENT_SECRET (For OAuth)
    • RAZORPAY_KEY_ID & RAZORPAY_KEY_SECRET
    • RAZORPAY_WEBHOOK_SECRET
    • AWS_ACCESS_KEY_ID & AWS_SECRET_ACCESS_KEY
    • AWS_REGION & AWS_S3_BUCKET_NAME
    • SENDGRID_API_KEY
    • EMAIL_FROM_ADDRESS & EMAIL_FROM_NAME

7. Verification & Quality Commands

Ensure all checks pass before submitting pull requests:

  • Lint Checking: 
    npm run lint
  • Testing Suites: 
    npm test