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](https://steamcommunity.com/dev/apikey))
- A code editor (VS Code recommended)

## 🚀 Quick Setup (5 Minutes)

### Step 1: Backend Setup

```bash
# Navigate to project root
cd TurboTrades

# Install backend dependencies
npm install

# Create environment file
cp .env.example .env
```

Edit `.env` with your credentials:
```env
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
```

```bash
# 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**:

```bash
# 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
```javascript
{ type: 'ping' }  // Keep-alive heartbeat
```

### Server → Client
```javascript
{ 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
```html
<!-- 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

```mermaid
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
```bash
# 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
```bash
# 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
```bash
# Restart Vite dev server
# Press Ctrl+C and run npm run dev again
```

## 📚 Additional Resources

### Backend Documentation
- [README.md](../README.md) - Full backend documentation
- [ARCHITECTURE.md](../ARCHITECTURE.md) - System architecture
- [WEBSOCKET_GUIDE.md](../WEBSOCKET_GUIDE.md) - WebSocket implementation

### Frontend Documentation
- [frontend/README.md](./README.md) - Full frontend documentation
- [Pinia Docs](https://pinia.vuejs.org/) - State management
- [Vue Router Docs](https://router.vuejs.org/) - Routing
- [Tailwind CSS Docs](https://tailwindcss.com/) - Styling

### External Resources
- [Steam Web API](https://developer.valvesoftware.com/wiki/Steam_Web_API)
- [Vue 3 Guide](https://vuejs.org/guide/)
- [Fastify Documentation](https://www.fastify.io/)

## 🎯 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