A progressive Node.js framework for building efficient and scalable server-side applications.

Description

RedFox API - Backend API for RedFox Point of Sale system built with NestJS, TypeORM, and supporting MySQL/PostgreSQL databases.

Project Setup

$ npm install

Environment Variables

The application requires the following environment variables. Create a .env file in the root directory with the following configuration:

Application Configuration

Variable	Description	Default	Required
NODE_ENV	Environment mode (development/production)	development	No
PORT	Server port	3000	No
HOST	Server host	0.0.0.0	No
CORS_ORIGIN	Allowed CORS origin	*	No
APP_KEY	Application key (used for JWT)	-	Yes
APP_PUBLIC_URL	Public base URL of this API (used to build absolute asset URLs like the company logo). Example: https://your-api.com (no /api)	-	No

Database Configuration

Variable	Description	Default	Required
APP_DB_PROVIDER	Database provider (mysql or postgres)	mysql	No

MySQL Configuration (when APP_DB_PROVIDER=mysql)

Variable	Description	Default	Required
MYSQL_DB_HOST	MySQL host	localhost	No
MYSQL_DB_PORT	MySQL port	3306	No
MYSQL_DB_USER	MySQL username	root	No
MYSQL_DB_PASSWORD	MySQL password	`` (empty)	No
MYSQL_DB_NAME	MySQL database name	redfox-db	No

PostgreSQL Configuration (when APP_DB_PROVIDER=postgres)

Variable	Description	Default	Required
PG_DB_HOST	PostgreSQL host	localhost	No
PG_DB_PORT	PostgreSQL port	5432	No
PG_DB_USER	PostgreSQL username	postgres	No
PG_DB_PASSWORD	PostgreSQL password	postgres	No
PG_DB_NAME	PostgreSQL database name	redfox-db	No

Database Advanced Options

Variable	Description	Default	Required
DB_SYNC	Auto-sync database schema (true/false)	false	No
DB_LOGGING	Enable query logging (true/false)	false	No

Authentication

Variable	Description	Default	Required
APP_KEY	JWT secret key (same as application key)	-	Yes

FacturaAPI Integration

Variable	Description	Default	Required
FACTURAPI_API_KEY	FacturaAPI API key	-	Yes

File Uploads

Variable	Description	Default	Required
UPLOAD_DEST	Upload directory path	./uploads	No

Static files (uploads)

• Uploaded files are served by the API under: /api/uploads/*
• Example (company logo): GET /api/uploads/company/<filename>
• Notes:
  • The storage folder is resolved from the process working directory (typically <redfox-api>/uploads).
  • If you set APP_PUBLIC_URL, the company-settings endpoint will return logoUrl as an absolute URL.

Example .env File

# Application
NODE_ENV=development
PORT=3000
HOST=0.0.0.0
CORS_ORIGIN=*
APP_KEY=your-super-secret-app-key-change-this-in-production

# Database Provider
APP_DB_PROVIDER=mysql

# MySQL Configuration
MYSQL_DB_HOST=localhost
MYSQL_DB_PORT=3306
MYSQL_DB_USER=root
MYSQL_DB_PASSWORD=your_password
MYSQL_DB_NAME=redfox-db

# PostgreSQL Configuration (alternative)
# PG_DB_HOST=localhost
# PG_DB_PORT=5432
# PG_DB_USER=postgres
# PG_DB_PASSWORD=your_password
# PG_DB_NAME=redfox-db

# Database Options
DB_SYNC=false
DB_LOGGING=false

# FacturaAPI
FACTURAPI_API_KEY=sk_test_your_api_key_here

# Uploads
UPLOAD_DEST=./uploads

Compile and Run the Project

# development
$ npm run start

# watch mode
$ npm run start:dev

# production mode
$ npm run start:prod

Database Migrations

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

# Run migrations
$ npm run migration:run

# Revert last migration
$ npm run migration:revert

# Show migration status
$ npm run migration:show

# Drop schema (development only)
$ npm run migration:drop

# Reset DB: drop all tables and run migrations (development only)
$ npm run db:reset

Database Seeds

# Run all seeds
$ npm run seed

# Run permissions seed only
$ npm run seed:permissions

Run Tests

# unit tests
$ npm run test

# e2e tests
$ npm run test:e2e

# test coverage
$ npm run test:cov

API Endpoints

The API is available at http://localhost:3000/api with the following main endpoints:

• /api/health - Health check endpoint
• /api/auth - Authentication endpoints
• /api/company-settings - Company settings (singleton) + logo upload
  • GET /api/company-settings
  • PUT /api/company-settings
  • POST /api/company-settings/logo (multipart/form-data, field: logo)
  • Logo is served at: GET /api/uploads/company/<filename>
• /api/users - User management
• /api/products - Product management
• /api/inventory - Inventory management
• /api/invoices - Invoice management (with FacturaAPI integration)
• /api/sales - Sales management
• /api/warehouses - Warehouse management
• And more...

For detailed API documentation, see INVOICE_API.md for invoice-related endpoints.

Docker Deployment

See DOCKER.md for detailed Docker setup and deployment instructions.

Project Structure

redfox-api/
├── src/
│   ├── config/          # Configuration files (database, app)
│   ├── controllers/     # API controllers
│   ├── services/        # Business logic services
│   ├── models/          # TypeORM entities
│   ├── dtos/            # Data Transfer Objects
│   ├── modules/         # NestJS modules
│   ├── guards/          # Authentication guards
│   ├── decorators/      # Custom decorators
│   ├── db/
│   │   ├── migrations/  # Database migrations
│   │   └── seeds/       # Database seeds
│   └── main.ts          # Application entry point
├── uploads/             # Uploaded files directory
└── package.json

Key Features

• Multi-database support: MySQL and PostgreSQL
• JWT Authentication: Secure token-based authentication
• FacturaAPI Integration: Electronic invoicing (CFDI) support
• Certification pack sync: Clients are synced with the pack on create/update (ClientPackSyncService; pack_client_id / pack_client_response in client). Products are catalog only; sync to the pack runs when applying a reception or when closing a warehouse (aperturas → inventory). Pack data is stored in inventory (pack_product_id, pack_product_response). See Certification pack sync below.
• File Uploads: Image and document upload support
• TypeORM: Database ORM with migrations
• Validation: Class-validator for DTOs
• CORS: Configurable CORS support

Certification pack sync

• Clients: On create/update, ClientPackSyncService syncs the client with the active certification pack (Facturapi). The client entity stores pack_client_id and pack_client_response. Create/update endpoints return { client, pack_sync_success, pack_sync_error? }.
• Products: Products are catalog only (no price in the products table; price comes from inventory via reception or warehouse opening). Sync to the pack runs when:
  • A reception is applied (products are transferred to inventory with price), or
  • A warehouse is closed (warehouse openings are transferred to inventory with price). InventoryPackSyncService builds product data from inventory (product + price), calls Facturapi createProduct / updateProduct, and stores pack_product_id and pack_product_response in the inventory record. Product create/update no longer sync with the pack.

Resources

• NestJS Documentation
• TypeORM Documentation
• FacturaAPI Documentation
• Docker Setup Guide
• Invoice API Documentation

License

This project is private and proprietary.