Task Management API Documentation

Hello! 👋

I have built this Task Management API as part of my assignment for dMACQ Software Private Limited. This is a complete production-ready application with proper authentication, role-based access, and analytics features. Let me walk you through what I have created and how you can use it.

📋 What I Have Built

This is a multi-user task management system where:

• Users can register and login into the system
• They can create, update, delete their own tasks only
• Admins can see everyone's tasks and get proper analytics
• Everything is secured with JWT tokens properly
• Built with NestJS in Nx monorepo structure (exactly as mentioned in requirements)
• Using MongoDB for database operations
• Fully Dockerized for easy deployment anywhere

🛠️ Tech Stack I Used

I have used exactly what was mentioned in the assignment document:

• Backend: Node.js + TypeScript + NestJS v9+
• Database: MongoDB (Cosmos DB compatible with Mongo API)
• Authentication: Passport + JWT tokens
• Testing: Jest with 70%+ coverage achieved
• Containerization: Docker + Docker Compose
• Architecture: Nx Monorepo (this was mandatory requirement)

🏗️ Project Structure

I have organized the entire codebase in Nx monorepo format as specified in requirements:

task-management-api/
├── apps/
│   └── backend/                    # Main NestJS application
│       ├── src/
│       │   ├── main.ts
│       │   └── app/
├── libs/
│   ├── auth/                   # JWT, Guards, Strategies, DTOs
│   │   ├── guards/
│   │   ├── strategies/
│   │   └── dto/
│   ├── models/                 # Shared DTOs, enums, Mongoose schemas
│   │   ├── user/
│   │   └── task/
│   ├── data-access/            # DB repositories (Cosmos/Mongo layer)
│   ├── tasks/                  # Task module (controller + service)
│   ├── users/                  # User module (controller + service)
│   ├── analytics/              # Analytics module
│   └── utils/                  # Common helpers (error handling, pipes, interceptors)
├── docker-compose.yml
├── Dockerfile
└── README.md

Each module is having specific responsibility only:

• AuthModule → login, register, JWT, guards everything
• UsersModule → user schema + repository layer
• TasksModule → all CRUD endpoints
• AnalyticsModule → aggregate queries for admin
• Utils → validation pipes, exception filter, common stuff

🚀 How to Setup This Project

I have provided two different ways to run this application - locally on your machine and with Docker containers.

Method 1: Local Development Setup

What you need first:

• Node.js v18+ should be installed
• MongoDB running locally or connection string ready
• Git installed on your system

Follow these steps:

1. Clone the repository first:

   git clone <your-repo-url> .

2. Install all dependencies:

   npm install

3. Create environment file: Make one .env file in root directory:

   # Database connection details
   MONGO_URI=mongodb://localhost:27017/taskmanagement
   DB_NAME=taskmanagement
   
   # JWT configuration settings
   JWT_SECRET=your-super-secret-jwt-key-change-this-in-production
   JWT_EXPIRES_IN=7d
   
   # Application settings
   PORT=4000
   NODE_ENV=development

4. Start the application now:

   # Run in development mode
   npm run start:dev
   
   # Build for production
   npm run build
   
   # Run in production mode
   npm run start:prod

5. Test if everything is working:

   curl http://localhost:4000/api/v1/public

Method 2: Docker Setup (I Recommend This)

Using Docker means you don't need to install MongoDB separately on your machine. I have configured everything properly in docker-compose file.

Follow these steps:

1. Clone the repository first:

   git clone <your-repo-url>
   cd task-management-api

2. Create environment file:

   # For Docker setup use this
   MONGO_URI=mongodb://mongo:27017/taskmanagement
   DB_NAME=taskmanagement
   JWT_SECRET=your-super-secret-jwt-key
   JWT_EXPIRES_IN=7d
   PORT=4000
   NODE_ENV=production

3. Start Docker containers:

   # Start all services together (API + MongoDB)
   docker-compose up -d --build
   
   # Check the logs if needed
   docker-compose logs -f
   
   # Stop all services
   docker-compose down

4. Test everything is working:

   curl http://localhost:4000/api/v1/public

📚 Complete API Documentation

Base URL for all requests: http://localhost:4000/api/v1

Authentication Related APIs

1. Register New User

POST /auth/register
Content-Type: application/json

{
  "email": "john@example.com",
  "password": "password123",
  "name": "John Sharma",
  "role": "USER"  // This is optional, by default it will be USER
}

You will get this response:

{
  "success": true,
  "message": "User registered successfully",
  "data": {
    "user": {
      "id": "64f1a2b3c4d5e6f7g8h9i0j1",
      "email": "john@example.com",
      "name": "John Sharma",
      "role": "USER"
    }
  },
  "statusCode": 201
}

2. Login Into System

POST /auth/login
Content-Type: application/json

{
  "email": "john@example.com",
  "password": "password123"
}

You will get this response:

{
  "success": true,
  "message": "Login successful",
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "user": {
      "id": "64f1a2b3c4d5e6f7g8h9i0j1",
      "email": "john@example.com",
      "name": "John Sharma",
      "role": "USER"
    }
  },
  "statusCode": 200
}

Task Management APIs

Very Important: All task related APIs need JWT token. You must add it in header like this:

Authorization: Bearer <your-jwt-token>

1. Create New Task

POST /tasks
Content-Type: application/json
Authorization: Bearer <token>

{
  "title": "Complete assignment work",
  "description": "Finish the dMACQ task management API project",
  "status": "TODO",        // Options: TODO | IN_PROGRESS | DONE
  "priority": "HIGH",      // Options: LOW | MEDIUM | HIGH
  "dueDate": "2024-12-31T23:59:59.000Z"
}

2. Get Your Own Tasks

GET /tasks
Authorization: Bearer <token>

# Bonus feature: With filtering and pagination
GET /tasks?status=TODO&priority=HIGH&page=1&limit=5

You will get response like this:

{
  "success": true,
  "message": "Tasks retrieved successfully",
  "data": {
    "tasks": [
      {
        "id": "64f1a2b3c4d5e6f7g8h9i0j2",
        "title": "Complete assignment work",
        "description": "Finish the dMACQ task management API project",
        "status": "TODO",
        "priority": "HIGH",
        "dueDate": "2024-12-31T23:59:59.000Z",
        "createdAt": "2024-09-20T10:00:00.000Z",
        "updatedAt": "2024-09-20T10:00:00.000Z",
        "userId": "64f1a2b3c4d5e6f7g8h9i0j1"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 5,
      "total": 1,
      "totalPages": 1
    }
  },
  "statusCode": 200
}

3. Update Existing Task

PUT /tasks/:id
Content-Type: application/json
Authorization: Bearer <token>

{
  "title": "Updated assignment title",
  "status": "IN_PROGRESS",
  "completedAt": "2024-09-21T15:30:00.000Z"  // Set this when status becomes DONE
}

4. Delete Any Task

DELETE /tasks/:id
Authorization: Bearer <token>

Analytics APIs (Only For Admin Users)

These APIs can be accessed by ADMIN role users only.

Get Complete Task Analytics

GET /analytics/tasks
Authorization: Bearer <admin-token>

Admin will get response like this:

{
  "success": true,
  "message": "Analytics retrieved successfully",
  "data": {
    "taskCountsByStatus": {
      "TODO": 15,
      "IN_PROGRESS": 8,
      "DONE": 27
    },
    "averageCompletionTimeInDays": 3.5,
    "taskCountsByUser": [
      {
        "userId": "64f1a2b3c4d5e6f7g8h9i0j1",
        "userName": "John Sharma",
        "taskCount": 12
      },
      {
        "userId": "64f1a2b3c4d5e6f7g8h9i0j3",
        "userName": "Priya Singh",
        "taskCount": 8
      }
    ],
    "totalTasks": 50,
    "completedTasks": 27,
    "completionRate": 54
  },
  "statusCode": 200
}

🔒 Security Features I Implemented

I have implemented proper security as per industry standards:

Authentication & Authorization

• JWT tokens for secure authentication process
• Password hashing using bcrypt library
• Role-based access control (USER/ADMIN roles)
• Request validation using DTOs properly
• Guards for protecting all sensitive routes

Access Control Rules

• USER Role: Can access only their own tasks, nothing else
• ADMIN Role: Can access all tasks and analytics dashboard
• Ownership validation for all task related operations
• Centralized exception handling for consistent responses

Rate Limiting (Bonus Feature I Added)

// Maximum 100 requests per minute per user
@UseGuards(ThrottlerGuard)
@Throttle(100, 60)

🧪 Testing Implementation

I have implemented comprehensive testing as per requirements:

How to Run Tests

# Run all unit tests
npm run test

# Check test coverage report
npm run test:cov

# Run tests in watch mode
npm run test:watch

My Testing Structure

libs/
├── auth/
│   └── __tests__/
│       ├── auth.service.spec.ts
│       ├── jwt.strategy.spec.ts
│       └── role.guard.spec.ts
├── tasks/
│   └── __tests__/
│       ├── tasks.service.spec.ts
│       └── tasks.controller.spec.ts
└── analytics/
    └── __tests__/
        └── analytics.service.spec.ts

Coverage Requirements I Met

• My Achievement: 75%+ coverage (requirement was 70% minimum)
• Focus Areas: Services, Guards, Controllers all covered
• Test Types: Both Unit tests + Integration tests implemented

🛠️ Error Handling & Resiliency

I have implemented proper error handling throughout the application:

Centralized Exception Filter

• All errors are handled properly in one place
• Consistent error response format for all APIs
• HTTP status codes are set correctly always

DTO Validation Implementation

• All input data is validated using class-validator
• Proper 400 errors returned for validation failures
• Complete type safety with TypeScript

Database Error Handling

• MongoDB connection failures are handled gracefully
• Proper retry mechanisms implemented
• Timeout handling for all database operations

🎯 Bonus Features I Have Implemented

From the assignment bonus section, I have implemented these features:

✅ Pagination & Filtering

GET /tasks?status=TODO&priority=HIGH&page=2&limit=10

✅ Rate Limiting Protection

• Maximum 100 requests per minute per user
• Using @nestjs/throttler library properly
• Prevents API abuse and ensures fair usage

My Database Schema Design

I have designed this schema structure:

// User Schema Design
interface User {
  _id: ObjectId;
  email: string; // unique field
  password: string; // bcrypt hashed always
  name: string;
  role: 'USER' | 'ADMIN';
  createdAt: Date;
  updatedAt: Date;
}

// Task Schema Design
interface Task {
  _id: ObjectId;
  title: string;
  description?: string;
  status: 'TODO' | 'IN_PROGRESS' | 'DONE';
  priority: 'LOW' | 'MEDIUM' | 'HIGH';
  dueDate?: Date;
  completedAt?: Date; // Set only when status becomes DONE
  userId: ObjectId; // Task owner reference
  createdAt: Date;
  updatedAt: Date;
}

📝 Assignment Requirements Completion

I have completed all assignment requirements properly:

✅ Correctness

• All endpoints are working perfectly
• Authentication & authorization implemented correctly
• Role-based access control is working as expected
• JWT token validation is proper

✅ Code Quality

• Clean Nx monorepo structure maintained
• Modular architecture implemented properly
• TypeScript best practices followed throughout
• Proper separation of concerns everywhere

✅ Testing

• Jest unit & integration tests implemented
• 75%+ coverage achieved (more than required 70%)
• Meaningful test cases written
• Proper mock implementations done

✅ Resiliency

• Centralized exception filter implemented
• DTO validation with proper error messages
• Graceful database failure handling done
• HTTP status codes are set properly always

✅ DevOps

• Dockerfile created and optimized
• Docker-compose with API + MongoDB configured
• Local development environment supported
• Production-ready setup completed

✅ Bonus

• Pagination & filtering feature implemented
• Rate limiting protection added
• Clean API documentation provided

🤝 Development Tips for Further Work

If you want to develop this project further:

1. Database GUI: Use MongoDB Compass to view data easily
2. API Testing: Create Postman collection for easy testing
3. Debug Issues: Use docker-compose logs -f to check logs
4. Hot Reload: Development mode has automatic reload feature
5. Environment Management: Create different .env files for dev/prod

🚀 Production Deployment Ready

This application is completely production-ready:

• Docker images are optimized properly
• Environment variables configured correctly
• Error handling is comprehensive throughout
• Security best practices are followed
• Database connections are pooled efficiently
• Proper logging is implemented

📞 Contact & Final Notes

If you have any doubts or questions, feel free to reach out to me. I have built this project according to all assignment requirements and tested all features thoroughly. Everything is working as expected.

The application follows all the mentioned guidelines and implements every feature that was asked in the assignment document.

📧 Get in Touch

• Email: pankajkholiya04@gmail.com
• Phone: +91 7028531074
• LinkedIn: https://www.linkedin.com/in/ifeelpankaj
• Portfolio: https://pankaj-kholiya.netlify.app/

I am always open to discuss technical details, answer any questions about the implementation, or talk about potential improvements to this project.

Thank you for reviewing my work! 🚀

---

Built with dedication by Pankaj Kholiya for dMACQ Software Private Limited