TaskFlow API 🚀

Scalable REST API with JWT Authentication & Role-Based Access Control
Built with Node.js · Express · PostgreSQL · Docker

---

Features

Category	Details
Auth	Register, login, JWT tokens, bcrypt password hashing
RBAC	user and admin roles with route-level enforcement
Tasks CRUD	Create, read, update, delete with filters & pagination
Admin	User management, role promotion, platform stats
Security	Helmet, CORS, rate limiting, input validation (Joi)
Docs	Swagger UI at /api-docs + Postman collection
API Versioning	/api/v1/... prefix for forward compatibility
Deployment	Docker Compose with PostgreSQL + Redis included

---

Quick Start

1. Prerequisites

• Node.js 20+
• PostgreSQL 14+
• (Optional) Docker & Docker Compose

2. Clone & Install

git clone https://github.com/YOUR_USERNAME/taskflow-api.git
cd taskflow-api/backend
npm install

3. Configure Environment

cp .env.example .env
# Edit .env and set your DB credentials and JWT_SECRET

4. Initialize Database

# Create the database first
psql -U postgres -c "CREATE DATABASE taskflow_db;"

# Run schema + seed
npm run db:init

5. Start Server

npm run dev        # development (nodemon)
npm start          # production

Server runs on http://localhost:5000

---

Docker Deployment (Recommended)

# From project root
docker-compose up --build

# Scale API horizontally
docker-compose up --scale api=4

Services:

• Frontend: http://localhost:3000
• API: http://localhost:5000
• Swagger: http://localhost:5000/api-docs
• PostgreSQL: localhost:5432
• Redis: localhost:6379

---

API Reference

Base URL

http://localhost:5000/api/v1

Authentication

All protected endpoints require:

Authorization: Bearer <token>

---

Auth Endpoints

Method	Endpoint	Auth	Description
POST	/auth/register	✗	Register new user
POST	/auth/login	✗	Login → get JWT
GET	/auth/me	✓	Get own profile
PATCH	/auth/me	✓	Update name / password

Register

curl -X POST http://localhost:5000/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{"name":"Jane","email":"jane@example.com","password":"SecurePass1"}'

Login

curl -X POST http://localhost:5000/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"admin@taskflow.dev","password":"Admin@1234"}'

---

Tasks Endpoints

Method	Endpoint	Auth	Role	Description
GET	/tasks	✓	any	List tasks (with filters)
GET	/tasks/:id	✓	any	Get single task
POST	/tasks	✓	any	Create task
PATCH	/tasks/:id	✓	owner/admin	Update task
DELETE	/tasks/:id	✓	owner/admin	Delete task

Query Parameters (GET /tasks):

Param	Values	Default
status	todo, in_progress, done	—
priority	low, medium, high	—
page	integer	1
limit	1–50	10
sort	created_at, updated_at, priority, title	created_at
order	asc, desc	desc

---

Admin Endpoints (Admin role required)

Method	Endpoint	Description
GET	/admin/stats	Platform statistics
GET	/admin/users	List all users
PATCH	/admin/users/:id/role	Change user role
DELETE	/admin/users/:id	Delete user account

---

Database Schema

users
  id            UUID PRIMARY KEY
  name          VARCHAR(50)
  email         VARCHAR(255) UNIQUE
  password_hash TEXT
  role          VARCHAR(10) DEFAULT 'user'   -- 'user' | 'admin'
  created_at    TIMESTAMPTZ
  updated_at    TIMESTAMPTZ

tasks
  id            UUID PRIMARY KEY
  title         VARCHAR(120)
  description   TEXT
  status        VARCHAR(20) DEFAULT 'todo'   -- 'todo' | 'in_progress' | 'done'
  priority      VARCHAR(10) DEFAULT 'medium' -- 'low' | 'medium' | 'high'
  user_id       UUID REFERENCES users(id) ON DELETE CASCADE
  created_at    TIMESTAMPTZ
  updated_at    TIMESTAMPTZ

---

Project Structure

taskflow-api/
├── backend/
│   ├── src/
│   │   ├── config/
│   │   │   ├── db.js              # PostgreSQL connection pool
│   │   │   └── swagger.js         # OpenAPI spec config
│   │   ├── controllers/
│   │   │   ├── auth.controller.js
│   │   │   ├── tasks.controller.js
│   │   │   └── admin.controller.js
│   │   ├── middleware/
│   │   │   ├── auth.js            # JWT verify + role check
│   │   │   ├── validate.js        # Joi validation factory
│   │   │   └── errorHandler.js    # Global error handler
│   │   ├── routes/
│   │   │   ├── index.js           # Version router
│   │   │   └── v1/
│   │   │       ├── auth.routes.js
│   │   │       ├── tasks.routes.js
│   │   │       └── admin.routes.js
│   │   ├── validators/
│   │   │   ├── auth.validator.js
│   │   │   └── task.validator.js
│   │   └── schema/
│   │       ├── init.sql           # DB schema + seed
│   │       └── initDb.js          # Runner script
│   ├── server.js
│   ├── Dockerfile
│   └── package.json
├── frontend/
│   └── index.html                 # Single-page UI
├── docs/
│   └── TaskFlow.postman_collection.json
├── docker-compose.yml
├── SCALABILITY.md
└── README.md

---

API Documentation

Swagger UI: http://localhost:5000/api-docs

Postman: Import docs/TaskFlow.postman_collection.json

1. Run Login first — token is auto-saved to collection variable
2. All authenticated requests use {{token}} automatically

---

Security Practices

• Password hashing: bcrypt with cost factor 12
• JWT: Signed with HS256, expiry enforced, user existence re-checked on every request
• Input validation: Joi schemas strip unknown fields, enforce types and lengths
• Rate limiting: 100 req/15 min globally, 20 req/15 min on auth routes
• HTTP headers: helmet sets HSTS, X-Frame-Options, CSP, etc.
• CORS: Explicit allowlist, no wildcard in production
• Generic auth errors: "Invalid email or password" prevents email enumeration
• SQL injection: Parameterised queries throughout (no string interpolation)

---

Default Credentials

Email	Password	Role
admin@taskflow.dev	Admin@1234	admin

⚠️ Change the default password immediately in any non-demo environment.

---

Roadmap / Optional Enhancements

• Redis caching for task lists
• Email verification on registration
• Refresh token rotation
• File attachments on tasks (S3)
• WebSocket notifications (Socket.IO)
• Unit & integration tests (Jest + Supertest)
• CI/CD pipeline (GitHub Actions)