bugfix: .env.example files updated. some minor changes in jwt strategy to avoid failing when .env files does not contain needed keys.

backend/README.md

@@ -3,7 +3,7 @@
 ## Prerequisites
 
 - **Node.js 20+** and **npm**
-- **PostgreSQL** reachable from your machine (local or remote)
+- **PostgreSQL** reachable from your machine — either installed locally **or** run via Docker (see below)
 
 ## First-time setup
 
@@ -28,9 +28,23 @@
    - `JWT_SECRET` — strong secret for signing tokens  
    Do not commit `.env`.
 
-4. **Database URL for local dev**
+4. **Database for local dev**
 
-   Point `DATABASE_URL` at a database you created in Postgres (create an empty DB first if needed).
+   **Option A — Postgres in Docker (no local install, e.g. Mac)**  
+   From `backend/`, with `.env` present (copy from `.env.example` first):
+
+   - Ensure `DATABASE_URL` uses **`localhost`** as the host (not `postgres`). Match user, password, and DB name to `POSTGRES_USER`, `POSTGRES_PASSWORD`, and `POSTGRES_DB` in the same file.
+
+   ```bash
+   docker compose -f docker-compose.postgres.yml up -d
+   ```
+
+   Wait until Postgres is healthy (`docker compose -f docker-compose.postgres.yml ps`). The container creates the database on first start.
+
+   To stop Postgres (data is kept in the named volume): `docker compose -f docker-compose.postgres.yml down`
+
+   **Option B — Postgres installed on the machine**  
+   Create an empty database, then point `DATABASE_URL` at it.
 
 5. **Generate Prisma Client**
 
@@ -46,12 +60,43 @@
 
    This runs `prisma migrate dev`. Use it during development when the schema changes.
 
-7. **Seed** (optional — sample data / bootstrap)
+7. **Seed** (optional — reference data only)
 
    ```bash
    npm run prisma:seed
    ```
 
+   This **does not** wipe your database. It only upserts lookup data: organization types (`CLINIC`, `LAB`), subscription plans, and tab permissions. Existing users, organizations, memberships, patients, appointments, and links are **left unchanged**.
+
+   To start from an empty database with fresh tables and reference data, see [Reset database (clean slate)](#reset-database-clean-slate) below.
+
+## Reset database (clean slate)
+
+Use this when you want to **delete all application data** (users, organizations, patients, sessions, etc.) and rebuild the schema from migrations, then run the seed.
+
+From `backend/`:
+
+```bash
+npx prisma migrate reset
+```
+
+Prisma will prompt for confirmation, drop the database, re-apply all migrations, and run `prisma/seed.ts` automatically.
+
+**What gets removed:** everything in the database, including organizations and all related rows.
+
+**What the seed adds back:** only reference data (types, plans, permissions) — not demo users or organizations. Register again or use your own test data after a reset.
+
+**Docker Postgres dev:** if you also want to wipe the Docker volume (not only tables), stop the container and remove the volume:
+
+```bash
+docker compose -f docker-compose.postgres.yml down -v
+docker compose -f docker-compose.postgres.yml up -d
+npm run prisma:migrate
+npm run prisma:seed
+```
+
+Do **not** run `migrate reset` against production or shared staging databases.
+
 ## Run (development)
 
 ```bash
@@ -60,7 +105,7 @@ npm run start:dev
 
 API listens on **`http://localhost:3000`** by default (`PORT` in `.env`).
 
-If the frontend runs on another origin (e.g. `http://localhost:3001`), set `CORS_ORIGIN` in `.env` to that URL.
+If the frontend runs on another origin (e.g. `http://localhost:3001`), set `FRONTEND_URL` in `.env` to that URL (CORS and invite links use it).
 
 ## After pulling latest `main`
 
@@ -71,7 +116,7 @@ npm run prisma:generate
 npm run prisma:migrate
 ```
 
-If teammates added migrations, step 4 applies them. Resolve migration conflicts locally before pushing.
+If teammates added migrations, the migrate step above applies them. Resolve migration conflicts locally before pushing.
 
 ## Useful commands
 
@@ -80,9 +125,16 @@ If teammates added migrations, step 4 applies them. Resolve migration conflicts
 | `npm run prisma:generate` | Regenerate client after `schema.prisma` changes |
 | `npm run prisma:migrate` | Dev migrations (`migrate dev`) |
 | `npm run prisma:deploy` | Production-style apply (`migrate deploy`) — e.g. CI/containers |
+| `npm run prisma:seed` | Upsert reference data only (does not clear existing rows) |
+| `npx prisma migrate reset` | Drop DB, re-migrate, run seed — **dev clean slate** |
 | `npm run build` | Compile Nest app |
 | `npm run start:prod` | Run compiled app (`node dist/main`) |
 
 ## Docker
 
-Image build is defined in **`Dockerfile`** at this folder. For full-stack deployment and CI, see the **repository root `README.md`**.
+| File | Purpose |
+|------|--------|
+| **`Dockerfile`** | Production API image |
+| **`docker-compose.postgres.yml`** | Local dev Postgres only (port mapped to host) |
+
+For full-stack deployment and CI, see the **repository root `README.md`**.