dyolink/backend/README.md

# Dyolink — Backend (NestJS)

## Prerequisites

- **Node.js 20+** and **npm**
- **PostgreSQL** reachable from your machine — either installed locally **or** run via Docker (see below)

## First-time setup

1. **Clone the monorepo** and go to the backend app:

   ```bash
   git clone <repository-url> dyolink
   cd dyolink/backend
   ```

2. **Install dependencies**

   ```bash
   npm install
   ```

3. **Environment**

   Copy `.env.example` to `.env` and set at least:

   - `DATABASE_URL` — PostgreSQL connection string for your dev database
   - `JWT_SECRET` — strong secret for signing tokens  
   Do not commit `.env`.

4. **Database for local dev**

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

   ```bash
   npm run prisma:generate
   ```

6. **Apply migrations** (creates/updates tables to match `prisma/schema.prisma`)

   ```bash
   npm run prisma:migrate
   ```

   This runs `prisma migrate dev`. Use it during development when the schema changes.

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
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 `FRONTEND_URL` in `.env` to that URL (CORS and invite links use it).

## After pulling latest `main`

```bash
git pull
npm install
npm run prisma:generate
npm run prisma:migrate
```

If teammates added migrations, the migrate step above applies them. Resolve migration conflicts locally before pushing.

## Useful commands

| Command | Purpose |
|--------|---------|
| `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

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