TurboTrades/frontend/QUICKSTART.md

TurboTrades - Quick Start Guide

Get your TurboTrades marketplace up and running in minutes!

📦 What You'll Need

• Node.js 18+ installed
• MongoDB 5.0+ installed and running
• Steam API Key (Get one here)
• A code editor (VS Code recommended)

🚀 Quick Setup (5 Minutes)

Step 1: Backend Setup

# Navigate to project root
cd TurboTrades

# Install backend dependencies
npm install

# Create environment file
cp .env.example .env

Edit .env with your credentials:

MONGODB_URI=mongodb://localhost:27017/turbotrades
STEAM_API_KEY=YOUR_STEAM_API_KEY_HERE
SESSION_SECRET=your-random-secret-here
JWT_ACCESS_SECRET=your-jwt-access-secret
JWT_REFRESH_SECRET=your-jwt-refresh-secret
PORT=3000
NODE_ENV=development

# Start MongoDB (if not already running)
mongod

# Start backend server
npm run dev

Backend will be running at http://localhost:3000 ✅

Step 2: Frontend Setup

Open a new terminal window:

# Navigate to frontend directory
cd TurboTrades/frontend

# Install frontend dependencies
npm install

# Start development server
npm run dev

Frontend will be running at http://localhost:5173 ✅

Step 3: Open Your Browser

Visit http://localhost:5173 and you're ready to go! 🎉

🔑 First Login

1. Click the "Sign in through Steam" button in the navigation bar
2. Authorize with your Steam account
3. You'll be redirected back to the marketplace
4. Your profile will appear in the top-right corner

🎯 Quick Feature Tour

Browse Marketplace

• Go to /market to see all items
• Use filters to narrow down results
• Click any item to view details

Set Up Your Profile

1. Click your avatar → Profile
2. Add your Steam Trade URL (required for trading)
3. Optionally add your email for notifications

Deposit Funds (UI Only - Mock)

1. Go to Profile → Deposit
2. Select amount and payment method
3. Click "Continue to Payment"

Sell Items (Coming Soon)

1. Go to Sell page
2. Select items from your Steam inventory
3. Set prices and list on marketplace

🛠️ Project Structure Overview

TurboTrades/
├── backend (Node.js + Fastify)
│   ├── index.js           # Main server file
│   ├── models/            # MongoDB schemas
│   ├── routes/            # API endpoints
│   ├── middleware/        # Auth & validation
│   └── utils/             # WebSocket, JWT, etc.
│
└── frontend (Vue 3 + Vite)
    ├── src/
    │   ├── views/         # Page components
    │   ├── components/    # Reusable components
    │   ├── stores/        # Pinia state management
    │   ├── router/        # Vue Router config
    │   └── assets/        # CSS & images
    └── index.html         # Entry point

📡 API Endpoints

Authentication

• GET /auth/steam - Initiate Steam login
• GET /auth/me - Get current user
• POST /auth/logout - Logout
• POST /auth/refresh - Refresh access token

User Management

• GET /user/profile - Get user profile
• PATCH /user/trade-url - Update trade URL
• PATCH /user/email - Update email
• GET /user/balance - Get balance

WebSocket

• WS /ws - WebSocket connection for real-time updates

🌐 WebSocket Events

The frontend automatically connects to WebSocket for real-time updates:

Client → Server

{ type: 'ping' }  // Keep-alive heartbeat

Server → Client

{ type: 'connected', data: { userId, timestamp } }
{ type: 'pong', timestamp }
{ type: 'notification', data: { message } }
{ type: 'balance_update', data: { balance } }
{ type: 'listing_update', data: { itemId, price } }
{ type: 'price_update', data: { itemId, newPrice } }

🎨 Design System

Colors

• Primary Orange: #f58700
• Dark Background: #0f1923
• Surface: #151d28
• Accent Blue: #3b82f6
• Accent Green: #10b981
• Accent Red: #ef4444

Component Classes

<!-- Buttons -->
<button class="btn btn-primary">Primary</button>
<button class="btn btn-secondary">Secondary</button>

<!-- Cards -->
<div class="card">
  <div class="card-body">Content</div>
</div>

<!-- Inputs -->
<input type="text" class="input" />

<!-- Badges -->
<span class="badge badge-primary">Badge</span>

🔐 Authentication Flow

sequenceDiagram
    User->>Frontend: Click "Sign in"
    Frontend->>Backend: GET /auth/steam
    Backend->>Steam: Redirect to Steam OAuth
    Steam->>Backend: OAuth callback
    Backend->>Frontend: Set JWT cookies + redirect
    Frontend->>Backend: GET /auth/me
    Backend->>Frontend: User data

📱 Key Features

✅ Implemented

• Steam OAuth authentication
• JWT token management (access + refresh)
• WebSocket real-time connection
• User profile management
• Responsive navigation
• Dark theme UI
• Toast notifications
• Protected routes
• Auto token refresh

🚧 Coming Soon

• Marketplace item listing
• Item purchase flow
• Steam inventory integration
• Payment processing
• Trade bot integration
• Admin dashboard
• Transaction history
• Email notifications
• 2FA authentication

🐛 Troubleshooting

Backend Won't Start

# Check if MongoDB is running
mongod --version

# Check if port 3000 is available
lsof -i :3000  # macOS/Linux
netstat -ano | findstr :3000  # Windows

Frontend Won't Start

# Clear node_modules and reinstall
rm -rf node_modules package-lock.json
npm install

Steam Login Not Working

• Verify STEAM_API_KEY in .env
• Check STEAM_REALM matches your domain
• Ensure MongoDB is running and connected

WebSocket Not Connecting

• Check backend is running on port 3000
• Check browser console for errors
• Verify CORS settings in backend

Styling Issues

# Restart Vite dev server
# Press Ctrl+C and run npm run dev again

📚 Additional Resources

Backend Documentation

• README.md - Full backend documentation
• ARCHITECTURE.md - System architecture
• WEBSOCKET_GUIDE.md - WebSocket implementation

Frontend Documentation

• frontend/README.md - Full frontend documentation
• Pinia Docs - State management
• Vue Router Docs - Routing
• Tailwind CSS Docs - Styling

External Resources

• Steam Web API
• Vue 3 Guide
• Fastify Documentation

🎯 Next Steps

1. Explore the UI - Browse all pages and features
2. Check the Code - Review component structure
3. Read Documentation - Deep dive into backend/frontend docs
4. Add Features - Start building on top of the foundation
5. Deploy - Follow deployment guides for production

💡 Pro Tips

• Use Vue DevTools browser extension for debugging
• Install Volar extension in VS Code for Vue support
• Enable Tailwind CSS IntelliSense for class autocomplete
• Check browser console for WebSocket connection status
• Use npm run dev for both backend and frontend during development

🤝 Need Help?

• Check existing documentation in the project
• Review code comments for implementation details
• Open an issue on GitHub
• Contact support at support@turbotrades.com

🎉 You're All Set!

Your TurboTrades marketplace is now running. Happy trading! 🚀

---

Last Updated: January 2025 Version: 1.0.0