Five Services - Freelance Marketplace

Five Services is a full-stack freelance marketplace application where users can offer services, book professionals, and communicate in real-time. It features a modern service booking flow, role-based authentication (Client/Freelancer), and a real-time messaging system powered by Socket.IO.

This project is a monorepo designed to demonstrate advanced full-stack patterns, separating the real-time socket server from the Next.js application logic while maintaining a shared type-safe database layer.

---

Key Features

• Role-Based Access Control: Distinct flows for Clients (Buyers) and Freelancers (Sellers).
• Service Booking System: Comprehensive booking workflow with status tracking.
• Real-Time Messaging: Instant chat functionality between clients and freelancers using Socket.IO.
• Live Online Status: Real-time user presence detection.
• Media Sharing: Support for sending images and files in chat (integrated with Cloudinary).
• Modern UI/UX: Built with Tailwind CSS, Shadcn UI, and smooth animations.

---

Tech Stack

Frontend

• Framework: Next.js 16 (App Router)
• Language: TypeScript
• Styling: Tailwind CSS, Shadcn UI, Magic UI
• State/Animations: Motion (Framer Motion), React Hook Form

Backend

• Runtime: Node.js
• API Endpoints: Server Actions
• Real-Time: Socket.IO, Express
• Language: TypeScript

Database & ORM

• Database Host: NeonDb
• Database: PostgreSQL (Single shared instance)
• ORM: Prisma (Managed within the Frontend/Next.js layer)

Tooling

• Monorepo Management: npm workspaces
• Linting: ESLint

---

Project Structure

This project uses a monorepo structure to separate the frontend application from the real-time socket server.

/root
├── /frontend       → Next.js application (owns Database & Prisma)
├── /backend        → Socket.IO server (lightweight, real-time only)
└── package.json    → Shared scripts for the entire monorepo

Architectural Note: Why Prisma is in /frontend?

In this architecture, the Frontend (Next.js) serves as the primary backend for CRUD operations, authentication, and business logic using Server Actions and API routes. Therefore, it owns the Prisma schema and migrations. The Backend folder is strictly for the Socket.IO server to handle ephemeral real-time connections. This separation ensures the socket server remains lightweight and stateless, while the Next.js app handles data integrity.

---

Environment Variables

Both the frontend and backend require environment variables to function correctly.

Frontend (/frontend/.env)

Required for database connections, authentication, and API endpoints.

DATABASE_URL="postgresql://..."
BETTER_AUTH_SECRET="your-secret"
BETTER_AUTH_URL="http://localhost:3000"
NEXT_PUBLIC_SOCKET_URL="http://localhost:9000"
NEXT_PUBLIC_CLOUDINARY_CLOUD_NAME="your-cloud-name"

Refrence .env.example in the frontend directory for a complete list.

Backend (/backend/.env)

Required for database access (via the shared Prisma client) and server configuration.

DATABASE_URL="postgresql://..."
PORT=9000

---

Installation & Setup

Follow these steps to run the project on a fresh machine.

1. Clone the repository

git clone <repository-url>
cd five-services

2. Configure Environment Variables

First, set up your environment variables by copying the example file:

cp frontend/.env.example frontend/.env

Action Required: Open the newly created frontend/.env file and populate the required environment variables (such as DATABASE_URL and Authentication secrets) to matching your local integration. This step is mandatory for the app to run.

3. Install & Setup

Run the setup script which installs dependencies, generates the Prisma client, and runs migrations.

npm run setup:dev

Note: setup:dev automatically runs npm install, generates the Prisma client, and pushes DB migrations.

4. Start the development servers

This will start both the Next.js frontend and the Socket.IO backend concurrently.

npm run dev

The app should now be accessible at:

• Frontend: http://localhost:3000
• Socket Server: http://localhost:9000

---

Available Scripts

Here is a breakdown of the available commands in the root package.json:

• npm run install:all - Installs dependencies for the root, frontend, and backend.
• npm run prisma:generate - Regenerates the Prisma client (useful after schema changes).
• npm run prisma:migrate - Runs database migrations to keep the DB schema in sync.
• npm run dev - Starts both frontend and backend in development mode.
• npm run build - Builds the Next.js frontend application for production.

When to use them?

• Use setup:dev when you first pull the repo.
• Use dev for daily development.
• Use prisma:generate if PrismaClient types are out of sync.

---

Database & Prisma Notes

• Server-Side Only: Prisma is instantiated and run only on the server side of Next.js (in Server Actions or API routes). No sensitive database logic is exposed to the client browser.
• Shared Access: The backend (Socket.IO) imports the generated Prisma client from the frontend directory. This allows the socket server to validate session tokens or save messages directly to the shared database without duplicating the schema.

---

Production Notes

• Frontend: The Next.js application is production-ready and can be deployed to Vercel or any Node.js hosting platform.
• Backend: The Socket.IO server is a separate Node.js process and should be deployed to a service that supports persistent connections (e.g., Railway, Heroku, or a VPS).
• Environment: ensure DATABASE_URL is consistent across both deployments so they share the same data.

---

Why This Project?

This application was built as a comprehensive Portfolio & Learning Project to demonstrate:

• Full-Stack Proficiency: end-to-end development handling database, auth, UI, and deployment.
• Real-Time Systems: Implementing complex socket logic for messaging and presence.
• Architecture: Making deliberate choices (like monorepo & shared Prisma types) to solve specific structural challenges in modern web apps.