retail-nest/README.md

# 🛒 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](./QUICK_START.md) for step-by-step setup instructions.**

### Prerequisites
- Node.js 18+
- PostgreSQL 15+
- (Optional) Redis for caching

### Installation

```bash
# 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](./QUICK_START.md)** - Get up and running in 3 steps
- **[Setup Guide](./SETUP_COMPLETE.md)** - Complete setup documentation
- **[Database Guide](./docs/DATABASE_SETUP.md)** - Database schema and migrations
- **[Auth System](./docs/AUTH_SYSTEM.md)** - Authentication & authorization details
- **[API Documentation](http://localhost:3000/api/docs)** - 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

```bash
# 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

```bash
# 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](LICENSE).

---

## 🆘 Support

For issues and questions:
- Check [QUICK_START.md](./QUICK_START.md) for common issues
- Review [docs/](./docs/) for detailed documentation
- Check Swagger UI at http://localhost:3000/api/docs

---

**Built with ❤️ using NestJS**