TurboTrades/frontend/README.md

# TurboTrades Frontend

A modern, high-performance Vue 3 frontend for the TurboTrades marketplace, built with the Composition API, Pinia state management, and styled to match the skins.com aesthetic.

## 🚀 Features

- **Vue 3 + Composition API** - Modern Vue development with `<script setup>`
- **Pinia State Management** - Type-safe, intuitive state management
- **Vue Router** - Client-side routing with navigation guards
- **WebSocket Integration** - Real-time marketplace updates
- **Tailwind CSS** - Utility-first CSS framework with custom gaming theme
- **Axios** - HTTP client with interceptors for API calls
- **Toast Notifications** - Beautiful toast messages for user feedback
- **Responsive Design** - Mobile-first, works on all devices
- **Dark Theme** - Gaming-inspired dark mode design
- **Lucide Icons** - Beautiful, consistent icon system

## 📋 Prerequisites

- Node.js 18+ 
- npm or yarn
- Backend API running on `http://localhost:3000`

## 🛠️ Installation

1. **Navigate to the frontend directory**
```bash
cd TurboTrades/frontend
```

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

3. **Create environment file (optional)**
```bash
cp .env.example .env
```

Edit `.env` if you need to customize:
```env
VITE_API_URL=http://localhost:3000
```

4. **Start development server**
```bash
npm run dev
```

The app will be available at `http://localhost:5173`

## 📁 Project Structure

```
frontend/
├── public/                 # Static assets
├── src/
│   ├── assets/            # Stylesheets, images
│   │   └── main.css       # Main CSS with Tailwind + custom styles
│   ├── components/        # Reusable Vue components
│   │   ├── NavBar.vue     # Navigation bar with user menu
│   │   └── Footer.vue     # Site footer
│   ├── composables/       # Reusable composition functions
│   ├── router/            # Vue Router configuration
│   │   └── index.js       # Routes and navigation guards
│   ├── stores/            # Pinia stores
│   │   ├── auth.js        # Authentication state
│   │   ├── market.js      # Marketplace state
│   │   └── websocket.js   # WebSocket connection state
│   ├── utils/             # Utility functions
│   │   └── axios.js       # Axios instance with interceptors
│   ├── views/             # Page components
│   │   ├── HomePage.vue
│   │   ├── MarketPage.vue
│   │   ├── ItemDetailsPage.vue
│   │   ├── ProfilePage.vue
│   │   ├── InventoryPage.vue
│   │   └── ...
│   ├── App.vue            # Root component
│   └── main.js            # Application entry point
├── index.html             # HTML entry point
├── package.json           # Dependencies and scripts
├── tailwind.config.js     # Tailwind configuration
├── vite.config.js         # Vite configuration
└── README.md              # This file
```

## 🎨 Design System

### Colors

```javascript
// Primary (Orange)
primary-500: #f58700

// Dark Backgrounds
dark-500: #0f1923
surface: #151d28
surface-light: #1a2332
surface-lighter: #1f2a3c

// Accent Colors
accent-blue: #3b82f6
accent-green: #10b981
accent-red: #ef4444
accent-yellow: #f59e0b
accent-purple: #8b5cf6
```

### Typography

- **Display Font**: Montserrat (headings)
- **Body Font**: Inter (body text)

### Components

Pre-built component classes available:

```html
<!-- Buttons -->
<button class="btn btn-primary">Primary Button</button>
<button class="btn btn-secondary">Secondary Button</button>
<button class="btn btn-outline">Outline Button</button>
<button class="btn btn-ghost">Ghost Button</button>

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

<!-- Inputs -->
<input type="text" class="input" placeholder="Enter text">

<!-- Badges -->
<span class="badge badge-primary">Primary</span>
<span class="badge badge-success">Success</span>
```

## 🔌 API Integration

The frontend communicates with the backend via:

1. **REST API** - HTTP requests for CRUD operations
2. **WebSocket** - Real-time updates for marketplace

### Authentication Flow

```javascript
// Login (redirects to Steam OAuth)
authStore.login()

// Get current user
await authStore.fetchUser()

// Logout
await authStore.logout()

// Check authentication
if (authStore.isAuthenticated) {
  // User is logged in
}
```

### Making API Calls

```javascript
import axios from 'axios'

// All requests automatically include credentials
const response = await axios.get('/api/market/items')

// Error handling is done automatically via interceptors
```

## 🌐 WebSocket Usage

```javascript
import { useWebSocketStore } from '@/stores/websocket'

const wsStore = useWebSocketStore()

// Connect
wsStore.connect()

// Listen for events
wsStore.on('price_update', (data) => {
  console.log('Price updated:', data)
})

// Send message
wsStore.send({ type: 'ping' })

// Disconnect
wsStore.disconnect()
```

## 🗺️ Routes

| Path | Component | Auth Required | Description |
|------|-----------|---------------|-------------|
| `/` | HomePage | No | Landing page with featured items |
| `/market` | MarketPage | No | Browse marketplace |
| `/item/:id` | ItemDetailsPage | No | Item details and purchase |
| `/inventory` | InventoryPage | Yes | User's owned items |
| `/profile` | ProfilePage | Yes | User profile and settings |
| `/transactions` | TransactionsPage | Yes | Transaction history |
| `/sell` | SellPage | Yes | List items for sale |
| `/deposit` | DepositPage | Yes | Add funds |
| `/withdraw` | WithdrawPage | Yes | Withdraw funds |
| `/admin` | AdminPage | Admin | Admin dashboard |
| `/faq` | FAQPage | No | Frequently asked questions |
| `/support` | SupportPage | No | Support center |

## 🔐 Authentication Guards

Routes can be protected with meta fields:

```javascript
{
  path: '/profile',
  component: ProfilePage,
  meta: {
    requiresAuth: true,        // Requires login
    requiresAdmin: true,       // Requires admin role
    title: 'Profile'           // Page title
  }
}
```

## 🏪 Pinia Stores

### Auth Store (`useAuthStore`)

```javascript
const authStore = useAuthStore()

// State
authStore.user
authStore.isAuthenticated
authStore.balance
authStore.username

// Actions
await authStore.fetchUser()
authStore.login()
await authStore.logout()
await authStore.updateTradeUrl(url)
await authStore.updateEmail(email)
```

### Market Store (`useMarketStore`)

```javascript
const marketStore = useMarketStore()

// State
marketStore.items
marketStore.filters
marketStore.isLoading

// Actions
await marketStore.fetchItems()
await marketStore.purchaseItem(itemId)
await marketStore.listItem(itemData)
marketStore.updateFilter('search', 'AK-47')
marketStore.resetFilters()
```

### WebSocket Store (`useWebSocketStore`)

```javascript
const wsStore = useWebSocketStore()

// State
wsStore.isConnected
wsStore.connectionStatus

// Actions
wsStore.connect()
wsStore.disconnect()
wsStore.send(message)
wsStore.on(event, callback)
wsStore.off(event, callback)
```

## 🎯 Key Features

### Real-time Updates

The app automatically updates when:
- New items are listed
- Prices change
- Items are sold
- User balance changes

### Responsive Design

Breakpoints:
- Mobile: < 640px
- Tablet: 640px - 1024px
- Desktop: > 1024px

### Loading States

All data fetching operations show appropriate loading states:
- Skeleton loaders for initial load
- Spinners for actions
- Optimistic updates where appropriate

### Error Handling

Errors are automatically handled:
- Network errors show toast notifications
- 401 responses trigger token refresh or logout
- Form validation with inline error messages

## 🚀 Build & Deploy

### Development Build

```bash
npm run dev
```

### Production Build

```bash
npm run build
```

This creates an optimized build in the `dist` directory.

### Preview Production Build

```bash
npm run preview
```

### Deploy

The `dist` folder can be deployed to any static hosting service:

- **Netlify**: Drag & drop the `dist` folder
- **Vercel**: Connect your Git repository
- **GitHub Pages**: Use the `dist` folder
- **AWS S3**: Upload `dist` contents to S3 bucket

#### Environment Variables for Production

Create a `.env.production` file:

```env
VITE_API_URL=https://api.yourdomain.com
```

## 🧪 Development Tips

### Hot Module Replacement (HMR)

Vite provides instant HMR. Changes to your code will reflect immediately without full page reload.

### Vue DevTools

Install the Vue DevTools browser extension for easier debugging:
- Chrome: [Vue.js devtools](https://chrome.google.com/webstore/detail/vuejs-devtools/nhdogjmejiglipccpnnnanhbledajbpd)
- Firefox: [Vue.js devtools](https://addons.mozilla.org/en-US/firefox/addon/vue-js-devtools/)

### VS Code Extensions

Recommended extensions:
- Volar (Vue Language Features)
- Tailwind CSS IntelliSense
- ESLint
- Prettier

## 📝 Customization

### Change Theme Colors

Edit `tailwind.config.js`:

```javascript
theme: {
  extend: {
    colors: {
      primary: {
        500: '#YOUR_COLOR',
      },
    },
  },
}
```

### Add New Route

1. Create component in `src/views/`
2. Add route in `src/router/index.js`
3. Add navigation link in `NavBar.vue` or `Footer.vue`

### Add New Store

1. Create file in `src/stores/`
2. Define store with `defineStore`
3. Import and use in components

## 🐛 Troubleshooting

### WebSocket Not Connecting

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

### API Calls Failing

- Ensure backend is running
- Check network tab in browser DevTools
- Verify proxy settings in `vite.config.js`

### Styling Not Applied

- Restart dev server after Tailwind config changes
- Check for CSS class typos
- Verify Tailwind classes are in content paths

## 📄 License

ISC

## 🤝 Contributing

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/AmazingFeature`)
3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
4. Push to the branch (`git push origin feature/AmazingFeature`)
5. Open a Pull Request

## 📧 Support

For issues and questions:
- Create an issue on GitHub
- Email: support@turbotrades.com
- Discord: [Join our server](#)

## 🙏 Acknowledgments

- Design inspired by [skins.com](https://skins.com)
- Icons by [Lucide](https://lucide.dev)
- Built with [Vue 3](https://vuejs.org), [Vite](https://vitejs.dev), and [Tailwind CSS](https://tailwindcss.com)