# INSTRUCTIONS.md — Local Development Guide

## Prerequisites

- Node.js 20+
- npm 10+
- Docker + Docker Compose (for containerized runs)

---

## Local Development (No Docker)

### 1. Server

```bash
cd server
cp .env.example .env        # edit DATABASE_URL and JWT_SECRET
npm install
npx prisma migrate dev      # creates SQLite DB and runs migrations
npm run db:seed             # seeds demo vendor + admin user
npm run dev                 # starts API on :8080 with hot-reload
```

Default demo credentials: `admin@demo.com` / `password123`

### 2. Client

```bash
cd client
npm install
npm run dev                 # starts Vite dev server on :5173
```

The Vite dev server proxies `/api` to `http://localhost:8080`.
Open `http://localhost:5173` in your browser.

---

## Docker (Single Container + SQLite)

```bash
docker build -t vendor-pos:latest .
docker run --rm -p 8080:8080 \
  -e NODE_ENV=production \
  -e PORT=8080 \
  -e DATABASE_URL=file:/data/pos.db \
  -e JWT_SECRET=change-me \
  -v pos_data:/data \
  vendor-pos:latest
```

Admin UI: `http://localhost:8080`
API: `http://localhost:8080/api/v1`

---

## Docker Compose (App + PostgreSQL)

```bash
cp .env.example .env        # set JWT_SECRET
docker compose up --build
```

App: `http://localhost:8080`

---

## API Overview

All endpoints live under `/api/v1`.

| Method | Path                        | Auth     | Description              |
|--------|-----------------------------|----------|--------------------------|
| GET    | /health                     | None     | Health check             |
| POST   | /auth/login                 | None     | Obtain tokens            |
| POST   | /auth/refresh               | None     | Rotate refresh token     |
| POST   | /auth/logout                | Bearer   | Invalidate tokens        |
| GET    | /auth/me                    | Bearer   | Current user info        |

---

## Environment Variables

| Variable       | Required | Default       | Description                            |
|----------------|----------|---------------|----------------------------------------|
| PORT           | No       | 8080          | HTTP port                              |
| NODE_ENV       | No       | development   | `development` or `production`          |
| DATABASE_URL   | Yes      | —             | Prisma connection string               |
| JWT_SECRET     | Yes      | —             | Secret for signing JWT tokens          |
| LOG_LEVEL      | No       | info          | Logging verbosity                      |
| CORS_ORIGIN    | No       | *             | Allowed CORS origin                    |

For SQLite: `DATABASE_URL=file:./dev.db`
For Postgres: `DATABASE_URL=postgresql://user:pass@host:5432/db`

---

## Database Migrations

```bash
# Create a new migration (dev only)
cd server && npx prisma migrate dev --name <migration-name>

# Apply pending migrations (production)
cd server && npx prisma migrate deploy

# Open Prisma Studio (GUI)
cd server && npx prisma studio
```