TurboTrades/STRUCTURE.md

# TurboTrades Project Structure

Clean and simple structure with everything in the root directory.

## 📁 Directory Tree

```
TurboTrades/
├── config/                      # Configuration files
│   ├── database.js             # MongoDB connection handler
│   ├── index.js                # Environment variables loader
│   └── passport.js             # Steam OAuth strategy setup
│
├── middleware/                  # Custom Express/Fastify middleware
│   └── auth.js                 # JWT authentication & authorization
│
├── models/                      # MongoDB/Mongoose schemas
│   └── User.js                 # User schema (Steam, 2FA, email, bans)
│
├── routes/                      # API route handlers
│   ├── auth.js                 # Authentication routes (Steam login, logout, refresh)
│   ├── marketplace.example.js  # Example marketplace implementation
│   ├── user.js                 # User profile & settings routes
│   └── websocket.js            # WebSocket management routes
│
├── utils/                       # Utility functions & helpers
│   ├── jwt.js                  # JWT token generation & verification
│   └── websocket.js            # WebSocket manager with user mapping
│
├── .env                         # Environment variables (local config)
├── .env.example                 # Environment variables template
├── .gitignore                   # Git ignore rules
├── index.js                     # Main server entry point ⭐
├── package.json                 # Dependencies & npm scripts
│
└── Documentation/
    ├── ARCHITECTURE.md          # System architecture & diagrams
    ├── COMMANDS.md              # Command reference cheatsheet
    ├── PROJECT_SUMMARY.md       # High-level project overview
    ├── QUICKSTART.md            # 5-minute setup guide
    ├── README.md                # Main documentation
    ├── STRUCTURE.md             # This file
    ├── WEBSOCKET_GUIDE.md       # WebSocket integration guide
    └── test-client.html         # WebSocket test interface
```

## 🎯 File Purposes

### Core Files

**`index.js`** - Main server entry point
- Initializes Fastify server
- Registers all plugins (CORS, Helmet, WebSocket, etc.)
- Connects to MongoDB
- Registers all routes
- Starts the server

### Configuration (`config/`)

**`config/index.js`** - Central configuration
- Loads environment variables from `.env`
- Exports config object used throughout the app
- Provides sensible defaults

**`config/database.js`** - Database connection
- Connects to MongoDB using Mongoose
- Handles connection errors and retries
- Graceful shutdown support

**`config/passport.js`** - Authentication strategy
- Configures passport-steam strategy
- Handles Steam OAuth flow
- Creates/updates users on login

### Middleware (`middleware/`)

**`middleware/auth.js`** - Authentication & authorization
- `authenticate()` - Requires valid JWT token
- `optionalAuthenticate()` - Optional JWT verification
- `requireStaffLevel()` - Check staff permissions
- `requireVerifiedEmail()` - Require verified email
- `require2FA()` - Require two-factor auth
- `verifyRefreshTokenMiddleware()` - Verify refresh tokens

### Models (`models/`)

**`models/User.js`** - User database schema
- Steam profile data (ID, username, avatar)
- Marketplace data (balance, trade URL)
- Email system (address, verification)
- Security (bans, 2FA, staff level)
- Timestamps (createdAt, updatedAt)

### Routes (`routes/`)

**`routes/auth.js`** - Authentication endpoints
- `GET /auth/steam` - Start Steam login
- `GET /auth/steam/return` - OAuth callback
- `GET /auth/me` - Get current user
- `POST /auth/refresh` - Refresh access token
- `POST /auth/logout` - Logout user
- `GET /auth/verify` - Verify token validity

**`routes/user.js`** - User management endpoints
- `GET /user/profile` - Get user profile
- `PATCH /user/trade-url` - Update trade URL
- `PATCH /user/email` - Update email address
- `GET /user/verify-email/:token` - Verify email
- `GET /user/balance` - Get balance
- `GET /user/stats` - Get user statistics
- `PATCH /user/intercom` - Update intercom ID
- `GET /user/:steamId` - Public user profile

**`routes/websocket.js`** - WebSocket management
- `GET /ws` - WebSocket connection endpoint
- `GET /ws/stats` - Connection statistics
- `POST /ws/broadcast` - Broadcast to all (admin)
- `POST /ws/send/:userId` - Send to specific user
- `GET /ws/status/:userId` - Check online status

**`routes/marketplace.example.js`** - Example implementation
- Shows how to create marketplace routes
- Demonstrates WebSocket broadcasting
- Example purchase flow with notifications

### Utils (`utils/`)

**`utils/jwt.js`** - JWT token utilities
- `generateAccessToken()` - Create access token (15min)
- `generateRefreshToken()` - Create refresh token (7 days)
- `generateTokenPair()` - Create both tokens
- `verifyAccessToken()` - Verify access token
- `verifyRefreshToken()` - Verify refresh token
- `isTokenExpired()` - Check if token expired

**`utils/websocket.js`** - WebSocket manager
- `handleConnection()` - Process new connections
- `broadcastPublic()` - Send to all clients
- `broadcastToAuthenticated()` - Send to authenticated users
- `sendToUser()` - Send to specific user
- `isUserConnected()` - Check if user is online
- User-to-socket mapping
- Heartbeat/ping-pong system
- Automatic cleanup of dead connections

## 🔄 Data Flow

### Authentication Flow
```
Client → /auth/steam → Steam → /auth/steam/return → Generate JWT → Set Cookies → Client
```

### API Request Flow
```
Client → Nginx → Fastify → Middleware → Route Handler → Database → Response
```

### WebSocket Flow
```
Client → /ws → Authenticate → Map User → Send/Receive Messages → Broadcast
```

## 📦 Key Dependencies

```json
{
  "fastify": "High-performance web framework",
  "mongoose": "MongoDB ODM",
  "passport-steam": "Steam OAuth authentication",
  "jsonwebtoken": "JWT token creation/verification",
  "ws": "WebSocket implementation",
  "@fastify/cookie": "Cookie parsing & setting",
  "@fastify/cors": "CORS support",
  "@fastify/helmet": "Security headers",
  "@fastify/rate-limit": "Rate limiting",
  "@fastify/websocket": "WebSocket plugin for Fastify"
}
```

## 🚀 Getting Started

1. **Install dependencies**
   ```bash
   npm install
   ```

2. **Configure environment**
   ```bash
   cp .env.example .env
   # Edit .env with your Steam API key
   ```

3. **Start MongoDB**
   ```bash
   mongod
   ```

4. **Run the server**
   ```bash
   npm run dev
   ```

## 📝 Adding New Features

### Adding a new route
1. Create file in `routes/` (e.g., `routes/trades.js`)
2. Define your endpoints with proper middleware
3. Import and register in `index.js`

```javascript
// routes/trades.js
export default async function tradesRoutes(fastify, options) {
  fastify.get('/trades', { preHandler: authenticate }, async (req, reply) => {
    // Your logic here
  });
}

// index.js
import tradesRoutes from './routes/trades.js';
await fastify.register(tradesRoutes);
```

### Adding a new model
1. Create file in `models/` (e.g., `models/Listing.js`)
2. Define Mongoose schema
3. Export the model

```javascript
// 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);
```

### Adding middleware
1. Create or update file in `middleware/`
2. Export your middleware function
3. Use in routes with `preHandler`

```javascript
// middleware/custom.js
export const myMiddleware = async (request, reply) => {
  // Your logic
};

// In routes
fastify.get('/protected', {
  preHandler: [authenticate, myMiddleware]
}, handler);
```

### Adding utilities
1. Create file in `utils/` (e.g., `utils/email.js`)
2. Export utility functions
3. Import where needed

```javascript
// utils/email.js
export const sendVerificationEmail = async (email, token) => {
  // Email logic
};

// In routes
import { sendVerificationEmail } from '../utils/email.js';
```

## 🧪 Testing

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

# Test authenticated endpoint
curl http://localhost:3000/auth/me \
  -H "Authorization: Bearer YOUR_TOKEN"

# Test WebSocket
open test-client.html
```

## 📚 Documentation Files

- **README.md** - Start here for complete overview
- **QUICKSTART.md** - Get running in 5 minutes
- **WEBSOCKET_GUIDE.md** - Detailed WebSocket integration
- **ARCHITECTURE.md** - System design & diagrams
- **COMMANDS.md** - Command reference guide
- **PROJECT_SUMMARY.md** - High-level summary
- **STRUCTURE.md** - This file (project organization)

## 🎯 Why This Structure?

✅ **Simple** - No nested `src/` folder, everything at root level  
✅ **Clear** - Organized by function (routes, models, utils)  
✅ **Scalable** - Easy to add new features  
✅ **Standard** - Follows Node.js conventions  
✅ **Clean** - Separation of concerns  
✅ **Maintainable** - Easy to navigate and understand  

---

**Ready to build your marketplace! 🚀**