retail-nest/QUICK_START.md

🚀 Quick Start Guide - Retail POS Backend

For Local Development (WITHOUT Redis)

✅ You Only Need PostgreSQL!

Redis is completely optional. The application will use in-memory caching if Redis is not available.

---

📋 Prerequisites

• Node.js 18+
• PostgreSQL 15+ (this is required)
• npm or yarn

---

🏃 Quick Start (3 steps)

Step 1: Create PostgreSQL Database

# Make sure PostgreSQL is running, then create the database
createdb retail_pos

# Or using psql
psql postgres -c "CREATE DATABASE retail_pos;"

Step 2: Update .env File

Edit .env and update ONLY these database fields:

DB_HOST=localhost
DB_PORT=5432
DB_USERNAME=your_postgres_username
DB_PASSWORD=your_postgres_password
DB_DATABASE=retail_pos

You can ignore the Redis settings - the app will work fine without it!

Step 3: Start the Application

# Install dependencies (already done)
npm install

# Run database migrations to create tables
npm run migration:run

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

# Start the development server
npm run start:dev

🎉 Done! Your API is now running at http://localhost:3000/api

---

📱 Access Points

Once the server is running:

• API Base URL: http://localhost:3000/api
• Swagger Documentation: http://localhost:3000/api/docs
• Health Check: http://localhost:3000/health

---

🔐 Default Login Credentials

After running npm run seed:run, you'll have these users:

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

---

🧪 Test Your Setup

1. Check if server is running:

curl http://localhost:3000/health

2. Login to get JWT token:

curl -X POST http://localhost:3000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "admin@retailpos.com",
    "password": "Admin123!"
  }'

You'll get a response with an access_token. Copy it!

3. Test an authenticated endpoint:

curl http://localhost:3000/api/auth/profile \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN_HERE"

4. Or just use Swagger UI:

Visit http://localhost:3000/api/docs and test all endpoints interactively!

---

🐳 Docker Option (Includes PostgreSQL)

If you prefer Docker and don't want to install PostgreSQL locally:

# Start only PostgreSQL (without Redis)
docker-compose up -d postgres

# Or start everything (PostgreSQL + Redis)
docker-compose up -d

Then follow steps 2-3 above.

---

❓ Common Issues

"Migration failed"

• Make sure PostgreSQL is running
• Check your database credentials in .env
• Verify the database retail_pos exists

"Cannot connect to database"

• Check if PostgreSQL is running: psql -U postgres -c "SELECT 1;"
• Verify DB_HOST, DB_PORT, DB_USERNAME, DB_PASSWORD in .env

Port 3000 already in use

• Change PORT=3001 in .env file
• Or stop the other service using port 3000

---

🎯 What About Redis?

You don't need it for development!

The app uses in-memory caching by default. Redis only provides:

• ✅ Persistent cache across server restarts
• ✅ Better performance for high-traffic production

To add Redis later (optional):

1. Install Redis: brew install redis (Mac) or apt-get install redis (Linux)
2. Start Redis: redis-server
3. The app will automatically use it (no code changes needed!)

---

📊 Database Commands

# Run migrations (create tables)
npm run migration:run

# Revert last migration
npm run migration:revert

# Seed database with sample data
npm run seed:run

# Generate new migration
npm run migration:generate -- src/database/migrations/MigrationName

# Create empty migration
npm run migration:create -- src/database/migrations/MigrationName

---

🛑 Stop the Server

Press Ctrl + C in the terminal where the server is running.

---

🎉 Next Steps

1. ✅ Test the API using Swagger UI
2. ✅ Connect your Flutter app to http://localhost:3000/api
3. ✅ Read SETUP_COMPLETE.md for detailed documentation
4. ✅ Customize categories and products via the API

Happy coding! 🚀