🗒️Task Manager API

Overview

Task Manager API is a backend-focused portfolio project designed to demonstrate backend fundatmentals, API security, role-based access control (RBAC), and database design using Node.js and PostgreSQL.

The project simulates a task management system with users, teams, roles, and permissions, going beyond basic CRUD to showcase authorization logic, structured testing, and Docker-based deployment.

This project is intentionally built as a backend-only service to highlight server-side design, not UI implementation.

---

Table of Contents

• Getting Started
  • Docker Setup (Recommended)
  • Local Setup (Without Docker)
• Key Features
• Tech Stack
• Architecture Overview
• Project Structure
• Authentication Flow
• API Endpoints
• Database Design
• Security Considerations
• Testing

---

Getting Started

1. Clone the repository

   git clone https://github.com/bx0518/task-manager-api.git
   cd task-manager-api

2. Create .env file

   PORT=3000
   DB_HOST=localhost
   DB_PORT=5432
   DB_USER=your_postgre_username
   DB_PASSWORD=your_postgre_password
   DB_NAME=taskdb
   JWT_SECRET=your_jwt_secret

   • Replace your_postgre_username, your_postgre_password, and your_jwt_secret with appropriate values.
   • DB_HOST will be automatically overriden to postgres when using Docker.

3. Set up project either with Docker or locally.

Docker Setup (Recommended)

Using Docker allows you to avoid installing Node.js and PostgreSQL locally. Docker will handle all required services (including the database).

Prerequisites

Make sure you have Docker and Docker Compose installed on your machine.

Steps

1. Build and start services

   docker-compose up --build

2. Access the API API will be available at http://localhost:3000.

Docker handles:

• PostgreSQL service
• Database initialization (runs automatically when the container starts)

---

Local Setup (Without Docker)

If you prefer to run the API directly on your machine, follow these steps.

Prerequisites

Ensure you have the following installed:

• Node.js >= 18
• PostgreSQL >= 14
• npm

Steps

1. Install dependencies

   npm install

2. Create PostgreSQL Database You need to create a PostgreSQL database and run the initialization script:

   psql -h localhost -U postgres -d taskdb -f init-db.sql

3. Start the server

   npm start

4. Access the API The API will be available at http://localhost:3000.

---

Key Features

• User authentication with JWT
• Secure password hashing with bcrypt
• Role-Based Access Control (RBAC) with permissions
• Team-based task visibility and management
• Admin and manager privilege seperation
• Input validation with Joi
• Centralized logging with Winston
• API security middleware (rate limiting, headers, compression)
• PostgreSQL relational database with migrations
• Dockerized environment
• Automated tests using Jest + Supertest

---

Tech Stack

Backend

• Node.js (Express v5)
• PostgreSQL

Security & Middleware

• JWT (jsonwebtoken)
• bcrypt
• express-rate-limit
• helmet
• compression

Validation & Logging

• Joi
• Winston

Testing

• Jest
• Supertest

DevOps / Tooling

• Docker & Docker Compose
• dotenv

---

Architecture Overview

This API follows a layered architecture commonly used in production backend systems:

Client
↓
Routes (HTTP layer)
↓
Middleware (Auth, RBAC, Validation)
↓
Controllers
↓
Models (PostgreSQL Database Access)

Request Lifecycle

1. Request enters Express Router
2. Security middleware runs first (rate limit, headers)
3. Authentication middleware validates JWT
4. RBAC middleware checks permissions & resource ownership
5. Validation middleware ensures request shape
6. Controller logic executes business rules
7. Modles executes database query
8. Standardized response returned

This separation ensures the codebase remains maintainable, testable, and scalable.

---

Project Structure

task-manager-api/
├── controllers/ # Business logic
├── middleware/ # Auth, RBAC, security
├── migrations/ # DB migrations
├── models/ # Database models
├── routes/ # API routes
├── tests/ # Unit & integration tests
├── utils/ # Helper utilities (e.g. logger)
├── .env.example # Sample environment variables
├── app.js # Entry point
├── db.js # PostgreSQL connection
├── docker-compose.yml # Multi-container setup
├── Dockerfile # App container definition
└── init-db.sql # Initial database setup

---

Authentication Flow

1. User registers via /users/register
2. Password is hashed using bcrypt
3. User logs in via /users/login
4. Server issues a JWT access token
5. Token must be sent in Authorization: Bearer <token> header

---

Authorization & RBAC Design

This project implements permission-based RBAC, not simple role checks to avoids hard-coded role logic, makes permission changes easier, and mirrors enterprise authorization systems.

Roles

• admin - full system access
• manager - team-level access
• user - own-resource access

---

API Endpoints

Detailed API documentation is available in documentation/api.md

Auth

• POST /users/register
• POST /users/login

Tasks

• POST /tasks
• GET /tasks
• GET /tasks/:id
• PUT /tasks/:id
• DELETE /tasks/:id
• GET /tasks/team

Admin Tasks

• GET /tasks/admin/all
• GET /tasks/admin/user/:id
• GET /tasks/admin/team/:teamId
• DELETE /tasks/admin/:id

User & Team Management

• GET /admin/users
• PUT /admin/users
• DELETE /admin/users
• POST /teams
• GET /teams
• PUT /teams/assign
• DELETE /teams/:id

---

Database Design

The databased is designed to support RBAC and team-based access.

Core tables：

• users
• roles
• teams
• tasks

Relationships:

• Each user has one role
• Users may belong to a team
• Tasks are owned by users and optionally linked to teams

Detailed schema explanation is available in documentation/database.md

---

Security Considerations

• Password hashing with bcrypt (salted)
• JWT expiration & verification middleware
• Rate limiting to mitigate brute-force attacks
• Helmet for secure HTTP headers
• Centralized request logging for audit & debugging

---

Testing

Run tests:

npm test

What is Tested

• Authentication (valid / invalid JWT)
• Authorization (RBAC permission)
• Resource ownership checks
• Admin-only routes
• Task CRUD flows

---