Building a REST API with AI — Full-Stack Vibe Coding

I want to build a Notes API. Help me write a PRD.

The API should support:
- User registration and login (email + password)
- JWT-based authentication
- CRUD operations for notes (title, content, tags)
- Notes belong to users — users can only see their own
- Search notes by title or content
- Pagination for list endpoints
- Input validation on all endpoints

Tech stack:
- TypeScript with Express
- PostgreSQL with Prisma ORM
- JWT for auth with bcrypt for passwords
- Vitest for testing
- Zod for input validation

Write the PRD as a markdown document. Include:
- API endpoint list with request/response formats
- Database schema
- Authentication flow
- Error response format

## API Endpoints

### Auth
POST /api/auth/register — Register a new user
POST /api/auth/login — Login and get JWT token
POST /api/auth/refresh — Refresh an expired token

### Notes
GET    /api/notes       — List user's notes (paginated)
GET    /api/notes/:id   — Get a single note
POST   /api/notes       — Create a note
PUT    /api/notes/:id   — Update a note
DELETE /api/notes/:id   — Delete a note
GET    /api/notes/search?q=term — Search notes

## Database Schema

User: id, email (unique), passwordHash, name, createdAt
Note: id, title, content, tags (string array),
      userId (foreign key), createdAt, updatedAt

## Error Format
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Email is required",
    "details": [...]
  }
}

Read the PRD. Scaffold the project structure.

Create:
- package.json with all dependencies
- tsconfig.json (strict mode)
- Prisma schema matching the PRD database design
- Express app with middleware setup (cors, json parsing,
  error handling)
- Route files for auth and notes (empty handlers)
- Zod schemas for all request bodies
- Project structure following the PRD architecture

Do not implement the handlers yet. Just the structure.

notes-api/
├── package.json
├── tsconfig.json
├── prisma/
│   └── schema.prisma
├── src/
│   ├── index.ts              # Express app setup
│   ├── routes/
│   │   ├── auth.ts           # Auth route definitions
│   │   └── notes.ts          # Notes route definitions
│   ├── controllers/
│   │   ├── authController.ts
│   │   └── notesController.ts
│   ├── services/
│   │   ├── authService.ts
│   │   └── notesService.ts
│   ├── middleware/
│   │   ├── auth.ts           # JWT verification
│   │   ├── validate.ts       # Zod validation middleware
│   │   └── errorHandler.ts   # Global error handler
│   ├── schemas/
│   │   ├── auth.ts           # Zod schemas for auth
│   │   └── notes.ts          # Zod schemas for notes
│   ├── lib/
│   │   └── prisma.ts         # Prisma client singleton
│   └── types/
│       └── express.d.ts      # Express type extensions
└── tests/
    ├── setup.ts
    ├── auth.test.ts
    └── notes.test.ts

model User {
  id           String   @id @default(cuid())
  email        String   @unique
  passwordHash String
  name         String
  createdAt    DateTime @default(now())
  deletedAt    DateTime?
  notes        Note[]
}

model Note {
  id        String   @id @default(cuid())
  title     String
  content   String
  tags      String[]
  userId    String
  user      User     @relation(fields: [userId], references: [id])
  createdAt DateTime @default(now())
  updatedAt DateTime @updatedAt
}

Implement the auth service and controller.

authService.ts:
- register: validate email uniqueness, hash password with
  bcrypt (12 rounds), create user, return JWT
- login: find user by email, compare password hash,
  return JWT
- JWT payload: { userId, email }
- JWT expiration: 24 hours
- Use the JWT_SECRET from environment variables

authController.ts:
- register handler: validate with Zod, call service, return
  201 with token
- login handler: validate with Zod, call service, return
  200 with token

middleware/auth.ts:
- Extract Bearer token from Authorization header
- Verify JWT and attach user to request
- Return 401 with clear error message on failure

Important:
- Do NOT store the JWT secret in code
- Do NOT log passwords or tokens
- Use constant-time comparison for passwords (bcrypt
  handles this internally)
- Return generic "Invalid credentials" for both wrong
  email and wrong password (prevent user enumeration)

import bcrypt from 'bcrypt';
import jwt from 'jsonwebtoken';
import { prisma } from '../lib/prisma';

const JWT_SECRET = process.env.JWT_SECRET;
const SALT_ROUNDS = 12;
const TOKEN_EXPIRY = '24h';

if (!JWT_SECRET) {
  throw new Error('JWT_SECRET environment variable is required');
}

export async function register(
  email: string,
  password: string,
  name: string
): Promise<{ token: string; user: { id: string; email: string; name: string } }> {
  const existing = await prisma.user.findUnique({
    where: { email: email.toLowerCase() },
  });

  if (existing) {
    throw new AppError('Email already registered', 409);
  }

  const passwordHash = await bcrypt.hash(password, SALT_ROUNDS);

  const user = await prisma.user.create({
    data: {
      email: email.toLowerCase(),
      passwordHash,
      name,
    },
    select: { id: true, email: true, name: true },
  });

  const token = jwt.sign(
    { userId: user.id, email: user.email },
    JWT_SECRET,
    { expiresIn: TOKEN_EXPIRY }
  );

  return { token, user };
}

export async function login(
  email: string,
  password: string
): Promise<{ token: string; user: { id: string; email: string; name: string } }> {
  const user = await prisma.user.findUnique({
    where: { email: email.toLowerCase(), deletedAt: null },
  });

  if (!user) {
    throw new AppError('Invalid credentials', 401);
  }

  const valid = await bcrypt.compare(password, user.passwordHash);

  if (!valid) {
    throw new AppError('Invalid credentials', 401);
  }

  const token = jwt.sign(
    { userId: user.id, email: user.email },
    JWT_SECRET,
    { expiresIn: TOKEN_EXPIRY }
  );

  return {
    token,
    user: { id: user.id, email: user.email, name: user.name },
  };
}

Implement the notes service and controller.

notesService.ts:
- create: create a note for the authenticated user
- findAll: list notes for a user with pagination
  (page and limit query params, default page=1 limit=20)
- findById: get a single note (verify it belongs to the user)
- update: update title, content, or tags (verify ownership)
- delete: delete a note (verify ownership)
- search: full-text search on title and content

Return pagination metadata: { data, total, page, limit,
totalPages }

notesController.ts:
- Wire up routes to service functions
- Validate all inputs with Zod schemas
- Return appropriate HTTP status codes
  (200, 201, 204, 400, 401, 404)

Set up the database configuration.

Create:
- .env.example with all required environment variables
- Database migration for the initial schema
- Seed script with sample data (2 users, 5 notes each)
- Test database configuration (use a separate test database)

Commands:
- npm run db:migrate — run migrations
- npm run db:seed — seed sample data
- npm run db:reset — reset and re-seed

Write integration tests for the entire API.

Use Vitest with supertest for HTTP testing.
Use a real test database (configured in .env.test).

Test setup:
- Before all: run migrations on test database
- Before each: clean all tables
- After all: disconnect

Auth tests:
- Register with valid data
- Register with duplicate email (409)
- Register with invalid email (400)
- Login with correct credentials
- Login with wrong password (401)
- Login with non-existent email (401)
- Access protected route without token (401)
- Access protected route with expired token (401)

Notes tests (all require auth):
- Create a note
- List notes (check pagination metadata)
- Get a note by ID
- Get another user's note (404, not 403 — prevent
  enumeration)
- Update a note
- Update another user's note (404)
- Delete a note
- Search notes by title
- Search notes by content

$ npm test

 ✓ tests/auth.test.ts (8 tests) 1.2s
 ✓ tests/notes.test.ts (10 tests) 1.8s

 Test Files  2 passed (2)
      Tests  18 passed (18)
   Start at  14:32:15
   Duration  3.2s

Create a Dockerfile and docker-compose.yml for deployment.

Requirements:
- Multi-stage Docker build (build + production stages)
- Production image should be minimal (node:20-alpine)
- docker-compose with: app + PostgreSQL
- Environment variables for configuration
- Health check endpoint at GET /health
- Run database migrations on startup

Also create a simple deployment script for a VPS:
- Pull latest code
- Build Docker image
- Run migrations
- Restart the container with zero downtime

services:
  app:
    build: .
    ports:
      - "3000:3000"
    environment:
      - DATABASE_URL=postgresql://notes:notes@db:5432/notes
      - JWT_SECRET=${JWT_SECRET}
      - NODE_ENV=production
    depends_on:
      db:
        condition: service_healthy

  db:
    image: postgres:16-alpine
    environment:
      - POSTGRES_USER=notes
      - POSTGRES_PASSWORD=notes
      - POSTGRES_DB=notes
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U notes"]
      interval: 5s
      timeout: 5s
      retries: 5

volumes:
  postgres_data: