TaskFlow API

A production-ready REST API built with Node.js, TypeScript and Fastify. It demonstrates backend best practices: authentication with JWT refresh-token rotation, role-based access control (RBAC), pagination/filters/sorting, rate limiting, automated tests and CI/CD.

Features

• Authentication: register, login, logout and refresh-token rotation.
• RBAC: user and admin roles with protected endpoints.
• Tasks: full CRUD with filters, sorting and pagination.
• Security: password hashing, short-lived access tokens, Redis-backed refresh-token blacklist, rate limiting and Helmet headers.
• Database: PostgreSQL with Drizzle ORM, migrations and seed script.
• API docs: OpenAPI/Swagger UI available at /documentation.
• DevOps: Docker, Docker Compose and GitHub Actions CI.
• Testing: integration tests with Vitest, Supertest, PostgreSQL and Redis.

Tech Stack

Layer	Technology
Runtime	Node.js 20+
Language	TypeScript 5
Framework	Fastify 5
ORM	Drizzle ORM
Database	PostgreSQL 16
Cache	Redis 7
Auth	JWT (access + refresh)
Validation	Zod
Logging	Pino
Test	Vitest + Supertest
CI/CD	GitHub Actions

Getting Started

Prerequisites

• Node.js 20+
• pnpm 8+
• PostgreSQL 16+ and Redis 7+ (or use Docker Compose below)

Install

git clone https://github.com/loSpaccaBit/taskflow-api.git
cd taskflow-api
pnpm install
cp .env.example .env

Update .env with your credentials.

Run with Docker Compose

cp .env.example .env
# Optional: set strong secrets in .env
docker compose up --build

The API will be available at http://localhost:3000 and Swagger UI at http://localhost:3000/documentation.

Run Locally

1. Start PostgreSQL and Redis.
2. Apply migrations:

pnpm db:migrate

3. Seed the database (optional):

pnpm db:seed

4. Start the dev server:

pnpm dev

API Endpoints

Health

Method	Endpoint	Description
GET	/health	Basic health check
GET	/health/db	Database connectivity check

Auth

Method	Endpoint	Description
POST	/auth/register	Register a new user
POST	/auth/login	Login and receive tokens
POST	/auth/refresh	Rotate refresh token
POST	/auth/logout	Revoke refresh token

Users

Method	Endpoint	Auth	Description
GET	/users/me	User	Get current profile
PATCH	/users/me	User	Update current profile
GET	/users	Admin	List users with pagination
PATCH	/users/:id/role	Admin	Change user role

Tasks

Method	Endpoint	Auth	Description
GET	/tasks	User	List tasks (filters, sort, pagination)
POST	/tasks	User	Create a task
GET	/tasks/:id	User	Get a task
PATCH	/tasks/:id	User	Update a task
DELETE	/tasks/:id	User	Delete a task

Environment Variables

Variable	Description
NODE_ENV	Environment: development, test or production
PORT	Server port
DATABASE_URL	PostgreSQL connection string
REDIS_URL	Redis connection string
JWT_ACCESS_SECRET	Secret for access tokens
JWT_REFRESH_SECRET	Secret for refresh tokens
JWT_ACCESS_EXPIRES_IN	Access token TTL (e.g. 15m)
JWT_REFRESH_EXPIRES_IN	Refresh token TTL (e.g. 7d)
RATE_LIMIT_MAX	Max requests per minute per IP

Testing

pnpm test

By default, the test suite uses PGlite (an in-memory PostgreSQL implementation) and ioredis-mock, so no Docker or local services are required. The CI pipeline runs the same tests against real PostgreSQL and Redis containers.

To run tests against real services:

export DATABASE_URL=postgresql://postgres:postgres@localhost:5432/taskflow
export REDIS_URL=redis://localhost:6379
export TEST_USE_MOCK=false
pnpm db:migrate
pnpm test

Scripts

pnpm dev           # Start development server
pnpm build         # Compile TypeScript
pnpm start         # Start production server
pnpm db:migrate    # Run database migrations
pnpm db:seed       # Seed the database
pnpm db:studio     # Open Drizzle Studio
pnpm lint          # Run ESLint
pnpm type-check    # Run TypeScript checks
pnpm test          # Run tests
pnpm format        # Format code with Prettier

Contributing

See CONTRIBUTING.md.

Security

See SECURITY.md.

License

MIT © Francesco Nocerino