Karta API

REST API backend for Karta — a full-stack Amazon clone built with NestJS, PostgreSQL, and Prisma.

Tech Stack

• Framework: NestJS + Express adapter
• Language: TypeScript
• Database: PostgreSQL (Docker)
• ORM: Prisma 7
• Auth: JWT access + refresh tokens, Argon2 password hashing
• Validation: class-validator, class-transformer
• Security: Helmet, CORS, Rate limiting (@nestjs/throttler)
• Docs: Swagger UI
• Logging: Pino

Getting Started

Prerequisites

• Node.js 20+
• pnpm
• Docker Desktop

Installation

pnpm install

Environment Variables

Create a .env file in the root:

DATABASE_URL="postgresql://karta:karta_secret@localhost:5432/karta"
JWT_ACCESS_SECRET=your_access_secret
JWT_REFRESH_SECRET=your_refresh_secret
JWT_ACCESS_EXPIRES_IN=15m
JWT_REFRESH_EXPIRES_IN=7d
PORT=3000
NODE_ENV=development
FRONTEND_URL=http://localhost:3001

Database Setup

# Start PostgreSQL
docker compose up -d

# Run migrations
pnpm dlx prisma migrate dev

# Generate Prisma client
pnpm dlx prisma generate

Running the App

# Development
pnpm start:dev

# Production
pnpm build
pnpm start:prod

API Documentation

Swagger UI available at http://localhost:3000/api/docs when running locally.

API Endpoints

Auth

Method	Endpoint	Access	Description
POST	/api/auth/register	Public	Register new user
POST	/api/auth/login	Public	Login
POST	/api/auth/refresh	JWT	Refresh tokens
POST	/api/auth/logout	JWT	Logout

Users

Method	Endpoint	Access	Description
GET	/api/users/me	JWT	Get current user
PATCH	/api/users/me	JWT	Update current user
GET	/api/users	Admin	Get all users
DELETE	/api/users/:id	Admin	Delete user

Products

Method	Endpoint	Access	Description
GET	/api/products	Public	Get all products (paginated)
GET	/api/products/:id	Public	Get single product
POST	/api/products	Admin	Create product
PATCH	/api/products/:id	Admin	Update product
DELETE	/api/products/:id	Admin	Soft delete product

Cart

Method	Endpoint	Access	Description
GET	/api/cart	JWT	Get user cart
POST	/api/cart/items	JWT	Add item to cart
PATCH	/api/cart/items/:id	JWT	Update cart item
DELETE	/api/cart/items/:id	JWT	Remove cart item
DELETE	/api/cart	JWT	Clear cart

Orders

Method	Endpoint	Access	Description
POST	/api/orders/checkout	JWT	Create order from cart
GET	/api/orders/my	JWT	Get user orders
GET	/api/orders/:id	JWT	Get single order
PATCH	/api/orders/:id/status	Admin	Update order status

Database Schema

5 tables: users, products, orders, order_items, cart_items

• Soft deletes on products (deletedAt)
• Unique constraint on cart items (userId, productId)
• Prisma transactions for atomic checkout operations
• Price snapshots on order items (priceAtPurchase)

Project Structure

src/
├── auth/           # JWT auth, guards, strategies, decorators
├── cart/           # Cart management
├── common/         # Shared utilities
├── generated/      # Prisma generated client
├── orders/         # Order processing with transactions
├── prisma/         # PrismaService and PrismaModule
├── products/       # Product CRUD with soft deletes
└── users/          # User management