Backend Quick Start

Get the DoCurious Express server running locally in under five minutes.

STATUS: BUILT

The backend server is fully functional with 130+ endpoints, JWT authentication, and Prisma ORM.

Prerequisites

Tool	Minimum Version	Check
Node.js	20+	node -v
npm	10+	npm -v
PostgreSQL	14+ (17 recommended)	psql --version

Install

cd server
npm install

Environment Setup

Copy the example environment file and edit as needed:

cp .env.example .env

The .env file:

# Database
DATABASE_URL="postgresql://postgres:postgres@localhost:5432/docurious?schema=public"

# Server
PORT=8000
NODE_ENV=development

# JWT
JWT_SECRET="change-me-in-production"
JWT_REFRESH_SECRET="change-me-in-production-refresh"
JWT_ACCESS_EXPIRY="15m"
JWT_REFRESH_EXPIRY="7d"

# CORS — must match your frontend dev server
CORS_ORIGIN="http://localhost:5173"

# Cloudinary (file uploads — optional for local dev)
CLOUDINARY_CLOUD_NAME=""
CLOUDINARY_API_KEY=""
CLOUDINARY_API_SECRET=""

# Stripe (payments — optional for local dev)
STRIPE_SECRET_KEY=""
STRIPE_WEBHOOK_SECRET=""

All variables are validated at startup with Zod (server/src/config/env.ts). The server will exit with clear error messages if required variables are missing.

Variable	Required	Default	Notes
DATABASE_URL	Yes	--	PostgreSQL connection string
PORT	No	8000	Server port
NODE_ENV	No	development	development, production, or test
JWT_SECRET	Yes	--	Access token signing key (min 10 chars)
JWT_REFRESH_SECRET	Yes	--	Refresh token signing key (min 10 chars)
JWT_ACCESS_EXPIRY	No	15m	Access token lifetime
JWT_REFRESH_EXPIRY	No	7d	Refresh token lifetime
CORS_ORIGIN	No	http://localhost:5173	Comma-separated allowed origins
CLOUDINARY_*	No	""	File upload CDN (optional)
STRIPE_*	No	""	Payment processing (optional)

Database Setup

Make sure PostgreSQL is running, then generate the Prisma client and push the schema:

npx prisma generate
npx prisma db push

To seed the database with sample data:

npm run db:seed

To browse the database visually:

npm run db:studio

NPM Scripts

Script	Command	Description
dev	npm run dev	Start dev server with hot-reload (tsx watch)
build	npm run build	Compile TypeScript to dist/
start	npm run start	Run compiled production build
db:generate	npm run db:generate	Regenerate Prisma client
db:push	npm run db:push	Push schema changes to database
db:migrate	npm run db:migrate	Create and run a migration
db:seed	npm run db:seed	Seed database with sample data
db:studio	npm run db:studio	Open Prisma Studio GUI
test	npm run test	Run test suite (Vitest)
test:watch	npm run test:watch	Run tests in watch mode
test:report	npm run test:report	Run tests and save report

Start the Dev Server

npm run dev

The server starts at http://localhost:8000. Verify it's running:

curl http://localhost:8000/api/portal/health

Expected response:

{
  "success": true,
  "data": {
    "status": "ok",
    "timestamp": "2026-02-14T...",
    "version": "0.2.0",
    "database": "docurious_prod"
  }
}

There is also a live HTML dashboard showing all endpoint implementation status at:

http://localhost:8000/api/portal/health/dashboard

Connecting the Frontend

To switch the frontend from mock APIs to the real backend:

1. Edit the root .env file (not server/.env):

VITE_USE_MOCK_API=false
VITE_API_URL=http://localhost:8000/api/portal

2. Start both servers (in separate terminals):

# Terminal 1 — Backend
cd server && npm run dev

# Terminal 2 — Frontend
npm run dev

The frontend's httpClient.ts will route all API calls through the Express server instead of the in-memory mock database.

Next Steps

• Backend Architecture -- understand the server layers and patterns
• Database & Prisma -- explore the schema and dual model system
• API Endpoints -- complete endpoint reference
• Backend Testing -- run and write tests
• API Layer -- how the frontend mock/real API switching works