🚀 Local Backend Development - Quick Setup

✅ You're Right - No Need for Railway Every Time!

Your complete environment system is already built! This guide shows you how to use it.

🎯 What You Already Have Built

✅ Three environment presets:

1. Railway (environment.railway.ts) - Production backend
2. Local (environment.local.ts) - Local backend on port 3000
3. Mock (environment.mock.ts) - Offline-first with mock data

✅ Shared configuration (environment.shared.ts):

• Backend URLs (Railway, Local, Mock)
• Storage system config (offline-first, sync settings)
• Sync engine config (intervals, retry logic)

✅ Easy switching: Just copy a preset to environment.ts

✅ New commands (just added):

• yarn serve:backend-api - Start local backend
• yarn dev:full-stack - Run backend + frontend together

📋 Quick Start - Local Backend

Option 1: Full-Stack Command (Easiest):

# 1. Switch to local backend
cd apps/gograb-space/src/environments
cp environment.local.ts environment.ts

# 2. Run both backend + frontend
yarn dev:full-stack

Done! Backend on http://localhost:3000, Frontend on http://localhost:5200

Option 2: Separate Terminals:

# Terminal 1: Backend
yarn serve:backend-api

# Terminal 2: Switch environment
cd apps/gograb-space/src/environments
cp environment.local.ts environment.ts

# Terminal 3: Frontend
yarn serve:gograb-space

🔑 Backend Requirements

Create .env file in apis/backend-api/:

# MongoDB Connection (use same as Railway)
MONGODB_URI=mongodb+srv://username:[email protected]/gograb-dev

# JWT Secret
JWT_SECRET=your-super-secret-key-change-this

# Server Port (default: 3000)
PORT=3000

# Node Environment
NODE_ENV=development

# CORS Origins (allow frontend)
CORS_ORIGINS=http://localhost:5200,http://localhost:4200

🔄 Switching Between Environments

You already have presets built! Just copy them:

Railway Backend (Production Testing):

cp apps/gograb-space/src/environments/environment.railway.ts \
   apps/gograb-space/src/environments/environment.ts
yarn serve:gograb-space

Local Backend (Fast Development):

cp apps/gograb-space/src/environments/environment.local.ts \
   apps/gograb-space/src/environments/environment.ts
yarn serve:backend-api  # If not already running
yarn serve:gograb-space

Mock API (Offline Development):

cp apps/gograb-space/src/environments/environment.mock.ts \
   apps/gograb-space/src/environments/environment.ts
yarn serve:gograb-space  # No backend needed!

✅ Verify Current Environment

Check console logs when app starts:

// Railway Backend:
🔗 Connected to Backend API: https://backend-api-production-97c0.up.railway.app/api

// Local Backend:
🔗 Connected to Backend API: http://localhost:3000/api  ✅ LOCAL

// Mock API:
🎭 Using Mock-API (Offline Mode)

🎯 Benefits of Your System

✅ Already built - No new setup needed
✅ DRY - Shared config defined once in environment.shared.ts
✅ Easy switching - Just copy a preset file
✅ Type-safe - TypeScript ensures correctness
✅ Documented - Each preset has clear comments

🐛 Troubleshooting

Backend won't start:

# Check if port 3000 is in use
lsof -ti:3000 | xargs kill -9

# Rebuild backend
nx build backend-api --skip-nx-cache
yarn serve:backend-api

Frontend still uses old environment:

# Verify you copied the right file
cat apps/gograb-space/src/environments/environment.ts | grep backendApiUrl

# Should show one of:
# - BACKEND_URLS.railway  (Railway)
# - BACKEND_URLS.local    (Local)
# - BACKEND_URLS.mock     (Mock)

# Restart frontend
yarn serve:gograb-space

500 Error persists:

# Check backend logs in the terminal where you ran:
yarn serve:backend-api

# Look for error details and stack traces
# Our enhanced logging shows:
# - HTTP status
# - Error message
# - Full stack trace
# - Request data size

📚 See Also

• Environment README: apps/gograb-space/src/environments/README.md
• Shared Config: apps/gograb-space/src/environments/environment.shared.ts
• Presets:
  • environment.railway.ts
  • environment.local.ts
  • environment.mock.ts

Date: November 18, 2025
Status: ✅ System Already Built - Just Use It!