Now when you refresh/migrate the database, your test users will be automatically created. Here's what I've set up:

  Laravel Seeder Setup

  UserSeeder Features:
  - Creates your 4 existing users with all their details
  - Sets passwords to 'password' for easy testing
  - Sets jack@stefani.org as admin
  - Uses updateOrCreate() so it won't create duplicates if run multiple times
  - All users are email verified

  To use the seeders:

  1. Refresh database with seeds:
  php artisan migrate:fresh --seed
  2. Run just the UserSeeder:
  php artisan db:seed --class=UserSeeder
  3. Run all seeders:
  php artisan db:seed

  Login credentials for testing:
  - All users: password is password
  - Admin user: jack@stefani.org / password
  - Regular users: Any of the other 3 emails / password

  The seeder is now part of the standard Laravel database seeding flow, so whenever you reset your database, these test users will be automatically recreated.








  

# Musical Marketplace - Developer Guide

## Architecture Overview

This is a Laravel 11 application implementing a musical instrument marketplace with modern features like user curation, behavioral tracking, and a minimalist UI inspired by monome.org.

### Tech Stack
- **Framework**: Laravel 11 (PHP 8.2+)
- **Database**: MySQL (production) / SQLite (development)
- **Frontend**: Blade templates + Tailwind CSS + Alpine.js
- **Build Tools**: Vite for asset compilation
- **Authentication**: Laravel Breeze

### Core Features
- Musical instrument listings (buy/sell/trade)
- User messaging system
- Behavioral tracking and recommendations
- Admin analytics dashboard
- Photo management with multiple images per listing
- Watchlist functionality (AJAX-powered)
- User feedback/rating system
- Dark mode with sophisticated gray tones

## Directory Structure

### Key Directories
```
app/
├── Http/Controllers/          # Route controllers
│   ├── Admin/                # Admin-specific controllers
│   ├── API/                  # API endpoints (behavioral tracking)
│   └── ...
├── Models/                   # Eloquent models
├── Policies/                 # Authorization policies
└── Providers/               # Service providers

database/
├── migrations/              # Database schema changes
└── seeders/                # Database seeding

resources/
├── js/                     # JavaScript files
│   ├── app.js             # Main JS entry point
│   └── darkmode.js        # Dark mode functionality
├── css/                   # Stylesheets
│   └── app.css           # Main CSS with Tailwind
└── views/                # Blade templates
    ├── components/       # Reusable components
    ├── layouts/         # Layout templates
    ├── marketplace/     # Main marketplace views
    ├── items/          # Item listing views
    ├── admin/          # Admin dashboard views
    └── ...

public/
├── build/              # Compiled assets (Vite output)
└── uploads/           # User-uploaded images

routes/
├── web.php            # Main web routes
├── api.php           # API routes
└── auth.php          # Authentication routes
```

## Key Models & Relationships

### Core Models
- **User**: Users with roles (admin/regular)
- **Item**: Musical instrument listings
- **Category**: Instrument categories (synths, guitars, etc.)
- **ItemPhoto**: Multiple photos per item
- **Message**: User-to-user messaging
- **Transaction**: Buy/sell transactions
- **UserInteraction**: Behavioral tracking (views, clicks)
- **UserPreference**: User instrument preferences
- **Watchlist**: User saved items

### Important Relationships
```php
// User relationships
User->items()           // Items they've listed
User->sentMessages()    // Messages they've sent
User->transactions()    // Their transactions
User->interactions()    // Their behavioral data
User->preferences()     // Their instrument preferences
User->watchlistItems()  // Items they're watching

// Item relationships
Item->user()           // Who listed it
Item->category()       // What type of instrument
Item->photos()         // Associated photos
Item->messages()       // Messages about this item
Item->watchers()       // Users watching this item
Item->interactions()   // Behavioral data for this item
```

## Key Controllers

### Public Controllers
- **MarketplaceController**: Homepage with featured/recent items
- **ItemController**: Browse, search, view individual items
- **MessageController**: User messaging system
- **WatchlistController**: AJAX watchlist management
- **ProfileController**: User profiles and settings

### Admin Controllers
- **AdminController**: Main admin dashboard with analytics
- **AdminUserController**: User management and impersonation
- **AdminItemController**: Item moderation
- **AdminReportController**: Analytics and reporting

### API Controllers
- **UserInteractionController**: Tracks user behavior (AJAX)

## Database Schema Highlights

### Key Tables
```sql
users                    # User accounts
items                    # Instrument listings
categories              # Instrument categories
item_photos             # Multiple photos per item
messages                # User messaging
transactions            # Buy/sell records
user_interactions       # Behavioral tracking
user_preferences        # User instrument preferences
watchlists              # User saved items
```

### Important Migrations
- `create_user_interactions_table` - Behavioral tracking system
- `create_user_preferences_table` - User curation system
- `create_watchlists_table` - Watchlist functionality

## Frontend Architecture

### Styling
- **Tailwind CSS**: Utility-first CSS framework
- **Dark Mode**: Class-based (`dark:` prefixes) with localStorage persistence
- **Design**: Monome-inspired minimalist aesthetic with lots of negative space

### JavaScript
- **Alpine.js**: For interactive components (dropdowns, mobile nav)
- **Vanilla JS**: Custom functionality (dark mode, AJAX watchlist, behavioral tracking)
- **Vite**: Asset bundling and hot reloading

### Key Components
- `hero-section.blade.php` - Homepage hero with minimal design
- `navigation.blade.php` - Fixed navigation with dark mode toggle
- Various item cards and grids throughout

## Behavioral Tracking System

The app tracks user interactions for personalized recommendations:

### Tracked Events
- **view**: Item page views
- **click**: Item clicks from listings
- **search**: Search queries
- **watchlist_add/remove**: Watchlist actions

### Implementation
```javascript
// Auto-tracking (in app.blade.php)
trackInteraction(itemId, 'view', metadata);

// Manual tracking
window.trackInteraction(itemId, 'click', {
    source: window.location.pathname,
    referrer: document.referrer
});
```

### Data Storage
- `user_interactions` table with polymorphic relationships
- Metadata stored as JSON for flexibility
- Used for admin analytics and future recommendation engine

## Admin Features

### Analytics Dashboard
- Real-time user activity
- Popular categories and items
- User behavior trends
- Item listing statistics

### User Management
- User impersonation for debugging
- User activity monitoring
- Preference management

## Development Workflow

### Local Development
```bash
# Install dependencies
composer install
npm install

# Set up environment
cp .env.example .env
php artisan key:generate

# Database setup
php artisan migrate
php artisan db:seed

# Start development servers
php artisan serve
npm run dev
```

### Asset Compilation
```bash
npm run dev    # Development with hot reload
npm run build  # Production build
```

### Database Operations
```bash
php artisan migrate              # Run migrations
php artisan migrate:rollback     # Rollback migrations
php artisan db:seed             # Seed database
php artisan migrate:fresh --seed # Fresh DB with seeds
```

## Deployment

### Production Deployment
```bash
./deploy.sh  # Automated deployment to xeek.com
```

The deployment script:
- Builds assets locally with Vite
- Syncs files to production server
- Runs Composer with PHP 8.2
- Executes Laravel setup commands
- Handles database migrations

### Environment Configuration
- Production uses MySQL database
- Environment variables set in deploy script
- Assets compiled and synced to server

## Key Configuration Files

### Laravel Config
- `config/app.php` - Main application config
- `config/database.php` - Database connections
- `config/filesystems.php` - File storage config

### Frontend Config
- `tailwind.config.js` - Tailwind CSS configuration with dark mode
- `vite.config.js` - Asset build configuration
- `package.json` - Node.js dependencies

### Deployment Config
- `deploy.sh` - Production deployment script
- `.env.example` - Environment template

## Testing

### Running Tests
```bash
php artisan test              # Run all tests
php artisan test --coverage  # With coverage report
```

### Key Test Areas
- Authentication flows
- Item CRUD operations
- Admin functionality
- API endpoints

## Common Tasks

### Adding New Item Categories
1. Add to database via migration or admin
2. Categories auto-appear in filters

### Modifying UI Design
- Edit Blade templates in `resources/views/`
- Update Tailwind classes
- Rebuild assets with `npm run build`

### Adding New Behavioral Tracking
1. Add tracking calls in JavaScript
2. Optionally extend `UserInteraction` model
3. Update admin analytics if needed

### Database Backups
```bash
# Export data only (schema handled by migrations)
mysqldump -u username -p --no-create-info database_name > backup.sql

# Import data
mysql -u username -p database_name < backup.sql
```

## Security Notes

- CSRF protection on all forms
- User authorization via policies
- Image upload validation
- SQL injection protection via Eloquent
- XSS protection via Blade escaping

## Performance Considerations

- Database queries optimized with eager loading
- Asset compilation via Vite
- Image optimization recommended for uploads
- Caching configured for production (routes, config, views)

This marketplace combines modern Laravel practices with a unique minimalist design, comprehensive user tracking, and robust admin tools for managing a musical instrument community.