Developer Setup Guide

Get the full TravelFast stack running on your machine — backend API, admin dashboard, and customer-facing storefront.

Architecture overview

TravelFast is split into four independent packages. Each lives in its own directory at the project root, has its own package.json, and runs independently.

backend/ — Express 5 + Prisma 7 REST API (PostgreSQL). Serves all data, handles auth, file uploads.

dashboard/ — TanStack Router + React 19 admin panel. Connects to backend/ via REST.

storefront/ — Next.js 16 customer-facing travel website. Fetches trips, blogs, pages from backend/.

Prerequisites

✓ Node.js 22+ — verify with node --version
✓ pnpm 10 — corepack enable && corepack prepare pnpm@10 --activate
✓ PostgreSQL 16+ — running locally or via Docker

1. Backend API — backend/

The REST API server. Handles all data persistence, authentication, file uploads, and serves the admin dashboard and storefront.

Install dependencies

cd backend
pnpm install

Configure environment

cp .env.example .env

Edit .env with your values:

NODE_ENV="development"
DATABASE_URL="postgresql://user:password@localhost:5432/travelfast"
JWT_SECRET="your-jwt-secret"
JWT_SECRET_ADMIN="your-admin-jwt-secret"
BCRYPT_SALT_ROUNDS="10"

Optional (email features)

RESEND_API_KEY, VERIFICATION_TOKEN, RESET_LINK — only needed for transactional email (Resend). The API will run without them.

Set up the database

npx prisma migrate dev    # creates tables from Prisma schema
pnpm seed:admin            # creates the admin user
pnpm seed:categories       # seeds trip & blog categories

Or run the full seed:

pnpm seed:full

Start the dev server

pnpm dev

Runs on http://localhost:3000 with hot-reload. API docs at http://localhost:3000/api-docs.

Other commands

Command	What it does
pnpm build	TypeScript compile + path alias resolution
pnpm lint	ESLint check on `src/`
pnpm db:studio	Open Prisma Studio (GUI database browser)
pnpm seed:full	Full data seed (admin, categories, sample trips, etc.)
pnpm test	Run Vitest test suite

Admin credentials

After seeding, log into the dashboard with the admin credentials you set during seed:admin. Check the seed script output for the email and password.

2. Admin Dashboard — dashboard/

The admin panel where staff manage trips, content, media, destinations, and site settings. Built with TanStack Router, React 19, and shadcn/ui.

Install dependencies

cd dashboard
pnpm install

Configure environment

cp .env.example .env

Edit .env:

ENV=development
NEXT_PUBLIC_API_BASE_URL=http://localhost:3000/api/v1
API_PROXY_URL=http://localhost:3000

Dev proxy

The Vite dev server proxies /api/* to http://localhost:3000/api/v1/* and /uploads/* to http://localhost:3000/api/v1/uploads/*. No CORS issues in development.

Start the dev server

pnpm dev

Runs on http://localhost:3001. Visit http://localhost:3001/admin to log in with your seeded admin credentials.

Available routes

Route	What it manages
/dashboard	Analytics overview
/dashboard/trips	Trip CRUD with itineraries
/dashboard/destinations	Destinations & regions
/dashboard/media	Media library
/dashboard/posts	Blog posts
/dashboard/pages	Info pages
/dashboard/inquiries	Customer inquiries
/dashboard/site-config	Site configuration
/dashboard/redirects	URL redirects
/dashboard/team	Team members & departments

Useful commands

Command	What it does
pnpm build	Type-check + Vite production build
pnpm lint	ESLint (typescript-eslint + react-hooks rules)
pnpm typecheck	TypeScript type-check only (`tsc --noEmit`)

3. Storefront — storefront/

The customer-facing travel agency website. Displays trips, blog posts, info pages, and handles bookings. Built with Next.js 16 and Tailwind CSS 4.

Install dependencies

cd storefront
pnpm install

Configure environment

cp .env.example .env    # or create .env manually

No .env.example — create one

The storefront doesn't ship an .env.example yet. Copy this into .env:

NEXT_PUBLIC_API_BASE_URL=http://localhost:3000/api/v1
API_BASE_URL=http://localhost:3000/api/v1

API proxy

In development, Next.js rewrites /api/* to https://api.travelfast.app/api/* (configured in next.config.ts). For local development, change the rewrite target to http://localhost:3000.

Start the dev server

pnpm dev

Runs on http://localhost:3002 (or the first available port after 3000).

Available pages

Route	Description
/	Homepage with featured trips, categories, testimonials
/explore	Trip exploration & search
/package/[slug]	Individual trip / tour detail page
/blogs	Blog listing
/blogs/[slug]	Blog post detail
/[slug]	Dynamic info pages (about, contact, etc.)
/booking	Booking page
/contact	Contact form
/design-your-trip	Custom trip builder
/our-team	Team page

Running everything at once

To run the full stack locally, open three terminal tabs:

Tab 1 — Backend API

cd backend && pnpm dev

Tab 2 — Admin Dashboard

cd dashboard && pnpm dev

Tab 3 — Storefront

cd storefront && pnpm dev

Port map

3000 — Backend API + Scalar API reference

3001 — Admin Dashboard

3002 — Storefront

Environment variables reference

backend/.env

Variable	Required	Description
DATABASE_URL	Yes	PostgreSQL connection string
JWT_SECRET	Yes	Secret for storefront/auth tokens
JWT_SECRET_ADMIN	Yes	Secret for admin dashboard tokens
BCRYPT_SALT_ROUNDS	Yes	Hash rounds for passwords (e.g. 10)
RESEND_API_KEY	No	Resend API key for transactional email
VERIFICATION_TOKEN	No	Secret for email verification links
RESET_LINK	No	Base URL for password reset emails

dashboard/.env

Variable	Required	Description
ENV	Yes	`development` or `production`
NEXT_PUBLIC_API_BASE_URL	Yes	Backend API base URL (e.g. http://localhost:3000/api/v1)
API_PROXY_URL	Yes	Backend origin for Vite proxy (e.g. http://localhost:3000)
NEXT_PUBLIC_WEBSITE_URL	No	Storefront URL for link generation
NEXT_PUBLIC_IMAGE_DOMAIN	No	Image domain for media library
NEXT_PUBLIC_ADMIN_EMAIL	No	Admin email shown in dashboard UI

storefront/.env

Variable	Required	Description
NEXT_PUBLIC_API_BASE_URL	Yes	Backend API base URL for client-side fetches
API_BASE_URL	Yes	Backend API base URL for server-side fetches
NEXT_PUBLIC_FRONTEND_BASE_URL	No	Public base URL for canonical links

How they connect

Storefront (3002)

↓ ↑ REST

Backend API (3000)

↓ ↑ REST

Dashboard (3001)

↑ reads

PostgreSQL

Troubleshooting

Prisma migration fails

Ensure PostgreSQL is running and the DATABASE_URL in .env is correct. Create the database first: createdb travelfast.

pnpm command not found

Enable Corepack: corepack enable && corepack prepare pnpm@10 --activate. Then restart your terminal.

ts-node-dev / tsconfig-paths issues

Make sure you have the right Node version (22+). Delete node_modules and reinstall: rm -rf node_modules && pnpm install.

API docs blank

The spec is generated from src/routes/**/*.ts at startup via fs.globSync. Check that route files have @openapi JSDoc blocks. The UI is rendered by @scalar/express-api-reference.

CORS errors in the browser

The dashboard Vite proxy handles CORS in dev. For the storefront, make sure next.config.ts rewrites point to the right backend URL.

Code conventions

• backend: Each domain has its own directory in src/controllers/ with per-action files and an index.ts re-export. Zod schemas in src/validations/. Path aliases: @/ → src/, @lib/, @config/, @types/, @root/.
• dashboard: shadcn/ui (new-york style), @/* maps to ./src/*. Vercel-inspired design system in DESIGN.md.
• storefront: Wise-inspired design system in DESIGN.md. All API calls via fetch to NEXT_PUBLIC_API_BASE_URL.
• All packages use Tailwind CSS 4 and TypeScript. No monorepo workspace — each package has its own node_modules.