# 🚀 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**

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

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

```bash
# 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:**
```bash
curl http://localhost:3000/health
```

### 2. **Login to get JWT token:**
```bash
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:**
```bash
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:

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

```bash
# 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!** 🚀