🛒 Retail POS Backend API

A comprehensive NestJS REST API backend for the Retail POS Flutter mobile application, providing product management, transaction processing, and offline-sync capabilities.

---

🚀 Quick Start

See QUICK_START.md for step-by-step setup instructions.

Prerequisites

• Node.js 18+
• PostgreSQL 15+
• (Optional) Redis for caching

Installation

# Install dependencies
npm install

# Setup database
createdb retail_pos

# Update .env with your PostgreSQL credentials
# DB_USERNAME, DB_PASSWORD, DB_DATABASE

# Run migrations
npm run migration:run

# Seed sample data (optional)
npm run seed:run

# Start development server
npm run start:dev

Access the API:

• API: http://localhost:3000/api
• Swagger Docs: http://localhost:3000/api/docs

---

📦 Features

• ✅ Authentication: JWT-based auth with role-based access control
• ✅ Products API: CRUD operations with search and filtering
• ✅ Categories API: Category management with product relations
• ✅ Transactions API: POS transaction processing with stock management
• ✅ Sync API: Offline-first mobile sync capabilities
• ✅ User Management: Multi-role user system (Admin, Manager, Cashier)
• ✅ API Documentation: Auto-generated Swagger/OpenAPI docs
• ✅ Docker Support: Production-ready containerization

---

🏗️ Tech Stack

• Framework: NestJS 11
• Language: TypeScript
• Database: PostgreSQL 15 with TypeORM
• Cache: Redis (optional, uses in-memory by default)
• Authentication: JWT with Passport
• Validation: class-validator, class-transformer
• Documentation: Swagger/OpenAPI

---

📚 Documentation

• Quick Start Guide - Get up and running in 3 steps
• Setup Guide - Complete setup documentation
• Database Guide - Database schema and migrations
• Auth System - Authentication & authorization details
• API Documentation - Interactive Swagger UI (when running)

---

🔐 Default Credentials

After running npm run seed:run:

Role	Email	Password
Admin	admin@retailpos.com	Admin123!
Manager	manager@retailpos.com	Manager123!
Cashier	cashier@retailpos.com	Cashier123!

---

📋 Available Scripts

# Development
npm run start:dev          # Start with hot-reload
npm run start:debug        # Start with debugger

# Production
npm run build              # Build for production
npm run start:prod         # Run production build

# Database
npm run migration:run      # Run migrations
npm run migration:revert   # Revert last migration
npm run seed:run           # Seed database

# Testing
npm run test               # Run unit tests
npm run test:e2e           # Run E2E tests
npm run test:cov           # Test coverage

# Code Quality
npm run lint               # Lint code
npm run format             # Format with Prettier

---

🐳 Docker Deployment

# Start all services (PostgreSQL, Redis, API)
docker-compose up -d

# Run migrations
docker-compose exec api npm run migration:run

# View logs
docker-compose logs -f api

---

🛣️ API Endpoints

Authentication

• POST /api/auth/register - Register new user
• POST /api/auth/login - Login user
• GET /api/auth/profile - Get current user (protected)

Products

• GET /api/products - List products (public)
• POST /api/products - Create product (Admin/Manager)
• PUT /api/products/:id - Update product (Admin/Manager)
• DELETE /api/products/:id - Delete product (Admin)

Categories

• GET /api/categories - List categories (public)
• POST /api/categories - Create category (Admin/Manager)
• PUT /api/categories/:id - Update category (Admin/Manager)
• DELETE /api/categories/:id - Delete category (Admin)

Transactions

• GET /api/transactions - List transactions (Cashier+)
• POST /api/transactions - Create transaction (Cashier+)
• GET /api/transactions/stats - Get statistics (Manager+)

Sync

• POST /api/sync - Sync all data for offline mobile (Cashier+)
• GET /api/sync/status - Get sync status (Cashier+)

For full API documentation, visit: http://localhost:3000/api/docs

---

🗂️ Project Structure

retail-nest/
├── src/
│   ├── common/              # Global utilities, guards, interceptors
│   ├── config/              # Configuration modules
│   ├── database/            # Migrations, seeds, data source
│   ├── modules/
│   │   ├── auth/            # Authentication module
│   │   ├── users/           # User management
│   │   ├── products/        # Product API
│   │   ├── categories/      # Category API
│   │   ├── transactions/    # Transaction API
│   │   └── sync/            # Mobile sync API
│   ├── app.module.ts
│   └── main.ts
├── test/                    # Unit & E2E tests
├── docs/                    # Additional documentation
├── .env                     # Environment variables
├── docker-compose.yml       # Docker stack configuration
└── package.json

---

🤝 Contributing

This is a retail POS backend project. Follow these guidelines:

1. Follow NestJS best practices
2. Write tests for new features
3. Update documentation as needed
4. Use conventional commits

---

📝 License

This project is MIT licensed.

---

🆘 Support

For issues and questions:

• Check QUICK_START.md for common issues
• Review docs/ for detailed documentation
• Check Swagger UI at http://localhost:3000/api/docs

---

Built with ❤️ using NestJS