Utopia

The successor to Huayra, built with Next.js App Router to unify frontend and backend — a single npm run dev replaces the dual-server setup.

Named after the Pagani Utopia, the successor to the Huayra.

Tech Stack

Category	Technology
Backend	Next.js 16 App Router
Auth	NextAuth v5
Rate Limiting	@upstash/ratelimit
Frontend Routing	Next.js App Router
State Management	useSession() + Zustand
Build Tool	Next.js built-in

---

Getting Started

1. Install dependencies

npm install

2. Configure environment variables

cp .env.local.example .env.local

Edit .env.local and fill in the required values:

MONGODB_URI=mongodb://localhost:27017/utopia

# Generate with: openssl rand -base64 32
AUTH_SECRET=<your-secret>

# Obtain from https://console.upstash.com/
UPSTASH_REDIS_REST_URL=https://<your-instance>.upstash.io
UPSTASH_REDIS_REST_TOKEN=<your-token>

3. Start the development server

npm run dev

Open http://localhost:3000

---

Scripts

npm run dev      # Development mode with hot reload (http://localhost:3000)
npm run build    # Production build (includes TypeScript type checking)
npm run start    # Start production server (requires build first)
npm run lint     # ESLint

---

Production Deployment (PM2)

1. Configure environment variables

next start does not load .env.local. Copy it to .env.production.local instead:

cp .env.local .env.production.local

Next.js env file loading order in production (highest to lowest priority):

File	Notes
.env.production.local	Local production overrides — do not commit
.env.local	Loaded by next dev / next build only, ignored by next start
.env.production	Production defaults — safe to commit
.env	Shared across all environments — safe to commit

2. Build and start

npm run build
pm2 start process.json

3. Common PM2 commands

pm2 list              # List all processes
pm2 logs utopia       # Stream logs
pm2 restart utopia    # Restart
pm2 stop utopia       # Stop
pm2 delete utopia     # Remove from PM2

4. Auto-start on boot

pm2 save
pm2 startup

---

Project Structure

app/
  (public)/          # Public pages (home, login, register)
  (account)/         # Member pages (requires login)
  (admin)/           # Admin pages
  api/               # API Route Handlers
proxy.ts             # Route protection + Rate Limiting
lib/
  auth.ts            # NextAuth v5 config
  mongodb.ts         # Mongoose connection
  ratelimit.ts       # Upstash Rate Limiting
models/              # Mongoose models
components/          # React components
email-templates/     # Pug email templates
util/                # sendmail / odm-service / workflow / slugify
store/               # Zustand stores
config/              # Centralized environment config