TurboTrades/QUICK_REFERENCE.md

TurboTrades Quick Reference Card

🚀 Quick Start (30 seconds)

npm install                              # Install dependencies
# Edit .env - add your STEAM_API_KEY
mongod                                   # Start MongoDB
npm run dev                              # Start server

Test it: Open http://localhost:3000/health

---

📁 Project Structure (At a Glance)

TurboTrades/
├── index.js              ⭐ Main entry point
├── config/               🔧 Configuration
├── middleware/           🛡️ Authentication
├── models/               📊 Database schemas
├── routes/               🛤️ API endpoints
└── utils/                🔨 Helpers (JWT, WebSocket)

---

🔌 Essential API Endpoints

Endpoint	Method	Auth	Description
/health	GET	❌	Health check
/auth/steam	GET	❌	Login with Steam
/auth/me	GET	✅	Get current user
/auth/refresh	POST	🔄	Refresh token
/auth/logout	POST	✅	Logout
/user/profile	GET	✅	User profile
/user/trade-url	PATCH	✅	Update trade URL
/ws	WS	Optional	WebSocket

---

🔑 Environment Variables (Required)

MONGODB_URI=mongodb://localhost:27017/turbotrades
STEAM_API_KEY=YOUR_STEAM_API_KEY_HERE
SESSION_SECRET=random-string
JWT_ACCESS_SECRET=random-string
JWT_REFRESH_SECRET=random-string

Generate secrets:

node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

---

📡 WebSocket Usage

Client Connection

const ws = new WebSocket('ws://localhost:3000/ws?token=YOUR_TOKEN');

ws.onmessage = (e) => {
  const msg = JSON.parse(e.data);
  console.log(msg);
};

Server Broadcasting

import { wsManager } from './utils/websocket.js';

// Broadcast to all
wsManager.broadcastPublic('price_update', { price: 99 });

// Send to specific user (by Steam ID)
wsManager.sendToUser(steamId, { type: 'notification', data: {...} });

---

🛡️ Using Middleware

import { authenticate, requireStaffLevel } from './middleware/auth.js';

// Require authentication
fastify.get('/protected', {
  preHandler: authenticate
}, handler);

// Require staff level
fastify.post('/admin', {
  preHandler: [authenticate, requireStaffLevel(3)]
}, handler);

---

🗄️ Database Quick Reference

// Import model
import User from './models/User.js';

// Find user
const user = await User.findOne({ steamId: '123' });

// Update user
user.balance += 100;
await user.save();

// Create user
const newUser = new User({ username: 'Player' });
await newUser.save();

---

🔧 Common Commands

# Development
npm run dev              # Auto-reload on changes
npm start                # Production mode

# MongoDB
mongod                   # Start MongoDB
mongosh                  # MongoDB shell
use turbotrades          # Select database
db.users.find()          # View users

# Testing
curl http://localhost:3000/health
open test-client.html    # WebSocket tester

# PM2 (Production)
pm2 start index.js --name turbotrades
pm2 logs turbotrades
pm2 restart turbotrades

---

🎯 Adding Features

New Route

// routes/myroute.js
export default async function myRoutes(fastify, options) {
  fastify.get('/my-endpoint', {
    preHandler: authenticate
  }, async (request, reply) => {
    return { success: true };
  });
}

// index.js
import myRoutes from './routes/myroute.js';
await fastify.register(myRoutes);

New Model

// models/Listing.js
import mongoose from 'mongoose';

const ListingSchema = new mongoose.Schema({
  itemName: String,
  price: Number,
  seller: { type: mongoose.Schema.Types.ObjectId, ref: 'User' }
}, { timestamps: true });

export default mongoose.model('Listing', ListingSchema);

---

🔒 JWT Token Flow

1. Login → Steam OAuth → Generate JWT
2. Store in httpOnly cookie (secure)
3. Client sends cookie with requests
4. Server verifies JWT
5. Token expires → Use refresh token
6. Logout → Clear cookies

Token Lifetimes:

• Access Token: 15 minutes
• Refresh Token: 7 days

---

🐛 Debugging

# Check if server is running
curl http://localhost:3000/health

# Check MongoDB connection
mongosh --eval "db.version()"

# Check port usage
lsof -i :3000          # Mac/Linux
netstat -ano | find "3000"  # Windows

# View logs
npm run dev            # Shows all logs
pm2 logs turbotrades   # PM2 logs

---

📚 Documentation Files

• README.md → Complete documentation
• QUICKSTART.md → 5-minute setup
• WEBSOCKET_GUIDE.md → WebSocket details
• ARCHITECTURE.md → System design
• STRUCTURE.md → File organization
• COMMANDS.md → Full command list
• THIS FILE → Quick reference

---

⚡ Performance Tips

✅ Add database indexes ✅ Enable Redis for sessions ✅ Use MongoDB Atlas (production) ✅ Enable PM2 cluster mode ✅ Add CDN for static assets ✅ Use connection pooling

---

🔐 Security Checklist

✅ HTTPS/WSS in production
✅ Strong JWT secrets
✅ COOKIE_SECURE=true
✅ Rate limiting enabled
✅ Input validation
✅ MongoDB authentication
✅ Regular security updates
✅ Environment variables secured

---

🆘 Common Issues

Port in use?

lsof -i :3000
kill -9 <PID>

MongoDB won't start?

mongod --dbpath ~/data/db

Module not found?

rm -rf node_modules package-lock.json
npm install

Steam auth fails? Check STEAM_API_KEY in .env

---

📞 Getting Help

1. Check README.md for detailed docs
2. Review example in routes/marketplace.example.js
3. Test WebSocket with test-client.html
4. Check error logs in terminal

---

⭐ Remember: All imports use .js extension (ES modules)

🚀 Ready to build! Check QUICKSTART.md for step-by-step setup.