🚀 Web-Based Project Management System

A comprehensive, specialized project management platform designed specifically for web agencies and freelance web developers. This system enables seamless collaboration, project tracking, client management, and team communication.

---

---

📋 Table of Contents

• Features
• Tech Stack
• Project Structure
• Prerequisites
• Installation
• Configuration
• Running the Application
• Testing
• API Documentation
• Database Schema
• File Upload & Cloud Storage
• Deployment
• Contributing

---

✨ Features

Core Project Management

• Workspace Management: Create and manage multiple workspaces for different agencies or clients
• Project Creation & Tracking: Full lifecycle management from conception to completion
• Task Management: Create, assign, and track tasks with priorities and dependencies
• Milestones & Deliverables: Track key project milestones and deliverable submissions
• Checklists: Template-based and custom checklists for quality assurance
• Timeline & Scheduling: Visual project timelines and milestone tracking

Collaboration & Communication

• Real-time Chat: Socket.io-powered chat rooms for project discussions
• Notifications: Real-time notifications for important project updates
• Comments & Feedback: Inline feedback on tasks and deliverables
• Team Members: Role-based member management (Admin, Manager, Member)

Client Management

• Client Portal: Dedicated interface for client interactions
• Project Visibility: Clients can view project progress and deliverables
• Payment Tracking: Integrated payment management and payment history

Advanced Features

• Reports & Analytics: Comprehensive project reports and performance analytics
• Email Notifications: Automated email notifications via Resend
• File Management: Cloud-based file uploads via Cloudinary
• Google OAuth: Social login integration for user convenience
• Rate Limiting: API rate limiting for stability and security
• Security: Helmet protection, XSS prevention, input sanitization, password hashing

Admin Features

• Marketing Email Management: Send and track marketing emails
• System Reports: Comprehensive system-wide reporting

---

🛠️ Tech Stack

Backend

Technology	Purpose
Node.js + Express.js	REST API server
TypeScript	Type-safe JavaScript
MongoDB + Mongoose	NoSQL database with ODM
Socket.io	Real-time bidirectional communication
Passport.js	Authentication (Local & Google OAuth)
Multer	File upload handling
Cloudinary	Cloud file storage
Resend	Email service
Helmet	HTTP headers security
Zod	Schema validation
Vitest + Supertest	Testing framework
Winston	Logging

Frontend

Technology	Purpose
React 18	UI library
TypeScript	Type-safe JavaScript
Vite	Build tool & dev server
React Router	Client-side routing
React Query (@tanstack/react-query)	Server state management
React Hook Form	Form state management
Radix UI	Headless UI components
Tailwind CSS	Utility-first CSS framework
Axios	HTTP client
DnD Kit	Drag & drop functionality
Date-fns	Date manipulation
Vitest	Unit testing

---

📁 Project Structure

Web-Based-Project-Management-System/
├── backend/                          # Express.js REST API
│   ├── src/
│   │   ├── @types/                   # TypeScript declarations
│   │   ├── config/                   # Configuration files
│   │   ├── controllers/              # Route handlers
│   │   ├── data/                     # Seed data and templates
│   │   ├── enums/                    # TypeScript enums
│   │   ├── middlewares/              # Express middlewares
│   │   ├── models/                   # Mongoose schemas
│   │   ├── routes/                   # API routes
│   │   ├── seeders/                  # Database seeders
│   │   ├── services/                 # Business logic
│   │   ├── socket/                   # Socket.io handlers
│   │   ├── tests/                    # Unit tests
│   │   ├── utils/                    # Utility functions
│   │   ├── validation/               # Request validation schemas
│   │   └── index.ts                  # Entry point
│   ├── package.json
│   ├── tsconfig.json
│   └── vitest.config.ts
│
├── client/                           # React + Vite frontend
│   ├── src/
│   │   ├── components/               # React components
│   │   ├── constant/                 # Constants
│   │   ├── context/                  # React context providers
│   │   ├── hoc/                      # Higher-order components
│   │   ├── hooks/                    # Custom React hooks
│   │   ├── layout/                   # Layout components
│   │   ├── lib/                      # Utility libraries
│   │   ├── page/                     # Page components
│   │   ├── routes/                   # Route configuration
│   │   ├── tests/                    # Unit tests
│   │   ├── types/                    # TypeScript type definitions
│   │   ├── App.tsx
│   │   ├── main.tsx
│   │   └── index.css
│   ├── public/                       # Static assets
│   ├── package.json
│   ├── tsconfig.json
│   ├── vite.config.ts
│   └── vitest.config.ts
│
├── .git/                             # Git repository
├── .gitignore
├── .prettierrc                        # Prettier config
└── README.md                         # This file

---

📦 Prerequisites

Before you begin, ensure you have the following installed:

• Node.js >= 18.0.0 (Download)
• npm >= 9.0.0 or yarn >= 3.0.0
• MongoDB >= 5.0 (for local development)
• Git >= 2.0.0

External Services Required

1. MongoDB Atlas (or local MongoDB)

   • Create a cluster and get connection string

2. Cloudinary (for image uploads)

   • Sign up at cloudinary.com
   • Get your API credentials

3. Resend (for email notifications)

   • Sign up at resend.com
   • Get your API key

4. Google OAuth (for social login)

   • Create a project in Google Cloud Console
   • Set up OAuth 2.0 credentials (Web application)
   • Get Client ID and Client Secret

---

🚀 Installation

1. Clone the Repository

git clone <repository-url>
cd "Web-Based-Project-Management-System-Specialized-for-Web-Agencies-and-Freelance-Web-Developers"

2. Backend Setup

cd backend

# Install dependencies
npm install

# Create .env file (see Configuration section below)
cp .env.example .env

# Install TypeScript globally (optional but recommended)
npm install -g typescript

3. Frontend Setup

cd ../client

# Install dependencies
npm install

# Create .env file (see Configuration section below)
cp .env.example .env

---

🔧 Configuration

Backend Environment Variables

Create a .env file in the backend/ directory:

# Server Configuration
BASE_PATH=/api/v1
PORT=5000
NODE_ENV=development

# Database
MONGODB_URI=mongodb+srv://username:password@cluster.mongodb.net/dbname?retryWrites=true&w=majority

# Session
SESSION_SECRET=your-random-secret-key-min-32-chars

# Authentication
JWT_SECRET=your-jwt-secret-key
JWT_EXPIRES_IN=7d

# Google OAuth
GOOGLE_CLIENT_ID=your-google-client-id
GOOGLE_CLIENT_SECRET=your-google-client-secret
GOOGLE_CALLBACK_URL=http://localhost:5000/api/v1/auth/google/callback

# Cloudinary
CLOUDINARY_CLOUD_NAME=your-cloud-name
CLOUDINARY_API_KEY=your-api-key
CLOUDINARY_API_SECRET=your-api-secret

# Email Service (Resend)
RESEND_API_KEY=your-resend-api-key
SENDER_EMAIL=noreply@yourdomain.com

# Frontend URL
CLIENT_URL=http://localhost:5173

# CORS
CORS_ORIGIN=http://localhost:5173

# Rate Limiting
RATE_LIMIT_WINDOW_MS=900000
RATE_LIMIT_MAX_REQUESTS=100

Frontend Environment Variables

Create a .env file in the client/ directory:

VITE_API_BASE_URL=http://localhost:5000/api/v1
VITE_SOCKET_URL=http://localhost:5000

---

🎯 Running the Application

Development Mode

Terminal 1: Start Backend

cd backend
npm run dev

The backend server will start at http://localhost:5000

Terminal 2: Start Frontend

cd client
npm run dev

The frontend will start at http://localhost:5173

Production Build

Backend

cd backend
npm run build
npm start

Frontend

cd client
npm run build
npm run preview

---

🧪 Testing

Backend Tests

cd backend

# Run all tests
npm test

# Run tests with coverage
npm test -- --coverage

# Run tests in watch mode
npm test -- --watch

Frontend Tests

cd client

# Run all tests
npm test

# Run tests with coverage and generate report
npm test -- --coverage

# Run tests in watch mode
npm test -- --watch

---

📚 API Documentation

Base URL

http://localhost:5000/api/v1

Available Routes

Authentication

• POST /auth/register - Register new user
• POST /auth/login - Login user
• POST /auth/logout - Logout user
• GET /auth/google - Google OAuth login
• GET /auth/google/callback - Google OAuth callback

Users

• GET /users/:id - Get user profile
• PUT /users/:id - Update user profile
• GET /users - List all users (admin)

Workspaces

• POST /workspaces - Create workspace
• GET /workspaces - Get user workspaces
• PUT /workspaces/:id - Update workspace
• DELETE /workspaces/:id - Delete workspace

Projects

• POST /projects - Create project
• GET /projects - Get projects
• PUT /projects/:id - Update project
• DELETE /projects/:id - Delete project
• GET /projects/:id/reports - Get project reports

Tasks

• POST /tasks - Create task
• GET /tasks - Get tasks
• PUT /tasks/:id - Update task
• DELETE /tasks/:id - Delete task
• PATCH /tasks/:id/status - Update task status

Deliverables

• POST /deliverables - Create deliverable
• GET /deliverables - Get deliverables
• PUT /deliverables/:id - Update deliverable
• POST /deliverables/:id/feedback - Add feedback

Chat

• POST /chat/rooms - Create chat room
• GET /chat/rooms - Get chat rooms
• POST /chat/messages - Send message
• GET /chat/rooms/:roomId/messages - Get messages

Payments

• POST /payments - Record payment
• GET /payments - Get payments
• GET /payments/history - Get payment history

Notifications

• GET /notifications - Get notifications
• PATCH /notifications/:id/read - Mark as read
• DELETE /notifications/:id - Delete notification

For detailed API documentation, refer to route files in backend/src/routes/

---

🗄️ Database Schema

Core Collections

Workspace

• Members management
• Project organization
• Settings

Project

• Milestones
• Tasks
• Deliverables
• Timeline

Task

• Assignments
• Status tracking
• Priority levels
• Dependencies

User

• Authentication
• Profile information
• Role assignments
• Preferences

ChatMessage & ChatRoom

• Real-time messaging
• Room-based conversations
• Message history

Payment

• Transaction records
• Payment history
• Invoice data

Notification

• Event notifications
• User notifications
• Read/unread status

For detailed schema definitions, see backend/src/models/

---

📁 File Upload & Cloud Storage

Image Upload

• Handled via Cloudinary
• Maximum file size: 10MB
• Supported formats: JPG, PNG, GIF, WebP
• Chat message images are auto-cleaned after 30 days

Configuration

// backend/src/config/cloudinary.config.ts
// Cloudinary is configured via environment variables

---

🌐 Deployment

Backend Deployment (Heroku/Railway/Render)

1. Push code to Git repository
2. Set environment variables
3. Ensure MongoDB is accessible
4. Deploy using platform's CLI or GitHub integration

Frontend Deployment (Vercel/Netlify)

1. Build the application:

   npm run build

2. Deploy dist/ folder to hosting platform

3. Set VITE_API_BASE_URL environment variable to production backend URL

Docker Deployment (Optional)

Create Dockerfile for backend:

FROM node:18-alpine
WORKDIR /app
COPY package*.json ./
RUN npm install
COPY . .
RUN npm run build
EXPOSE 5000
CMD ["npm", "start"]

---

👥 Contributing

Code Style

• Use TypeScript for type safety
• Follow existing code structure
• Format code with Prettier: npm run lint
• Write tests for new features

Pull Request Process

1. Fork the repository
2. Create a feature branch: git checkout -b feature/your-feature
3. Commit changes: git commit -m 'Add your feature'
4. Push to branch: git push origin feature/your-feature
5. Open a Pull Request