# Nova Exchange - Build Notes

## Project Overview
Marketplace for Dune Awakening Discord community. Users can list items for sale/trade, make offers, and review each other.

## Tech Stack
- **Backend:** Node.js + Express
- **Database:** SQLite (better-sqlite3)
- **Auth:** Discord OAuth2
- **Frontend:** Vanilla JS + CSS

## Setup

### 1. Discord Application
1. Create app at https://discord.com/developers/applications
2. Get Client ID and Client Secret from OAuth2 section
3. Add redirect URIs:
   - `http://localhost:3000/auth/callback` (dev)
   - `https://yourdomain.com/auth/callback` (prod)
4. Go to Bot section:
   - Click "Reset Token" and save the bot token
   - Enable Server Members Intent
5. Invite bot to server:
   - OAuth2 → URL Generator
   - Scopes: `bot`, `identify`, `guilds`, `guilds.members.read`
   - Bot Permissions: Send Messages, Embed Links
   - Use generated URL to invite

### 2. Environment Variables
Copy `env.example` to `.env` and fill in:
- `DISCORD_CLIENT_ID` - from Discord app
- `DISCORD_CLIENT_SECRET` - from Discord app  
- `DISCORD_SERVER_ID` - right-click server → Copy Server ID
- `DISCORD_BOT_TOKEN` - from Discord app → Bot → Reset Token
- `DISCORD_CHANNEL_ID` - right-click channel → Copy Channel ID
- `SESSION_SECRET` - random string for session encryption
- `BASE_URL` - `http://localhost:3000` for dev

### 3. Install & Run
```bash
npm install
npm run dev
```

## cPanel Deployment
1. Create Node.js app in cPanel (Node 18+)
2. Upload files (excluding node_modules, .env, *.db)
3. Set environment variables in cPanel
4. Run `npm install` in cPanel terminal
5. Add production callback URL to Discord app
6. Start the application

## Database
SQLite database (`exchange.db`) is created automatically on first run.

Tables:
- `users` - Discord user data
- `listings` - Sale/trade listings
- `offers` - Offers on listings
- `reviews` - User reviews

## File Structure
```
exchange/
├── server.js           # Express server
├── database/
│   └── schema.js       # SQLite schema & connection
├── routes/
│   ├── auth.js         # Discord OAuth
│   ├── listings.js     # Listing CRUD
│   ├── offers.js       # Offer management
│   ├── reviews.js      # Review system
│   ├── items.js        # Item database API
│   └── users.js        # User profiles
├── middleware/
│   └── auth.js         # Auth middleware
├── data/
│   └── items.js        # 837 items scraped from awakening.wiki
├── utils/
│   └── discord.js      # Bot channel notifications
├── public/
│   ├── index.html      # SPA shell
│   ├── css/style.css   # Styles
│   └── js/app.js       # Frontend logic
└── package.json
```

---

## Production Deployment Notes

### Pre-Deploy Checklist
- [ ] Create `.env` file with all production values (DO NOT commit)
- [ ] Set `SESSION_SECRET` to a strong random string (required - fallback is insecure)
- [ ] Update `BASE_URL` to production domain (e.g. `https://yourdomain.com`)
- [ ] Add production callback URL to Discord app: `https://yourdomain.com/auth/callback`
- [ ] Verify Discord bot has been invited to the server
- [ ] Verify Discord bot token and channel ID are correct

### Environment Variables Required
All must be set in cPanel (or `.env` for local):
```
DISCORD_CLIENT_ID=xxxxx
DISCORD_CLIENT_SECRET=xxxxx
DISCORD_SERVER_ID=xxxxx
DISCORD_BOT_TOKEN=xxxxx
DISCORD_CHANNEL_ID=xxxxx
SESSION_SECRET=xxxxx         # MUST be unique, random, 32+ chars
PORT=3000
BASE_URL=https://yourdomain.com
NODE_ENV=production          # Enables secure cookies
```

### cPanel Steps
1. Create Node.js app in cPanel (Node 18+)
2. Upload all files EXCEPT: `node_modules/`, `.env`, `*.db`
3. Set environment variables in cPanel Node.js settings
4. SSH/Terminal: `cd` to app directory, run `npm install`
5. Start application
6. Database (`exchange.db`) auto-creates on first run

### Security Notes
- Session cookies are `httpOnly` and `secure` (HTTPS only) in production
- All database queries use parameterized statements (SQL injection protected)
- Auth middleware protects all user-specific endpoints
- Owner verification on all update/delete operations

### Known Limitations (OK for launch)
- No rate limiting - consider adding if abuse occurs
- SQLite single-file database - sufficient for community size
- Sessions stored in memory (will lose on restart) - OK for small scale

### Post-Deploy Verification
1. Visit site, should see marketplace
2. Click "Login with Discord" - should redirect to Discord OAuth
3. After login, should show your Discord username/avatar
4. Create a test listing - should appear on marketplace
5. Check Discord channel - bot notification should post
6. Test offer flow if possible

### Troubleshooting
- **"Not a member" error**: User must be in the Discord server
- **Bot not posting**: Verify `DISCORD_BOT_TOKEN` and `DISCORD_CHANNEL_ID`
- **Login redirect fails**: Check `BASE_URL` matches exactly (including https)
- **Blank page**: Check browser console for errors, ensure static files served