first commit
This commit is contained in:
431
PROJECT_SUMMARY.md
Normal file
431
PROJECT_SUMMARY.md
Normal file
@@ -0,0 +1,431 @@
|
||||
# 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
|
||||
|
||||
```javascript
|
||||
{
|
||||
// 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
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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:**
|
||||
```env
|
||||
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
|
||||
```javascript
|
||||
const ws = new WebSocket('ws://localhost:3000/ws?token=ACCESS_TOKEN');
|
||||
```
|
||||
|
||||
### Broadcasting (Server-Side)
|
||||
```javascript
|
||||
// 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
|
||||
```javascript
|
||||
// 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
|
||||
```bash
|
||||
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.
|
||||
Reference in New Issue
Block a user