retail-nest/claude.md

# NestJS Retail POS Backend API Expert Guidelines

## 🎯 Backend Overview
A robust NestJS-based REST API backend for the Retail POS Flutter application, providing product management, category organization, transaction processing, and user authentication with offline-sync capabilities.

---

## 🤖 SUBAGENT DELEGATION SYSTEM 🤖
**CRITICAL: BE PROACTIVE WITH SUBAGENTS! YOU HAVE SPECIALIZED EXPERTS AVAILABLE!**

### 🚨 DELEGATION MINDSET
**Instead of thinking "I'll handle this myself"** **Think: "Which specialist is BEST suited for this task?"**

### 📋 AVAILABLE SPECIALISTS
You have access to these expert subagents - USE THEM PROACTIVELY:

#### 🌐 **nestjs-api-expert**
- **MUST BE USED for**: Controllers, DTOs, REST endpoints, request/response handling, validation
- **Triggers**: "API endpoint", "controller", "DTO", "validation", "REST", "route"

#### 🗄️ **nestjs-database-expert**
- **MUST BE USED for**: TypeORM entities, database schema, migrations, queries, relationships
- **Triggers**: "database", "entity", "migration", "query", "TypeORM", "Prisma", "PostgreSQL"

#### 🏗️ **nestjs-architecture-expert**
- **MUST BE USED for**: Module structure, dependency injection, services, clean architecture
- **Triggers**: "architecture", "module", "service", "dependency injection", "structure"

#### 🔐 **nestjs-auth-expert**
- **MUST BE USED for**: JWT authentication, guards, security, authorization, user management
- **Triggers**: "auth", "JWT", "guard", "security", "login", "authentication"

#### ⚡ **nestjs-performance-expert**
- **MUST BE USED for**: Caching, query optimization, rate limiting, performance tuning
- **Triggers**: "performance", "cache", "Redis", "optimization", "slow", "rate limit"

### 🎯 DELEGATION STRATEGY
**BEFORE starting ANY task, ASK YOURSELF:**
1. "Which of my specialists could handle this better?"
2. "Should I break this into parts for different specialists?"
3. "Would a specialist complete this faster and better?"

### 💼 WORK BALANCE RECOMMENDATION:
- **Simple Tasks (20%)**: Handle independently - quick fixes, minor updates
- **Complex Tasks (80%)**: Delegate to specialists for expert-level results

### 🔧 HOW TO DELEGATE
```
# Explicit delegation examples:
> Use the nestjs-api-expert to create the products CRUD endpoints
> Have the nestjs-database-expert design the transaction entity relationships
> Ask the nestjs-architecture-expert to structure the sync module
> Use the nestjs-auth-expert to implement JWT authentication
> Have the nestjs-performance-expert optimize product queries with caching
```

---

## NestJS Best Practices
- Use TypeScript with strict mode enabled
- Implement modular architecture with feature-based organization
- Follow dependency injection patterns with NestJS IoC
- Use DTOs with class-validator for request validation
- Implement proper error handling with exception filters
- Use TypeORM for database operations
- Follow RESTful API design principles
- Implement comprehensive API documentation with Swagger
- Use environment variables for configuration
- Write unit and e2e tests for all endpoints

## Project Structure

```
src/
  common/
    decorators/
      current-user.decorator.ts
      roles.decorator.ts
      public.decorator.ts
    dto/
      pagination.dto.ts
      api-response.dto.ts
    filters/
      http-exception.filter.ts
      all-exceptions.filter.ts
    guards/
      jwt-auth.guard.ts
      roles.guard.ts
    interceptors/
      logging.interceptor.ts
      transform.interceptor.ts
      cache.interceptor.ts
    pipes/
      validation.pipe.ts
    interfaces/
      pagination.interface.ts
    utils/
      helpers.ts
      formatters.ts
      
  config/
    app.config.ts
    database.config.ts
    jwt.config.ts
    redis.config.ts
    
  database/
    migrations/
      1234567890-CreateProductsTable.ts
      1234567891-CreateCategoriesTable.ts
      1234567892-CreateTransactionsTable.ts
    seeds/
      categories.seed.ts
      products.seed.ts
    data-source.ts
    
  modules/
    products/
      dto/
        create-product.dto.ts
        update-product.dto.ts
        get-products.dto.ts
        product-response.dto.ts
      entities/
        product.entity.ts
      products.controller.ts
      products.service.ts
      products.repository.ts
      products.module.ts
      
    categories/
      dto/
        create-category.dto.ts
        update-category.dto.ts
        category-response.dto.ts
      entities/
        category.entity.ts
      categories.controller.ts
      categories.service.ts
      categories.repository.ts
      categories.module.ts
      
    transactions/
      dto/
        create-transaction.dto.ts
        get-transactions.dto.ts
        transaction-response.dto.ts
      entities/
        transaction.entity.ts
        transaction-item.entity.ts
      transactions.controller.ts
      transactions.service.ts
      transactions.repository.ts
      transactions.module.ts
      
    auth/
      dto/
        login.dto.ts
        register.dto.ts
      strategies/
        jwt.strategy.ts
        local.strategy.ts
      guards/
        jwt-auth.guard.ts
        local-auth.guard.ts
      auth.controller.ts
      auth.service.ts
      auth.module.ts
      
    users/
      dto/
        create-user.dto.ts
        update-user.dto.ts
      entities/
        user.entity.ts
      users.controller.ts
      users.service.ts
      users.repository.ts
      users.module.ts
      
    sync/
      dto/
        sync-request.dto.ts
        sync-response.dto.ts
      sync.controller.ts
      sync.service.ts
      sync.module.ts
      
  app.module.ts
  main.ts
  
test/
  unit/
    products/
      products.service.spec.ts
      products.controller.spec.ts
    categories/
    transactions/
  e2e/
    products.e2e-spec.ts
    categories.e2e-spec.ts
    auth.e2e-spec.ts
    
.env
.env.example
package.json
tsconfig.json
ormconfig.json
docker-compose.yml
```

---

# Backend Context - Retail POS API

## About This Backend
A comprehensive NestJS REST API backend that powers the Flutter Retail POS mobile application. Provides robust endpoints for product management, category organization, transaction processing, and user authentication, with offline-sync capabilities and real-time data synchronization.

## Target Users
- **Flutter Mobile App**: Primary consumer of the API
- **Admin Dashboard**: Future web-based management interface (optional)
- **Third-party Integrations**: Payment gateways, inventory systems

## Core Features

### 📦 Product Management
**Endpoints**:
- `GET /api/products` - List all products with pagination and filtering
- `GET /api/products/:id` - Get single product details
- `POST /api/products` - Create new product
- `PUT /api/products/:id` - Update product
- `DELETE /api/products/:id` - Delete product
- `GET /api/products/category/:categoryId` - Products by category
- `GET /api/products/search` - Search products

**Features**:
- Full CRUD operations
- Advanced filtering (category, price range, availability)
- Search by name and description
- Stock management
- Image URL storage
- Pagination and sorting
- Soft delete support (optional)

**Business Logic**:
- Validate category exists before creating product
- Check stock availability
- Update product count in category
- Track inventory changes

### 📁 Category Management
**Endpoints**:
- `GET /api/categories` - List all categories
- `GET /api/categories/:id` - Get single category
- `POST /api/categories` - Create new category
- `PUT /api/categories/:id` - Update category
- `DELETE /api/categories/:id` - Delete category
- `GET /api/categories/:id/products` - Products in category

**Features**:
- CRUD operations
- Product count tracking
- Icon/image support
- Color coding
- Cascade delete (optional)

**Business Logic**:
- Prevent deletion if category has products (or cascade)
- Update product count when products added/removed
- Unique category names

### 💰 Transaction Management
**Endpoints**:
- `GET /api/transactions` - List transactions with pagination
- `GET /api/transactions/:id` - Get transaction details
- `POST /api/transactions` - Create new transaction
- `GET /api/transactions/stats` - Transaction statistics
- `GET /api/transactions/daily` - Daily sales report

**Features**:
- Complete transaction logging
- Transaction items tracking
- Subtotal, tax, discount calculation
- Payment method tracking
- Transaction history
- Sales reporting

**Business Logic**:
- Validate stock availability
- Update product stock on transaction
- Calculate totals automatically
- Atomic transaction creation (all or nothing)
- Track product at transaction time (price snapshot)

### 🔐 Authentication & Authorization
**Endpoints**:
- `POST /api/auth/register` - Register new user
- `POST /api/auth/login` - Login user
- `GET /api/auth/profile` - Get current user profile
- `POST /api/auth/refresh` - Refresh access token

**Features**:
- JWT-based authentication
- Password hashing with bcrypt
- Role-based access control (RBAC)
- Token refresh mechanism
- Secure password policies

**Roles**:
- **Admin**: Full access to all endpoints
- **Manager**: Product and category management
- **Cashier**: Transaction processing only
- **User**: Read-only access (optional)

### 🔄 Sync Management
**Endpoints**:
- `POST /api/sync/products` - Sync products to mobile
- `POST /api/sync/categories` - Sync categories to mobile
- `GET /api/sync/status` - Get last sync status
- `GET /api/sync/changes` - Get changes since last sync

**Features**:
- Incremental sync support
- Last modified timestamp tracking
- Change detection
- Bulk data transfer
- Sync conflict resolution

## Technical Stack

### Core Technologies
- **Framework**: NestJS 10.x
- **Language**: TypeScript 5.x
- **Database**: PostgreSQL 15.x
- **ORM**: TypeORM 0.3.x (or Prisma as alternative)
- **Cache**: Redis 7.x
- **Authentication**: JWT (jsonwebtoken)
- **Validation**: class-validator, class-transformer
- **Documentation**: Swagger/OpenAPI

### Key Dependencies
```json
{
  "dependencies": {
    "@nestjs/common": "^10.0.0",
    "@nestjs/core": "^10.0.0",
    "@nestjs/platform-express": "^10.0.0",
    "@nestjs/typeorm": "^10.0.0",
    "@nestjs/jwt": "^10.0.0",
    "@nestjs/passport": "^10.0.0",
    "@nestjs/swagger": "^7.0.0",
    "@nestjs/config": "^3.0.0",
    "@nestjs/cache-manager": "^2.0.0",
    "@nestjs/throttler": "^5.0.0",
    "typeorm": "^0.3.17",
    "pg": "^8.11.0",
    "bcrypt": "^5.1.0",
    "passport-jwt": "^4.0.1",
    "class-validator": "^0.14.0",
    "class-transformer": "^0.5.1",
    "cache-manager": "^5.2.0",
    "cache-manager-redis-store": "^3.0.0"
  }
}
```

## Database Schema

### Products Table
```sql
CREATE TABLE products (
  id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
  name VARCHAR(255) NOT NULL,
  description TEXT,
  price DECIMAL(10, 2) NOT NULL,
  image_url VARCHAR(500),
  category_id UUID REFERENCES categories(id) ON DELETE CASCADE,
  stock_quantity INTEGER DEFAULT 0,
  is_available BOOLEAN DEFAULT true,
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  
  INDEX idx_products_name (name),
  INDEX idx_products_category (category_id),
  INDEX idx_products_name_category (name, category_id)
);
```

### Categories Table
```sql
CREATE TABLE categories (
  id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
  name VARCHAR(255) UNIQUE NOT NULL,
  description TEXT,
  icon_path VARCHAR(255),
  color VARCHAR(50),
  product_count INTEGER DEFAULT 0,
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  
  INDEX idx_categories_name (name)
);
```

### Transactions Table
```sql
CREATE TABLE transactions (
  id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
  subtotal DECIMAL(10, 2) NOT NULL,
  tax DECIMAL(10, 2) DEFAULT 0,
  discount DECIMAL(10, 2) DEFAULT 0,
  total DECIMAL(10, 2) NOT NULL,
  payment_method VARCHAR(50) NOT NULL,
  completed_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  
  INDEX idx_transactions_date (completed_at)
);
```

### Transaction Items Table
```sql
CREATE TABLE transaction_items (
  id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
  transaction_id UUID REFERENCES transactions(id) ON DELETE CASCADE,
  product_id UUID REFERENCES products(id),
  product_name VARCHAR(255) NOT NULL,
  price DECIMAL(10, 2) NOT NULL,
  quantity INTEGER NOT NULL,
  line_total DECIMAL(10, 2) NOT NULL,
  
  INDEX idx_transaction_items_transaction (transaction_id),
  INDEX idx_transaction_items_product (product_id)
);
```

### Users Table
```sql
CREATE TABLE users (
  id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
  name VARCHAR(255) NOT NULL,
  email VARCHAR(255) UNIQUE NOT NULL,
  password VARCHAR(255) NOT NULL,
  roles TEXT[] DEFAULT ARRAY['user'],
  is_active BOOLEAN DEFAULT true,
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  
  INDEX idx_users_email (email)
);
```

## API Response Format

### Success Response
```json
{
  "success": true,
  "data": {
    // Response data
  },
  "message": "Operation successful"
}
```

### Paginated Response
```json
{
  "success": true,
  "data": [
    // Array of items
  ],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 100,
    "totalPages": 5
  }
}
```

### Error Response
```json
{
  "success": false,
  "error": {
    "statusCode": 400,
    "message": "Validation failed",
    "details": [
      "name must be a string",
      "price must be a positive number"
    ]
  },
  "timestamp": "2025-01-15T10:30:00.000Z",
  "path": "/api/products"
}
```

## Key API Endpoints

### Products API

#### List Products
```http
GET /api/products?page=1&limit=20&categoryId=uuid&search=laptop&minPrice=100&maxPrice=1000
```

**Response**:
```json
{
  "success": true,
  "data": [
    {
      "id": "uuid",
      "name": "Laptop",
      "description": "Gaming laptop",
      "price": 999.99,
      "imageUrl": "https://...",
      "categoryId": "uuid",
      "stockQuantity": 50,
      "isAvailable": true,
      "category": {
        "id": "uuid",
        "name": "Electronics"
      },
      "createdAt": "2025-01-15T10:00:00.000Z",
      "updatedAt": "2025-01-15T10:00:00.000Z"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 100,
    "totalPages": 5
  }
}
```

#### Create Product
```http
POST /api/products
Content-Type: application/json
Authorization: Bearer <token>

{
  "name": "Laptop",
  "description": "Gaming laptop",
  "price": 999.99,
  "imageUrl": "https://...",
  "categoryId": "uuid",
  "stockQuantity": 50,
  "isAvailable": true
}
```

### Categories API

#### List Categories
```http
GET /api/categories
```

**Response**:
```json
{
  "success": true,
  "data": [
    {
      "id": "uuid",
      "name": "Electronics",
      "description": "Electronic devices",
      "iconPath": "/icons/electronics.png",
      "color": "#FF5722",
      "productCount": 150,
      "createdAt": "2025-01-15T10:00:00.000Z"
    }
  ]
}
```

### Transactions API

#### Create Transaction
```http
POST /api/transactions
Content-Type: application/json
Authorization: Bearer <token>

{
  "items": [
    {
      "productId": "uuid",
      "quantity": 2
    }
  ],
  "paymentMethod": "cash",
  "discount": 10.00
}
```

**Response**:
```json
{
  "success": true,
  "data": {
    "id": "uuid",
    "subtotal": 1999.98,
    "tax": 199.99,
    "discount": 10.00,
    "total": 2189.97,
    "paymentMethod": "cash",
    "items": [
      {
        "id": "uuid",
        "productId": "uuid",
        "productName": "Laptop",
        "price": 999.99,
        "quantity": 2,
        "lineTotal": 1999.98
      }
    ],
    "completedAt": "2025-01-15T10:30:00.000Z"
  }
}
```

### Authentication API

#### Login
```http
POST /api/auth/login
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "Password123!"
}
```

**Response**:
```json
{
  "success": true,
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "user": {
      "id": "uuid",
      "email": "user@example.com",
      "name": "John Doe",
      "roles": ["admin"]
    }
  }
}
```

## Caching Strategy

### Cache Layers
1. **Product List Cache**: 5 minutes TTL
2. **Single Product Cache**: 10 minutes TTL
3. **Category List Cache**: 15 minutes TTL
4. **Transaction Stats Cache**: 1 hour TTL

### Cache Invalidation
- Invalidate on CREATE, UPDATE, DELETE operations
- Smart invalidation: Only clear related caches
- Use cache tags for grouped invalidation

### Redis Configuration
```typescript
{
  host: process.env.REDIS_HOST,
  port: 6379,
  ttl: 300, // Default 5 minutes
  max: 1000 // Max items in cache
}
```

## Performance Optimization

### Database Optimization
- Index frequently queried columns
- Use query builders for complex queries
- Implement connection pooling (max: 20, min: 5)
- Paginate all list endpoints
- Eager load only necessary relations

### API Optimization
- Enable response compression (gzip)
- Implement rate limiting (100 req/min per IP)
- Cache frequently accessed data
- Use streaming for large responses
- Implement query result caching

### Monitoring
- Log all API requests with response times
- Track database query performance
- Monitor cache hit/miss rates
- Alert on slow endpoints (>1s)
- Track error rates

## Security Implementation

### Authentication
- JWT with 1-day expiration
- Refresh tokens with 7-day expiration
- bcrypt password hashing (10 rounds)
- Rate limiting on auth endpoints (5 req/min)

### Authorization
- Role-based access control (RBAC)
- Protected routes with guards
- Public endpoints clearly marked
- Admin-only endpoints separated

### API Security
- CORS enabled with whitelist
- Helmet for security headers
- Input validation on all endpoints
- SQL injection prevention (TypeORM)
- XSS prevention
- HTTPS only in production

### Environment Variables
```bash
# Application
NODE_ENV=development
PORT=3000
API_PREFIX=api

# Database
DB_HOST=localhost
DB_PORT=5432
DB_USERNAME=postgres
DB_PASSWORD=postgres
DB_DATABASE=retail_pos

# JWT
JWT_SECRET=your-super-secret-key-change-in-production
JWT_EXPIRES_IN=1d

# Redis
REDIS_HOST=localhost
REDIS_PORT=6379
CACHE_TTL=300

# CORS
CORS_ORIGIN=http://localhost:3000,capacitor://localhost

# Rate Limiting
THROTTLE_TTL=60
THROTTLE_LIMIT=100
```

## Testing Strategy

### Unit Tests
- Test all service methods
- Test business logic
- Test error handling
- Mock all dependencies
- Aim for 80%+ coverage

### Integration Tests
- Test database operations
- Test repository methods
- Test data transformations

### E2E Tests
- Test complete API flows
- Test authentication flows
- Test CRUD operations
- Test error scenarios
- Test edge cases

### Test Structure
```typescript
describe('ProductsService', () => {
  let service: ProductsService;
  let repository: MockType<ProductsRepository>;

  beforeEach(async () => {
    const module = await Test.createTestingModule({
      providers: [
        ProductsService,
        {
          provide: ProductsRepository,
          useFactory: mockRepository,
        },
      ],
    }).compile();

    service = module.get(ProductsService);
    repository = module.get(ProductsRepository);
  });

  it('should create a product', async () => {
    const dto = { name: 'Test', price: 10 };
    repository.create.mockResolvedValue(dto);
    
    const result = await service.create(dto);
    
    expect(result).toEqual(dto);
    expect(repository.create).toHaveBeenCalledWith(dto);
  });
});
```

## Deployment

### Docker Setup
```dockerfile
FROM node:18-alpine

WORKDIR /app

COPY package*.json ./
RUN npm ci --only=production

COPY . .
RUN npm run build

EXPOSE 3000

CMD ["node", "dist/main"]
```

### Docker Compose
```yaml
version: '3.8'

services:
  api:
    build: .
    ports:
      - "3000:3000"
    environment:
      - NODE_ENV=production
    depends_on:
      - postgres
      - redis

  postgres:
    image: postgres:15-alpine
    environment:
      POSTGRES_DB: retail_pos
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: postgres
    volumes:
      - postgres-data:/var/lib/postgresql/data

  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"

volumes:
  postgres-data:
```

## Development Workflow

### Setup
```bash
# Install dependencies
npm install

# Setup database
npm run migration:run
npm run seed:run

# Start development server
npm run start:dev
```

### Development Commands
```bash
# Run tests
npm run test
npm run test:e2e
npm run test:cov

# Generate migration
npm run migration:generate -- -n MigrationName

# Run migration
npm run migration:run

# Revert migration
npm run migration:revert

# Seed database
npm run seed:run
```

### API Documentation
- **Swagger UI**: http://localhost:3000/api/docs
- **JSON**: http://localhost:3000/api/docs-json

---

## Remember: ALWAYS DELEGATE TO SPECIALISTS FOR BETTER RESULTS!

When working on this NestJS backend:
- **API/Endpoints** → nestjs-api-expert
- **Database/Entities** → nestjs-database-expert
- **Architecture** → nestjs-architecture-expert
- **Auth/Security** → nestjs-auth-expert
- **Performance** → nestjs-performance-expert

**Think delegation first, implementation second!**