TurboTrades/PROJECT_SUMMARY.md

TurboTrades Backend - Project Summary

🎯 Project Overview

A production-ready backend API for a Steam/CS2/Rust marketplace built with modern Node.js technologies. This backend provides authentication, real-time communication, and a solid foundation for building a complete marketplace platform.

🏗️ Architecture

Tech Stack

• Framework: Fastify (high-performance Node.js web framework)
• Database: MongoDB with Mongoose ODM
• Authentication:
  • Steam OAuth (passport-steam)
  • JWT (short-lived access tokens + long-lived refresh tokens)
  • httpOnly cookies for CSRF protection
• Real-time: WebSocket with custom user mapping
• Security: Helmet, CORS, Rate Limiting

Project Structure

TurboTrades/
├── models/                      # MongoDB Schemas
│   └── User.js                 # User model with 2FA, email, ban support
│
├── config/                      # Configuration
│   ├── index.js                # Environment config loader
│   ├── database.js             # MongoDB connection handler
│   └── passport.js             # Steam OAuth configuration
│
├── middleware/                  # Custom Middleware
│   └── auth.js                 # JWT verification & authorization
│
├── routes/                      # API Routes
│   ├── auth.js                 # Authentication endpoints
│   ├── user.js                 # User profile management
│   ├── websocket.js            # WebSocket management
│   └── marketplace.example.js  # Example marketplace routes
│
├── utils/                       # Utilities
│   ├── jwt.js                  # Token generation & verification
│   └── websocket.js            # WebSocket manager with user mapping
│
├── index.js                     # Main server entry point
├── .env.example                 # Environment variables template
├── .gitignore                   # Git ignore rules
├── package.json                 # Dependencies & scripts
├── README.md                    # Full documentation
├── QUICKSTART.md                # Quick start guide
├── WEBSOCKET_GUIDE.md           # WebSocket integration guide
└── test-client.html             # WebSocket test client

✨ Key Features

1. Authentication System

Steam OAuth Integration

• Seamless login via Steam
• Automatic user profile creation/update
• Profile syncing (avatar, username, Steam ID)

JWT Token System

• Access tokens (15 min lifetime) for API requests
• Refresh tokens (7 days) for token renewal
• Automatic token refresh flow
• httpOnly cookies for security

Authorization Levels

• Staff level system (0=User, 1=Support, 2=Mod, 3=Admin)
• Email verification support
• 2FA ready (schema prepared)
• Ban system with expiration dates

2. WebSocket System

Advanced Features

• User-to-socket mapping for authenticated users
• Public broadcasting (all clients)
• Authenticated-only broadcasting
• Targeted user messaging
• Heartbeat/ping-pong for connection health
• Automatic dead connection cleanup

Use Cases

• Real-time price updates
• New listing notifications
• Purchase confirmations
• Trade status updates
• Admin announcements
• User-specific notifications

3. User Management

Profile Features

• Steam profile data
• Trade URL management
• Email verification system
• Balance tracking
• 2FA support (ready for implementation)
• Ban/unban with reasons
• Intercom integration
• User statistics

4. Security Features

CSRF Protection

• httpOnly cookies
• SameSite cookie attribute
• Short-lived tokens

Rate Limiting

• Per-IP rate limiting
• Configurable limits
• Redis support ready

Security Headers

• Helmet.js integration
• Content Security Policy
• XSS protection

Input Validation

• Fastify JSON schema validation
• Mongoose schema validation
• Custom validators (email, trade URL)

📊 Database Schema

User Model

{
  // Steam Data
  username: String,
  steamId: String,
  avatar: String,
  account_creation: Number,
  communityvisibilitystate: Number,
  
  // Marketplace Data
  tradeUrl: String,
  balance: Number,
  intercom: String,
  
  // Email System
  email: {
    address: String,
    verified: Boolean,
    emailToken: String
  },
  
  // Security
  ban: {
    banned: Boolean,
    reason: String,
    expires: Date  // null = permanent
  },
  
  // 2FA (Ready for implementation)
  twoFactor: {
    enabled: Boolean,
    qrCode: String,
    secret: String,
    revocationCode: String
  },
  
  // Permissions
  staffLevel: Number,  // 0-3
  
  // Timestamps
  createdAt: Date,
  updatedAt: Date
}

🔌 API Endpoints

Authentication

• GET /auth/steam - Initiate Steam login
• GET /auth/steam/return - OAuth callback
• GET /auth/me - Get current user
• POST /auth/refresh - Refresh tokens
• POST /auth/logout - Logout
• GET /auth/verify - Verify token

User Management

• GET /user/profile - Get user profile
• PATCH /user/trade-url - Update trade URL
• PATCH /user/email - Update email
• GET /user/verify-email/:token - Verify email
• GET /user/balance - Get balance
• GET /user/stats - Get statistics
• PATCH /user/intercom - Update intercom ID
• GET /user/:steamId - Public user profile

WebSocket

• GET /ws - WebSocket connection
• GET /ws/stats - Connection statistics
• POST /ws/broadcast - Broadcast to all (admin)
• POST /ws/send/:userId - Send to user (mod)
• GET /ws/status/:userId - Check online status

System

• GET /health - Health check
• GET / - API information

🚀 Getting Started

Prerequisites

• Node.js 18+
• MongoDB 5.0+
• Steam API Key

Quick Start

# 1. Install dependencies
npm install

# 2. Configure environment
cp .env.example .env
# Edit .env with your settings

# 3. Start MongoDB
mongod

# 4. Start server
npm run dev

Test Connection

# Health check
curl http://localhost:3000/health

# Login via Steam
open http://localhost:3000/auth/steam

# Test WebSocket
open test-client.html

📝 Environment Variables

Required:

MONGODB_URI=mongodb://localhost:27017/turbotrades
STEAM_API_KEY=your-steam-api-key
SESSION_SECRET=random-secret-here
JWT_ACCESS_SECRET=random-secret-here
JWT_REFRESH_SECRET=different-random-secret

Optional: (See .env.example for full list)

• Port, host configuration
• Cookie settings
• CORS origins
• Rate limiting
• Email SMTP settings
• WebSocket options

🔧 Middleware System

authenticate

Requires valid JWT access token. Returns 401 if missing/invalid.

optionalAuthenticate

Attempts authentication but doesn't fail if no token.

requireStaffLevel(level)

Requires minimum staff level (1=Support, 2=Mod, 3=Admin).

requireVerifiedEmail

Requires verified email address.

require2FA

Requires 2FA to be enabled (ready for implementation).

verifyRefreshTokenMiddleware

Verifies refresh token for token renewal.

📡 WebSocket Integration

Connection

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

Broadcasting (Server-Side)

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

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

// Authenticated users only
wsManager.broadcastToAuthenticated({ type: 'announcement', data: {...} });

Client Messages

// Ping/pong keep-alive
ws.send(JSON.stringify({ type: 'ping' }));

🎯 Next Steps / TODO

Immediate

• Implement email service (nodemailer)
• Implement 2FA (speakeasy/otplib)
• Create Item/Listing models
• Create Transaction models

Short-term

• Steam inventory fetching
• Trade offer automation
• Payment integration (Stripe/PayPal)
• Admin dashboard routes
• Search & filtering system

Long-term

• Redis for sessions & rate limiting
• Docker containerization
• Automated tests (Jest/Mocha)
• API documentation (Swagger)
• Analytics & logging service
• Multi-server WebSocket sync
• CDN integration for avatars
• Backup & disaster recovery

📚 Documentation

• README.md - Complete documentation
• QUICKSTART.md - 5-minute setup guide
• WEBSOCKET_GUIDE.md - WebSocket integration guide
• test-client.html - Interactive WebSocket tester
• marketplace.example.js - Example marketplace implementation

🔒 Security Considerations

Production Checklist

• Generate secure random secrets
• Enable HTTPS/WSS
• Set COOKIE_SECURE=true
• Configure proper CORS origins
• Enable rate limiting with Redis
• Set up monitoring & logging
• Configure MongoDB authentication
• Use environment-specific configs
• Enable production error handling
• Set up automated backups

🚀 Deployment

Recommended Stack

• Hosting: DigitalOcean, AWS, Heroku
• Process Manager: PM2
• Reverse Proxy: Nginx
• Database: MongoDB Atlas
• SSL: Let's Encrypt
• Monitoring: PM2 Monitoring, New Relic, DataDog

PM2 Quick Start

npm install -g pm2
pm2 start index.js --name turbotrades
pm2 save
pm2 startup

📈 Performance

Optimizations Included

• Fastify (3x faster than Express)
• Connection pooling for MongoDB
• WebSocket heartbeat for dead connection cleanup
• Rate limiting to prevent abuse
• Efficient JWT verification
• Indexed database queries (via schema)

Scalability Considerations

• Stateless JWT authentication (horizontal scaling ready)
• WebSocket manager can be extended with Redis pub/sub
• MongoDB connection pooling
• Rate limiter ready for Redis backend
• Microservices-ready architecture

🤝 Contributing

Code Style

• ES6+ modules
• Async/await over callbacks
• Descriptive variable names
• Comments for complex logic
• Error handling on all async operations

Git Workflow

1. Create feature branch
2. Make changes
3. Test thoroughly
4. Submit pull request

📄 License

ISC License

🆘 Support & Resources

• Fastify Docs: https://www.fastify.io/docs/latest/
• Mongoose Docs: https://mongoosejs.com/docs/
• Steam Web API: https://developer.valvesoftware.com/wiki/Steam_Web_API
• JWT.io: https://jwt.io/
• WebSocket API: https://developer.mozilla.org/en-US/docs/Web/API/WebSocket

🎉 Credits

Built with modern Node.js best practices, focusing on:

• Security first
• Developer experience
• Production readiness
• Scalability
• Maintainability

---

Ready to build your marketplace! 🚀

For questions or issues, check the documentation or create an issue on GitHub.