iDefineHD/TurboTrades
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
b05594fe3d5f074829f27729e73022fe4dbb2254
TurboTrades/ARCHITECTURE.md
iDefineHD 232968de1e first commit
2026-01-10 04:57:43 +00:00

570 lines
43 KiB
Markdown
Raw Blame History

# TurboTrades Architecture
## 🏗️ System Architecture Overview
```
┌─────────────────────────────────────────────────────────────────────────┐
│ CLIENT LAYER │
├─────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌─────────────┐ │
│ │ Browser │ │ Mobile App │ │ Desktop │ │ WebSocket │ │
│ │ (React) │ │ (React │ │ Client │ │ Client │ │
│ │ │ │ Native) │ │ │ │ │ │
│ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ └──────┬──────┘ │
│ │ │ │ │ │
│ └─────────────────┴─────────────────┴─────────────────┘ │
│ │ │
└────────────────────────────────────┼─────────────────────────────────────┘
│
┌────────────────┴────────────────┐
│ HTTPS / WSS (TLS) │
└────────────────┬────────────────┘
│
┌────────────────────────────────────┼─────────────────────────────────────┐
│ API GATEWAY LAYER │
├────────────────────────────────────┼─────────────────────────────────────┤
│ │ │
│ ┌─────────────────────────────────▼──────────────────────────────────┐ │
│ │ NGINX / Reverse Proxy │ │
│ │ ┌────────────────┐ ┌────────────────┐ ┌──────────────────────┐ │ │
│ │ │ Rate Limiting │ │ Load Balancer │ │ SSL Termination │ │ │
│ │ └────────────────┘ └────────────────┘ └──────────────────────┘ │ │
│ └──────────────────────────────┬──────────────────────────────────────┘ │
│ │ │
└──────────────────────────────────┼───────────────────────────────────────┘
│
┌──────────────────────────────────┼───────────────────────────────────────┐
│ FASTIFY SERVER LAYER │
├──────────────────────────────────┼───────────────────────────────────────┤
│ │ │
│ ┌───────────────────────────────▼─────────────────────────────────┐ │
│ │ FASTIFY INSTANCE │ │
│ │ ┌──────────────────────────────────────────────────────────┐ │ │
│ │ │ PLUGINS │ │ │
│ │ │ ┌─────────┐ ┌────────┐ ┌──────┐ ┌────────┐ ┌─────────┐ │ │ │
│ │ │ │ CORS │ │ Helmet │ │Cookie│ │WebSock │ │ Rate │ │ │ │
│ │ │ │ │ │ │ │ │ │ et │ │ Limit │ │ │ │
│ │ │ └─────────┘ └────────┘ └──────┘ └────────┘ └─────────┘ │ │ │
│ │ └──────────────────────────────────────────────────────────┘ │ │
│ │ │ │
│ │ ┌──────────────────────────────────────────────────────────┐ │ │
│ │ │ MIDDLEWARE LAYER │ │ │
│ │ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │ │
│ │ │ │ JWT │ │ Staff │ │ Email │ │ │ │
│ │ │ │ Verification│ │ Level │ │ Verification │ │ │ │
│ │ │ └──────────────┘ └──────────────┘ └──────────────┘ │ │ │
│ │ └──────────────────────────────────────────────────────────┘ │ │
│ │ │ │
│ │ ┌──────────────────────────────────────────────────────────┐ │ │
│ │ │ ROUTE HANDLERS │ │ │
│ │ │ ┌────────┐ ┌────────┐ ┌──────────┐ ┌──────────────┐ │ │ │
│ │ │ │ Auth │ │ User │ │ Market │ │ WebSocket │ │ │ │
│ │ │ │ Routes │ │ Routes │ │ Routes │ │ Routes │ │ │ │
│ │ │ └────────┘ └────────┘ └──────────┘ └──────────────┘ │ │ │
│ │ └──────────────────────────────────────────────────────────┘ │ │
│ └──────────────────────────────────────────────────────────────────┘ │
│ │
│ ┌────────────────────────────────────────────────────────────────────┐ │
│ │ WebSocket Manager │ │
│ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────────────┐ │ │
│ │ │ User Socket │ │ Broadcast │ │ Heartbeat │ │ │
│ │ │ Mapping │ │ System │ │ Manager │ │ │
│ │ └──────────────┘ └──────────────┘ └──────────────────────┘ │ │
│ └────────────────────────────────────────────────────────────────────┘ │
│ │
└───────────────────────────────────────────────────────────────────────────┘
│
┌──────────────┴──────────────┐
│ │
┌───────────────────▼─────────────┐ ┌───────────▼──────────────────┐
│ EXTERNAL SERVICES │ │ DATA LAYER │
├─────────────────────────────────┤ ├──────────────────────────────┤
│ │ │ │
│ ┌────────────────────────────┐ │ │ ┌────────────────────────┐ │
│ │ Steam Web API │ │ │ │ MongoDB │ │
│ │ ┌──────────────────────┐ │ │ │ │ ┌──────────────────┐ │ │
│ │ │ OpenID Auth │ │ │ │ │ │ users │ │ │
│ │ │ Profile Data │ │ │ │ │ │ listings │ │ │
│ │ │ Trade Offers │ │ │ │ │ │ transactions │ │ │
│ │ │ Inventory │ │ │ │ │ └──────────────────┘ │ │
│ │ └──────────────────────┘ │ │ │ └────────────────────────┘ │
│ └────────────────────────────┘ │ │ │
│ │ │ ┌────────────────────────┐ │
│ ┌────────────────────────────┐ │ │ │ Redis (Future) │ │
│ │ Email Service │ │ │ │ ┌──────────────────┐ │ │
│ │ ┌──────────────────────┐ │ │ │ │ │ Sessions │ │ │
│ │ │ SMTP Server │ │ │ │ │ │ Rate Limiting │ │ │
│ │ │ Email Templates │ │ │ │ │ │ Caching │ │ │
│ │ │ Verification Links │ │ │ │ │ └──────────────────┘ │ │
│ │ └──────────────────────┘ │ │ │ └────────────────────────┘ │
│ └────────────────────────────┘ │ │ │
│ │ └──────────────────────────────┘
│ ┌────────────────────────────┐ │
│ │ Payment Providers │ │
│ │ ┌──────────────────────┐ │ │
│ │ │ Stripe │ │ │
│ │ │ PayPal │ │ │
│ │ │ Crypto Payments │ │ │
│ │ └──────────────────────┘ │ │
│ └────────────────────────────┘ │
│ │
└─────────────────────────────────┘
```
## 🔄 Data Flow Diagrams
### Authentication Flow
```
┌──────────┐ ┌───────────────┐
│ Client │ │ Steam OpenID │
└─────┬────┘ └───────┬───────┘
│ │
│ 1. GET /auth/steam │
├────────────────────────────────────────────────►│
│ │
│ 2. Redirect to Steam login │
│◄────────────────────────────────────────────────┤
│ │
│ 3. User authenticates on Steam │
├────────────────────────────────────────────────►│
│ │
│ 4. Redirect with profile data │
│◄────────────────────────────────────────────────┤
│ │
┌─────▼────┐ ┌───────────────┐
│ Fastify │ │ MongoDB │
└─────┬────┘ └───────┬───────┘
│ │
│ 5. Find or create user │
├────────────────────────────────────────────────►│
│ │
│ 6. User document │
│◄────────────────────────────────────────────────┤
│ │
│ 7. Generate JWT tokens │
│ │
│ 8. Set httpOnly cookies │
│ │
┌─────▼────┐
│ Client │
└──────────┘
│
│ 9. Redirect to dashboard with tokens
│
```
### WebSocket Connection Flow
```
┌──────────┐ ┌───────────────┐ ┌───────────────┐
│ Client │ │ WebSocket │ │ MongoDB │
│ │ │ Manager │ │ │
└─────┬────┘ └───────┬───────┘ └───────┬───────┘
│ │ │
│ 1. Connect ws://host/ws │ │
├──────────────────────────────►│ │
│ │ │
│ │ 2. Extract JWT token │
│ │ (cookie or query param) │
│ │ │
│ │ 3. Verify JWT token │
│ │ │
│ │ 4. Get user data │
│ ├─────────────────────────────►│
│ │ │
│ │ 5. User document │
│ │◄─────────────────────────────┤
│ │ │
│ │ 6. Map userId -> socket │
│ │ │
│ 7. Connection confirmed │ │
│◄──────────────────────────────┤ │
│ │ │
│ 8. Send messages │ │
│◄─────────────────────────────►│ │
│ │ │
│ │ 9. Heartbeat ping │
│◄──────────────────────────────┤ │
│ │ │
│ 10. Pong response │ │
├──────────────────────────────►│ │
│ │ │
```
### Marketplace Transaction Flow
```
┌──────────┐ ┌──────────┐ ┌───────────┐ ┌─────────┐ ┌──────────┐
│ Buyer │ │ Fastify │ │ MongoDB │ │ WebSocket│ │ Seller │
└────┬─────┘ └────┬─────┘ └─────┬─────┘ └────┬─────┘ └────┬─────┘
│ │ │ │ │
│ POST purchase │ │ │ │
├──────────────►│ │ │ │
│ │ │ │ │
│ │ Verify listing │ │ │
│ ├────────────────►│ │ │
│ │ │ │ │
│ │ Check balance │ │ │
│ ├────────────────►│ │ │
│ │ │ │ │
│ │ Update balances │ │ │
│ ├────────────────►│ │ │
│ │ │ │ │
│ │ Create tx │ │ │
│ ├────────────────►│ │ │
│ │ │ │ │
│ │ Update listing │ │ │
│ ├────────────────►│ │ │
│ │ │ │ │
│ │ │ Notify seller │ │
│ │ │ ◄──────────────┤─────────────►│
│ │ │ │ │
│ Success │ │ │ │
│◄──────────────┤ │ │ │
│ │ │ │ │
│ │ │ Broadcast sold │ │
│ │ │◄───────────────┤────────────► │
│ │ │ │ (All users)│
│ │ │ │ │
```
## 📦 Component Architecture
### Core Components
```
TurboTrades/
├── config/
│ ├── index.js → Environment configuration loader
│ ├── database.js → MongoDB connection manager
│ └── passport.js → Steam OAuth strategy setup
│
├── middleware/
│ └── auth.js → JWT verification & authorization
│ ├── authenticate()
│ ├── optionalAuthenticate()
│ ├── requireStaffLevel()
│ ├── requireVerifiedEmail()
│ └── require2FA()
│
├── routes/
│ ├── auth.js → Authentication endpoints
│ │ ├── GET /auth/steam
│ │ ├── GET /auth/steam/return
│ │ ├── GET /auth/me
│ │ ├── POST /auth/refresh
│ │ └── POST /auth/logout
│ │
│ ├── user.js → User management endpoints
│ │ ├── GET /user/profile
│ │ ├── PATCH /user/trade-url
│ │ ├── PATCH /user/email
│ │ └── GET /user/:steamId
│ │
│ ├── websocket.js → WebSocket management
│ │ ├── GET /ws
│ │ ├── GET /ws/stats
│ │ └── POST /ws/broadcast
│ │
│ └── marketplace.example.js → Example marketplace routes
│
├── utils/
│ ├── jwt.js → Token generation & verification
│ │ ├── generateAccessToken()
│ │ ├── generateRefreshToken()
│ │ ├── verifyAccessToken()
│ │ └── verifyRefreshToken()
│ │
│ └── websocket.js → WebSocket manager
│ ├── handleConnection()
│ ├── broadcastPublic()
│ ├── broadcastToAuthenticated()
│ ├── sendToUser()
│ └── isUserConnected()
│
├── models/
│ └── User.js → User MongoDB schema
│
└── index.js → Server entry point & initialization
```
## 🔐 Security Architecture
```
┌─────────────────────────────────────────────────────────────┐
│ SECURITY LAYERS │
├─────────────────────────────────────────────────────────────┤
│ │
│ ┌───────────────────────────────────────────────────────┐ │
│ │ Layer 1: Network Security │ │
│ │ ┌─────────────────────────────────────────────────┐ │ │
│ │ │ • HTTPS/TLS for all HTTP traffic │ │ │
│ │ │ • WSS (WebSocket Secure) for WebSocket │ │ │
│ │ │ • Reverse proxy (Nginx) │ │ │
│ │ │ • DDoS protection │ │ │
│ │ └─────────────────────────────────────────────────┘ │ │
│ └───────────────────────────────────────────────────────┘ │
│ │
│ ┌───────────────────────────────────────────────────────┐ │
│ │ Layer 2: Application Security │ │
│ │ ┌─────────────────────────────────────────────────┐ │ │
│ │ │ • Helmet.js security headers │ │ │
│ │ │ • CORS configuration │ │ │
│ │ │ • Rate limiting (per IP) │ │ │
│ │ │ • Input validation (Fastify schemas) │ │ │
│ │ │ • XSS protection │ │ │
│ │ └─────────────────────────────────────────────────┘ │ │
│ └───────────────────────────────────────────────────────┘ │
│ │
│ ┌───────────────────────────────────────────────────────┐ │
│ │ Layer 3: Authentication & Authorization │ │
│ │ ┌─────────────────────────────────────────────────┐ │ │
│ │ │ • Steam OAuth (trusted provider) │ │ │
│ │ │ • JWT with short expiration (15 min) │ │ │
│ │ │ • Refresh tokens (7 days) │ │ │
│ │ │ • httpOnly cookies (CSRF protection) │ │ │
│ │ │ • Staff level permissions │ │ │
│ │ │ • 2FA support (ready) │ │ │
│ │ └─────────────────────────────────────────────────┘ │ │
│ └───────────────────────────────────────────────────────┘ │
│ │
│ ┌───────────────────────────────────────────────────────┐ │
│ │ Layer 4: Data Security │ │
│ │ ┌─────────────────────────────────────────────────┐ │ │
│ │ │ • Mongoose schema validation │ │ │
│ │ │ • Sensitive data filtering (don't expose 2FA) │ │ │
│ │ │ • MongoDB authentication │ │ │
│ │ │ • Encrypted connections to DB │ │ │
│ │ └─────────────────────────────────────────────────┘ │ │
│ └───────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────┘
```
## 🚀 Deployment Architecture
### Single Server (Small Scale)
```
┌─────────────────────────────────────────────────────────┐
│ Single VPS/Server │
├─────────────────────────────────────────────────────────┤
│ │
│ ┌───────────────────────────────────────────────────┐ │
│ │ Nginx (Reverse Proxy + SSL Termination) │ │
│ │ Port 80 (HTTP) → 443 (HTTPS) │ │
│ └───────────────────┬───────────────────────────────┘ │
│ │ │
│ ┌───────────────────▼───────────────────────────────┐ │
│ │ PM2 Process Manager │ │
│ │ ┌─────────────────────────────────────────────┐ │ │
│ │ │ Fastify (Node.js) │ │ │
│ │ │ Port 3000 │ │ │
│ │ │ - API Routes │ │ │
│ │ │ - WebSocket Server │ │ │
│ │ └─────────────────────────────────────────────┘ │ │
│ └───────────────────────────────────────────────────┘ │
│ │
│ ┌───────────────────────────────────────────────────┐ │
│ │ MongoDB (Local or Atlas) │ │
│ │ Port 27017 │ │
│ └───────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────┘
```
### Multi-Server (Large Scale)
```
┌─────────────────────┐
│ Load Balancer │
│ (AWS ELB/Nginx) │
└──────────┬──────────┘
│
┌───────────────┼───────────────┐
│ │ │
┌───────▼──────┐ ┌─────▼──────┐ ┌─────▼──────┐
│ App Server │ │ App Server │ │ App Server │
│ Instance │ │ Instance │ │ Instance │
│ (Fastify) │ │ (Fastify) │ │ (Fastify) │
└───────┬──────┘ └─────┬──────┘ └─────┬──────┘
│ │ │
└───────────────┼───────────────┘
│
┌───────────────┴───────────────┐
│ │
┌───────▼──────────┐ ┌─────────▼──────────┐
│ Redis Cluster │ │ MongoDB Replica │
│ - Sessions │ │ Set │
│ - Rate Limit │ │ - Primary Node │
│ - Cache │ │ - Secondary Nodes │
│ - WebSocket │ │ - Arbiter │
│ Pub/Sub │ │ │
└──────────────────┘ └────────────────────┘
```
## 📊 Database Schema Design
```
┌─────────────────────────────────────────────────────────────┐
│ DATABASE │
├─────────────────────────────────────────────────────────────┤
│ │
│ ┌────────────────────────────────────────────────────────┐│
│ │ users ││
│ │ ├── _id (ObjectId, Primary Key) ││
│ │ ├── steamId (String, Unique Index) ││
│ │ ├── username (String) ││
│ │ ├── email { address, verified, token } ││
│ │ ├── balance (Number, Default: 0) ││
│ │ ├── staffLevel (Number, Default: 0) ││
│ │ ├── ban { banned, reason, expires } ││
│ │ ├── twoFactor { enabled, secret, qrCode } ││
│ │ ├── createdAt (Date) ││
│ │ └── updatedAt (Date) ││
│ └────────────────────────────────────────────────────────┘│
│ │
│ ┌────────────────────────────────────────────────────────┐│
│ │ listings (Future) ││
│ │ ├── _id (ObjectId, Primary Key) ││
│ │ ├── seller (ObjectId → users) ││
│ │ ├── itemName (String) ││
│ │ ├── game (String: cs2 | rust) ││
│ │ ├── price (Number) ││
│ │ ├── status (String: active | sold | cancelled) ││
│ │ ├── assetId (String) ││
│ │ └── createdAt (Date) ││
│ └────────────────────────────────────────────────────────┘│
│ │
│ ┌────────────────────────────────────────────────────────┐│
│ │ transactions (Future) ││
│ │ ├── _id (ObjectId, Primary Key) ││
│ │ ├── buyer (ObjectId → users) ││
│ │ ├── seller (ObjectId → users) ││
│ │ ├── listing (ObjectId → listings) ││
│ │ ├── amount (Number) ││
│ │ ├── status (String: pending | completed | failed) ││
│ │ └── createdAt (Date) ││
│ └────────────────────────────────────────────────────────┘│
│ │
└─────────────────────────────────────────────────────────────┘
```
## 🔄 Request Lifecycle
```
1. Client Request
│
├─► Nginx (Reverse Proxy)
│ ├─ SSL Termination
│ ├─ DDoS Protection
│ └─ Load Balancing
│
2. Fastify Server
│
├─► Pre-Handler Hooks
│ ├─ CORS Check
│ ├─ Helmet Headers
│ └─ Rate Limiting
│
3. Middleware
│
├─► Authentication
│ ├─ Extract JWT from Cookie/Header
│ ├─ Verify JWT Signature
│ ├─ Check Expiration
│ └─ Load User from DB
│
├─► Authorization
│ ├─ Check Staff Level
│ ├─ Verify Email (if required)
│ └─ Check 2FA (if required)
│
4. Route Handler
│
├─► Input Validation
│ └─ Fastify Schema Validation
│
├─► Business Logic
│ ├─ Database Operations
│ ├─ External API Calls
│ └─ WebSocket Broadcasts
│
5. Response
│
├─► Success/Error Response
│ ├─ JSON Serialization
│ ├─ Set Cookies (if needed)
│ └─ Send to Client
│
6. Post-Handler Hooks
│
└─► Logging & Analytics
```
## 🎯 Technology Decisions
### Why Fastify?
- **Performance**: 3x faster than Express
- **Schema Validation**: Built-in JSON schema validation
- **TypeScript Support**: Excellent TypeScript support
- **Plugin System**: Robust plugin architecture
- **Active Development**: Well-maintained and modern
### Why MongoDB?
- **Flexible Schema**: Easy to evolve data models
- **JSON-Native**: Perfect for JavaScript/Node.js
- **Scalability**: Horizontal scaling with sharding
- **Rich Queries**: Powerful aggregation framework
- **Atlas**: Excellent managed hosting option
### Why JWT + Cookies?
- **Stateless**: No server-side session storage needed
- **Scalable**: Works across multiple servers
- **Secure**: httpOnly cookies prevent XSS
- **Flexible**: Can use both cookies and headers
- **Standard**: Industry-standard authentication
### Why WebSocket?
- **Real-Time**: Instant bidirectional communication
- **Efficient**: Lower overhead than HTTP polling
- **Native Support**: Built-in browser support
- **Scalable**: Can be extended with Redis pub/sub
- **Flexible**: Works for various real-time features
## 📈 Scalability Strategy
### Vertical Scaling (Phase 1)
- Increase server resources (CPU, RAM)
- Optimize database queries
- Add database indexes
- Enable caching
### Horizontal Scaling (Phase 2)
- Multiple application servers
- Load balancer
- Redis for shared state
- MongoDB replica set
- CDN for static assets
### Microservices (Phase 3)
- Split into separate services:
- Auth Service
- User Service
- Marketplace Service
- WebSocket Service
- Payment Service
- API Gateway
- Service mesh
- Message queue (RabbitMQ/Kafka)
---
**This architecture is designed to be:**
- ✅ Production-ready
- ✅ Scalable
- ✅ Secure
- ✅ Maintainable
- ✅ Developer-friendly
Reference in New Issue View Git Blame Copy Permalink