Acquisition API

A RESTful user authentication and management API built with Node.js, Express 5, and PostgreSQL (via Neon). It provides secure user registration, login, logout, and full CRUD user management with role-based access control (RBAC).

Summary

Acquisition API is a production-ready backend service that handles the complete user lifecycle — from account creation with hashed passwords to JWT-based authentication and role-protected endpoints. Admins can manage all users while regular users can only access and modify their own accounts. The API is secured with Helmet, CORS, Arcjet rate limiting, and structured logging via Winston. It ships with Docker support for both local development (using Neon Local ephemeral database branches) and production deployments.

Features

• User Authentication — Sign up, sign in, and sign out with JWT tokens stored in HTTP-only cookies
• Password Hashing — Secure password storage using bcrypt
• Role-Based Access Control — admin and user roles with middleware-enforced permissions
• Soft Delete — Users are soft-deleted via a deleted_at timestamp instead of being permanently removed
• Pagination — Paginated user listing with configurable page and limit query parameters
• Input Validation — Request validation powered by Zod schemas
• Configurable CORS — Origin allowlist controlled via the CORS_ORIGIN environment variable
• Security Hardening — Helmet for HTTP headers, Arcjet for bot detection, shield protection, and role-based rate limiting (admin: 20/min, user: 10/min, guest: 5/min)
• Error Handling — Centralized 404 handler and global error handler with environment-aware error messages
• Structured Logging — Winston logger with file and console transports
• Database Migrations — Drizzle ORM with migration generation and push support
• Docker Support — Multi-stage Dockerfile with development and production Compose configurations
• CI/CD — GitHub Actions workflows for tests, linting, formatting, and Docker image builds

Tech Stack

Category	Technology
Runtime	Node.js 20
Framework	Express 5
Language	JavaScript (ES Modules)
Database	PostgreSQL via Neon
ORM	Drizzle ORM
Authentication	JSON Web Tokens (jsonwebtoken) + bcrypt
Validation	Zod
Security	Helmet, CORS, Arcjet (rate limiting, bot detection, shield)
Logging	Winston + Morgan
Testing	Jest + Supertest
Code Quality	ESLint + Prettier
Containerization	Docker + Docker Compose

Architecture Overview

The diagram below shows how the major components of the system interact:

graph TD
    Client["🌐 Client\n(Browser / Mobile / Postman)"]

    subgraph API["Acquisition API  (Express 5)"]
        direction TB
        MW["Security Middleware\n(Helmet · CORS · Arcjet · Morgan)"]
        Router["Router\n/api/auth · /api/users · /api/acquisition"]
        AuthMW["Auth Middleware\n(JWT verify · Role check)"]
        Controllers["Controllers\n(auth · user)"]
        Services["Services\n(auth · user)"]
        Utils["Utilities\n(jwt · cookies · format)"]
    end

    DB[("🐘 PostgreSQL\n(Neon Cloud)")]
    Logger["📋 Winston Logger\n(console + file)"]

    Client -->|HTTP Request| MW
    MW --> Router
    Router -->|protected routes| AuthMW
    AuthMW --> Controllers
    Router -->|public routes| Controllers
    Controllers --> Services
    Services --> Utils
    Services -->|Drizzle ORM| DB
    Controllers -->|response| Client
    API -->|logs| Logger

Loading

Request Lifecycle

Every HTTP request passes through a layered middleware pipeline before a response is returned:

sequenceDiagram
    participant C as Client
    participant H as Helmet / CORS
    participant A as Arcjet Security
    participant V as Zod Validation
    participant AM as Auth Middleware
    participant Ctrl as Controller
    participant Svc as Service
    participant DB as PostgreSQL

    C->>H: HTTP Request
    H->>A: Headers sanitized
    A-->>C: 429 Too Many Requests (rate-limited)
    A->>V: Request allowed
    V-->>C: 400 Bad Request (invalid body)
    V->>AM: Body validated
    AM-->>C: 401 Unauthorized (missing/invalid JWT)
    AM-->>C: 403 Forbidden (insufficient role)
    AM->>Ctrl: Token decoded → req.user set
    Ctrl->>Svc: Call service method
    Svc->>DB: Query via Drizzle ORM
    DB-->>Svc: Result
    Svc-->>Ctrl: Processed data
    Ctrl-->>C: JSON Response (2xx / 4xx / 5xx)

Loading

Authentication Flow

Sign-Up

flowchart TD
    A([POST /api/auth/sign-up]) --> B{Body valid?\nZod schema}
    B -- No --> C[400 Bad Request]
    B -- Yes --> D{Email already\nregistered?}
    D -- Yes --> E[409 Conflict]
    D -- No --> F[Hash password\nbcrypt × 10 rounds]
    F --> G[INSERT user row\nDrizzle ORM]
    G --> H[Sign JWT token]
    H --> I[Set HTTP-only cookie]
    I --> J[201 Created + user data]

Loading

Sign-In

flowchart TD
    A([POST /api/auth/sign-in]) --> B{Body valid?\nZod schema}
    B -- No --> C[400 Bad Request]
    B -- Yes --> D[Fetch user by email]
    D --> E{User found?}
    E -- No --> F[401 Unauthorized]
    E -- Yes --> G{Password matches?\nbcrypt.compare}
    G -- No --> F
    G -- Yes --> H[Sign JWT token]
    H --> I[Set HTTP-only cookie]
    I --> J[200 OK + user data]

Loading

Role-Based Access Control

graph LR
    subgraph Roles
        Admin["👑 admin"]
        User["👤 user"]
        Guest["🔓 guest\n(unauthenticated)"]
    end

    subgraph Endpoints
        SignUp["POST /api/auth/sign-up"]
        SignIn["POST /api/auth/sign-in"]
        SignOut["POST /api/auth/sign-out"]
        ListUsers["GET /api/users/"]
        GetUser["GET /api/users/:id"]
        UpdateUser["PUT /api/users/:id"]
        DeleteUser["DELETE /api/users/:id"]
    end

    Guest -->|allowed| SignUp
    Guest -->|allowed| SignIn
    Admin -->|allowed| SignOut
    User  -->|allowed| SignOut
    Admin -->|allowed| ListUsers
    Admin -->|allowed| GetUser
    User  -->|own ID only| GetUser
    Admin -->|allowed| UpdateUser
    User  -->|own ID only| UpdateUser
    Admin -->|allowed| DeleteUser
    User  -->|own ID only| DeleteUser

Loading

Database Schema

The application uses a single users table managed by Drizzle ORM:

erDiagram
    USERS {
        serial      id          PK "Auto-increment primary key"
        varchar255  name            "Full name — not null"
        varchar255  email           "Unique email — not null"
        varchar255  password        "bcrypt hash — not null"
        varchar50   role            "admin | user — default user"
        timestamp   created_at      "Row creation time"
        timestamp   updated_at      "Last update time"
        timestamp   deleted_at      "NULL = active (soft delete)"
    }

Loading

Column	Type	Constraints
id	serial	Primary key
name	varchar(255)	Not null
email	varchar(255)	Not null, unique
password	varchar(255)	Not null (hashed)
role	varchar(50)	Not null, default user
created_at	timestamp	Not null, default now
updated_at	timestamp	Not null, default now
deleted_at	timestamp	Nullable (soft delete)

CI/CD Pipeline

flowchart LR
    Push["git push / PR"] --> T["✅ tests.yml\nJest + Supertest"]
    Push --> L["🔍 lint-and-format.yml\nESLint + Prettier"]
    Push --> D["🐳 docker-build-and-push.yml\nBuild & push image"]

    T -->|pass| Merge["Merge ready"]
    L -->|pass| Merge
    D -->|pass| Merge

Loading

Workflow	Trigger	Description
tests.yml	Push / PR	Runs the test suite
lint-and-format.yml	Push / PR	Checks ESLint and Prettier formatting
docker-build-and-push.yml	Push / PR	Builds and pushes Docker images

Project Structure

acquisition/
├── src/
│   ├── index.js                  # Entry point — starts the server
│   ├── app.js                    # Express app setup (middleware, routes)
│   ├── server.js                 # Alternate entry point (no dotenv)
│   ├── config/
│   │   ├── database.js           # Drizzle + Neon database connection
│   │   ├── logger.js             # Winston logger configuration
│   │   └── arcjet.js             # Arcjet rate limiting configuration
│   ├── models/
│   │   └── user.model.js         # User table schema (Drizzle)
│   ├── controllers/
│   │   ├── auth.controller.js    # Sign-up, sign-in, sign-out handlers
│   │   └── user.controller.js    # User CRUD handlers
│   ├── routes/
│   │   ├── Auth.routes.js        # Authentication routes
│   │   └── user.routes.js        # User management routes
│   ├── services/
│   │   ├── auth.service.js       # Authentication business logic
│   │   └── user.service.js       # User data operations
│   ├── middleware/
│   │   ├── auth.middleware.js    # JWT verification and role checking
│   │   └── security.middleware.js# Security enforcement
│   ├── validations/
│   │   ├── auth.validation.js    # Zod schemas for auth endpoints
│   │   └── users.validation.js   # Zod schemas for user endpoints
│   └── utils/
│       ├── jwt.js                # JWT sign and verify helpers
│       ├── cookies.js            # Cookie set and clear helpers
│       └── format.js             # Validation error formatting
├── test/
│   └── app.test.js               # API integration tests
├── drizzle/                      # Generated database migrations
├── scripts/                      # Docker and deployment scripts
├── Dockerfile                    # Multi-stage production image
├── docker-compose.dev.yml        # Development environment (Neon Local)
├── docker-compose.prod.yml       # Production environment (Neon Cloud)
├── drizzle.config.js             # Drizzle Kit configuration
├── jest.config.mjs               # Jest test configuration
├── eslint.config.js              # ESLint rules
├── .prettierrc                   # Prettier formatting rules
├── DOCKER.md                     # Detailed Docker setup guide
└── package.json                  # Dependencies and npm scripts

Prerequisites

• Node.js v20 or later
• npm
• A Neon PostgreSQL database (or any PostgreSQL instance)
• Docker and Docker Compose (optional, for containerized setup)

Getting Started

1. Clone the repository

git clone https://github.com/Dead-WaRior/acquisition.git
cd acquisition

2. Install dependencies

npm install

3. Configure environment variables

Create a .env file in the project root:

PORT=3000
NODE_ENV=development
LOG_LEVEL=info

DATABASE_URL=postgresql://<user>:<password>@<host>/<database>?sslmode=require
ARCJET_KEY=<your-arcjet-key>
JWT_SECRET=<your-jwt-secret>
CORS_ORIGIN=http://localhost:3000

4. Run database migrations

npm run db:push

5. Start the development server

npm run dev

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

Environment Variables

Variable	Description	Default
PORT	Port the server listens on	3000
NODE_ENV	Environment (development/production)	development
LOG_LEVEL	Winston log level	info
DATABASE_URL	PostgreSQL connection string	—
ARCJET_KEY	Arcjet API key for rate limiting	—
JWT_SECRET	Secret key for signing JWT tokens	—
CORS_ORIGIN	Comma-separated list of allowed origins	— (allow all when empty)

For Docker-specific environment variables, see DOCKER.md.

API Endpoints

Health & Status

Method	Endpoint	Description
GET	/	Welcome message
GET	/health	Health check with uptime
GET	/api	API status

Authentication

Method	Endpoint	Description
POST	/api/auth/sign-up	Register a new user
POST	/api/auth/sign-in	Log in and receive a JWT
POST	/api/auth/sign-out	Log out and clear the token

User Management (Protected)

Method	Endpoint	Access	Description
GET	/api/users/	Admin only	Fetch all users (supports ?page=1&limit=10)
GET	/api/users/:id	Admin or self	Get user by ID
PUT	/api/users/:id	Admin or self	Update user
DELETE	/api/users/:id	Admin or self	Soft-delete user

Protected endpoints require a valid JWT token sent via an HTTP-only cookie or an Authorization: Bearer <token> header.

Scripts

Command	Description
npm run dev	Start the server in watch mode
npm start	Start the server
npm test	Run tests with coverage
npm run lint	Check code with ESLint
npm run lint:fix	Auto-fix ESLint issues
npm run format	Format code with Prettier
npm run format:check	Check code formatting
npm run db:generate	Generate database migrations
npm run db:push	Apply database migrations
npm run db:studio	Open Drizzle Studio (database GUI)
npm run dev:docker	Start development Docker environment
npm run prod:docker	Start production Docker environment

Docker

The project ships with Docker support for both development and production. See DOCKER.md for the full guide.

Quick start (development):

docker compose -f docker-compose.dev.yml up --build

Quick start (production):

docker compose -f docker-compose.prod.yml up --build -d

Testing

Tests are written with Jest and Supertest:

npm test

This runs the test suite and generates a coverage report.

License

This project is licensed under the ISC License.