Assist_Design/apps/bff/prisma/README.md

# Prisma Configuration

## Overview

This directory contains the Prisma schema and migrations for the BFF application.

## Important: Docker Build Behavior

### Canonical schema path

Prisma embeds the schema path into the generated client. We regenerate the client in Docker using the production layout so the embedded path is `/app/prisma/schema.prisma`.

## Directory Structure

### Development (Monorepo)

```
/project-root/
├── apps/bff/
│   ├── prisma/
│   │   ├── schema.prisma    ← Schema here
│   │   └── migrations/
│   └── src/
└── packages/
```

### Production (Docker Container)

```
/app/
├── prisma/
│   ├── schema.prisma        ← Schema here (flattened)
│   └── migrations/
├── dist/
└── node_modules/
    └── .prisma/client/      ← Generated client
```

## Commands

| Command            | Description                                                |
| ------------------ | ---------------------------------------------------------- |
| `pnpm db:generate` | Regenerate Prisma client (`--schema=prisma/schema.prisma`) |
| `pnpm db:migrate`  | Run migrations (dev) with explicit schema path             |
| `pnpm db:studio`   | Open Prisma Studio with explicit schema path               |
| `pnpm db:reset`    | Reset database with explicit schema path                   |

## Binary Targets

The schema includes binary targets for both development and production:

```prisma
binaryTargets = ["native", "linux-musl-openssl-3.0.x"]
```

- `native`: For local development (macOS, Windows, Linux)
- `linux-musl-openssl-3.0.x`: For Alpine Linux in Docker

## Troubleshooting

### "Could not load schema from path" Error

This error occurs when the Prisma client was generated with a different schema path than what exists in the current environment.

**Solution**: Ensure the Dockerfile regenerates the Prisma client from the production-like directory structure (see above).

### Client Not Found

If you see "Prisma Client not found" errors:

1. Run `pnpm db:generate` locally
2. For Docker, ensure the Dockerfile includes the `prisma generate` step

## Migration Strategy

1. Create migrations locally: `pnpm db:migrate`
2. Commit the migration files
3. In production, the entrypoint runs: `prisma migrate deploy --schema=/app/prisma/schema.prisma`