# Musical Marketplace - Project Documentation

## Overview

Musical Marketplace (xeek.com) is a Laravel-based e-commerce platform for buying, selling, and trading musical equipment. This is the **production** environment.

## Environment Details

### Server Information
- **Production URL**: https://xeek.com (and https://www.xeek.com)
- **Beta URL**: https://hound.xeek.com
- **Server IP**: 155.138.214.10
- **Web Root**: `/var/www/html`
- **Public Directory**: `/var/www/html/public`
- **Server User**: `www-data:www-data`

### Technology Stack
- **Framework**: Laravel 12.18.0
- **PHP Version**: 8.x
- **Node.js**: v20.19.5
- **NPM**: 10.8.2
- **Database**: MySQL/MariaDB
- **Web Server**: Apache 2.4.58 (Ubuntu)
- **Frontend**: Vite + Alpine.js + Tailwind CSS 4

### Git Repository
- **Remote**: git@github.com:jstefani/xeek.git
- **Production Branch**: `Sub-site-support`
- **Beta Branch**: `beta`

## Database Configuration

### Production Database
- **Database Name**: `metajack_marketplace`
- **User**: `mjack`
- **Host**: localhost
- **Port**: 3306

### Beta Database
- **Database Name**: `metajack_marketplace_beta`
- **User**: `mjack`
- **Host**: localhost
- **Port**: 3306

## File Storage

### AWS S3 Configuration
Images are stored in AWS S3. Configuration in `.env`:
- `AWS_ACCESS_KEY_ID`
- `AWS_SECRET_ACCESS_KEY`
- `AWS_DEFAULT_REGION`
- `AWS_BUCKET`

See `S3_SETUP.md` for detailed setup instructions.

### Local Storage
- **Storage Path**: `/var/www/html/storage/app/public`
- **Public Symlink**: `/var/www/html/public/storage`
- Created with: `php artisan storage:link`

## SSL Certificates

### Production (xeek.com)
- **Certificate**: Let's Encrypt
- **Domains**: xeek.com, www.xeek.com
- **Expiry**: January 23, 2026
- **Auto-renewal**: Enabled (certbot systemd timer)
- **Certificate Path**: `/etc/letsencrypt/live/xeek.com/`

### Beta (hound.xeek.com)
- **Certificate**: Let's Encrypt
- **Domain**: hound.xeek.com
- **Expiry**: January 23, 2026
- **Auto-renewal**: Enabled (certbot systemd timer)
- **Certificate Path**: `/etc/letsencrypt/live/hound.xeek.com/`

## Apache Configuration

### Production VirtualHost
- **Config File**: `/etc/apache2/sites-available/my-laravel-app.conf`
- **SSL Config**: `/etc/apache2/sites-available/my-laravel-app-le-ssl.conf`
- **Document Root**: `/var/www/html/public`
- **Log Files**:
  - Error: `/var/log/apache2/xeek-error.log`
  - Access: `/var/log/apache2/xeek-access.log`

### Beta VirtualHost
- **Config File**: `/etc/apache2/sites-available/hound.xeek.com.conf`
- **SSL Config**: `/etc/apache2/sites-available/hound.xeek.com-le-ssl.conf`
- **Document Root**: `/var/www/hound/public`
- **Log Files**:
  - Error: `/var/log/apache2/hound-error.log`
  - Access: `/var/log/apache2/hound-access.log`

## Deployment

### Initial Setup
```bash
# Clone repository
git clone git@github.com:jstefani/xeek.git /var/www/html

# Install dependencies
cd /var/www/html
php composer.phar install
npm install
npm run build

# Configure environment
cp .env.example .env
php artisan key:generate

# Set up database
php artisan migrate
php artisan db:seed

# Set permissions
chown -R www-data:www-data /var/www/html
chmod -R 775 storage bootstrap/cache

# Create storage symlink
php artisan storage:link
```

### Updating Production
```bash
cd /var/www/html

# Pull latest changes
git pull origin Sub-site-support

# Update dependencies
php composer.phar install --no-dev --optimize-autoloader
npm install
npm run build

# Run migrations
php artisan migrate --force

# Clear caches
php artisan config:cache
php artisan route:cache
php artisan view:cache

# Signal queue workers to pick up new code
php artisan queue:restart

# Restart services if needed
sudo systemctl reload apache2
```

### Deploying to Beta
```bash
cd /var/www/hound

# Pull/merge changes from development branch
git pull origin beta

# Update dependencies
php composer.phar install
npm install
npm run build

# Run migrations on beta database
php artisan migrate

# Clear caches
php artisan config:clear
php artisan route:clear
php artisan view:clear

# Signal queue workers to pick up new code
php artisan queue:restart
```

## Queue Workers

Notifications (offers, messages, sales, etc.) are queued (`QUEUE_CONNECTION=database`)
and processed by systemd-managed workers, one per environment:

- **Production**: `laravel-queue-production.service` (WorkingDirectory `/var/www/html`)
- **Beta**: `laravel-queue-beta.service` (WorkingDirectory `/var/www/hound`)

Workers are installed/updated via ansible (`devops/roles/queue_worker`):
```bash
cd devops
ansible-playbook playbooks/site.yml --tags queue            # both environments
ansible-playbook playbooks/site.yml --tags queue --limit production
```

Operations:
```bash
# Status / logs
sudo systemctl status laravel-queue-production
tail -f /var/www/html/storage/logs/queue-worker.log

# After every deploy (already in deploy scripts / ansible role):
php artisan queue:restart   # workers finish current job, systemd restarts them

# Check for stuck/failed jobs
php artisan queue:failed
```

## Scheduled Tasks

Scheduled tasks are defined in `routes/console.php` (currently
`transactions:auto-close`, daily at 06:00) and run via a `schedule:run` cron
entry installed by ansible (`devops/roles/scheduler`):

```bash
cd devops
ansible-playbook playbooks/site.yml --tags scheduler

# Inspect the schedule
php artisan schedule:list
```

## Common Artisan Commands

### Database
```bash
# Run migrations
php artisan migrate

# Rollback last migration
php artisan migrate:rollback

# Reset database (WARNING: deletes all data)
php artisan migrate:fresh

# Seed database
php artisan db:seed

# Create database backup
./backup_database.sh
```

### Cache Management
```bash
# Clear all caches
php artisan cache:clear
php artisan config:clear
php artisan route:clear
php artisan view:clear

# Cache for production
php artisan config:cache
php artisan route:cache
php artisan view:cache
```

### User Management
```bash
# Make user admin
php artisan make:user:admin

# Create new user
php artisan tinker
>>> User::create(['name' => '...', 'email' => '...', 'password' => bcrypt('...')]);
```

## Maintenance

### Database Backups
```bash
# Manual backup
./backup_database.sh

# Backups stored in ./backups/
```

### SSL Certificate Renewal
Certificates auto-renew via certbot systemd timer. To manually renew:
```bash
sudo certbot renew
sudo systemctl reload apache2
```

### Log Files
```bash
# Laravel logs
tail -f storage/logs/laravel.log

# Apache logs
tail -f /var/log/apache2/xeek-error.log
tail -f /var/log/apache2/xeek-access.log

# Beta logs
tail -f /var/log/apache2/hound-error.log
```

### Monitoring
```bash
# Check Apache status
sudo systemctl status apache2

# Check disk space
df -h

# Check database
mysql -u mjack -p metajack_marketplace
```

## Item Status Reference

The admin items page (`/admin/items`) uses different statuses to manage item visibility and moderation:

- **Active**: Item is visible to public and ready for sale/trade
- **Draft**: Item saved but not yet published
- **Sale Pending**: Item sale is in progress
- **Sold**: Item has been sold
- **Archived**: Item is hidden but kept for record-keeping. Use when items are completed or seller wants to hide them without moderation intervention. Can be manually restored via Quick Edit form.
- **Flagged**: Item marked for admin review due to potential policy violations
- **Removed**: Item hidden due to policy violations or moderation action. Includes optional admin reason/note. Shows "Restore" button to revert to active status.

### Admin Actions on Items

- **Remove**: Soft-delete that sets status to "removed", hides item from public, preserves all data in database, allows admin to record a reason, reversible via Restore button
- **Delete**: Hard-delete that permanently removes item record and all associated photos from database and storage, not reversible except via database backup

## Development Workflow

### Creating Features
1. Work on `beta` branch in `/var/www/hound`
2. Test thoroughly at https://hound.xeek.com
3. Merge to `Sub-site-support` when ready
4. Deploy to production

### Git Workflow
```bash
# Create feature branch
git checkout -b feature/new-feature

# Make changes and commit
git add .
git commit -m "Add new feature"

# Push to remote
git push origin feature/new-feature

# Merge to beta for testing
git checkout beta
git merge feature/new-feature
git push origin beta

# Deploy to beta server
cd /var/www/hound
git pull origin beta
# ... (update dependencies, migrate, etc.)
```

## Troubleshooting

### Common Issues

**500 Internal Server Error**
- Check Laravel logs: `tail -f storage/logs/laravel.log`
- Check Apache logs: `tail -f /var/log/apache2/xeek-error.log`
- Verify permissions: `chown -R www-data:www-data storage bootstrap/cache`
- Clear caches: `php artisan cache:clear`

**CSS/JS Not Loading**
```bash
npm run build
php artisan view:clear
```

**Database Connection Error**
- Verify `.env` database credentials
- Check MySQL is running: `sudo systemctl status mysql`
- Test connection: `mysql -u mjack -p metajack_marketplace`

**Storage/Upload Issues**
- Verify symlink exists: `ls -la public/storage`
- Recreate if needed: `php artisan storage:link`
- Check S3 credentials in `.env`
- Verify permissions: `chmod -R 775 storage`

**Apache Not Starting**
```bash
# Test configuration
sudo apache2ctl configtest

# Check enabled sites
ls -la /etc/apache2/sites-enabled/

# Restart Apache
sudo systemctl restart apache2
```

## Security Notes

### Sensitive Files
The following files contain sensitive information and should **never** be committed:
- `.env` (environment configuration)
- `*.sql` (database backups)
- Storage directory contents

### Git Configuration
`.gitignore` is configured to exclude:
- `.env` files
- `node_modules/`
- `vendor/` (Composer dependencies)
- `*.sql` backup files
- Storage and cache directories

### File Permissions
- Application files: `644` (files) / `755` (directories)
- Storage/cache: `775` (allows web server writes)
- Shell scripts: `755` (executable)
- `.env` file: `600` or `644` (readable by web server)

## Additional Documentation

- **README.md**: General Laravel information
- **README.dev**: Development environment setup
- **S3_SETUP.md**: AWS S3 configuration for image storage
- **deploy.txt**: Deployment notes
- **darkmode.txt**: Dark mode implementation notes

## Support

For issues or questions, contact the development team or refer to:
- Laravel Documentation: https://laravel.com/docs
- Project Repository: https://github.com/jstefani/xeek

---

**Last Updated**: October 25, 2025
**Environment**: Production (xeek.com)
**Claude Code**: This documentation was generated with assistance from Claude Code