# 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