jobifygarden/README.md

# JobifyGarden

A comprehensive job aggregator platform built with Laravel 13 that fetches, stores, and displays job listings from multiple free job APIs.

## Quick Start

```bash
# Clone repository
git clone <repository-url> && cd jobifygarden

# Install dependencies
composer install

# Start Docker environment (includes MySQL, Redis)
./vendor/bin/sail up -d

# Setup application
./vendor/bin/sail artisan key:generate
./vendor/bin/sail artisan migrate
./vendor/bin/sail artisan db:seed

# Install & build frontend assets
./vendor/bin/sail npm install && ./vendor/bin/sail npm run dev

# Start queue worker (in a separate terminal)
./vendor/bin/sail artisan queue:work

# Visit http://localhost
```

**Important:** After setup, configure the cron job (see [Cron Jobs](#cron-jobs-required) section) to enable automatic job fetching.

## Requirements

- **PHP**: 8.3.x or higher
- **MySQL**: 8.0+ or MariaDB 10.3+
- **Composer**: 2.x
- **Node.js**: 18.x or 20.x
- **Redis**: 6.x+ (for caching and queues)

## Features

### Core Functionality
- **Multi-Source Job Aggregation**: Fetch jobs from multiple APIs
- **Advanced Search & Filtering**: Full-text search, location, job type, experience level, salary range
- **Smart Deduplication**: Automatic detection and removal of duplicate listings
- **Job Enrichment**: Auto-categorization, geocoding, salary normalization
- **Real-time Analytics**: Track job views, searches, and user engagement

### SEO & Marketing
- **Dynamic Meta Tags**: Job-specific title, description, and keywords
- **Structured Data**: Schema.org JobPosting markup for Google Jobs integration
- **XML Sitemaps**: Automatic sitemap generation for search engines
- **Social Sharing**: Open Graph and Twitter Card support
- **Mobile-First**: Responsive design optimized for all devices

### Performance
- **Redis Caching**: Aggressive caching strategy for fast page loads
- **Database Optimization**: Proper indexing and query optimization
- **Queue Processing**: Background job processing for API fetching
- **Asset Optimization**: Minified CSS/JS with lazy loading

### Monitoring & Analytics
- **API Metrics**: Track success rates, response times, errors
- **User Analytics**: Popular searches, viewed jobs, click-through rates
- **Admin Dashboard**: Real-time monitoring and statistics
- **Error Tracking**: Comprehensive logging and error handling

## Installation

### Development Setup (Laravel Sail - Recommended)

1. **Clone the repository**
```bash
git clone <repository-url>
cd jobifygarden
```

2. **Install PHP dependencies**
```bash
composer install
```

3. **Copy environment file**
```bash
cp .env.example .env
```

4. **Configure environment variables**
Edit `.env` and update the following:
```env
APP_NAME=JobifyGarden
APP_ENV=local
APP_DEBUG=true
APP_URL=http://localhost

# Database (Sail uses these defaults)
DB_CONNECTION=mysql
DB_HOST=mysql
DB_PORT=3306
DB_DATABASE=jobifygarden
DB_USERNAME=sail
DB_PASSWORD=password

# Cache & Sessions (Redis)
CACHE_STORE=redis
SESSION_DRIVER=redis
QUEUE_CONNECTION=redis

# Redis (Sail default)
REDIS_HOST=redis
REDIS_PASSWORD=null
REDIS_PORT=6379
```

5. **Start Docker containers**
```bash
./vendor/bin/sail up -d
```

6. **Generate application key**
```bash
./vendor/bin/sail artisan key:generate
```

7. **Run database migrations**
```bash
./vendor/bin/sail artisan migrate
```

8. **Seed initial data (optional)**
```bash
./vendor/bin/sail artisan db:seed
```

9. **Install frontend dependencies and build assets**
```bash
./vendor/bin/sail npm install
./vendor/bin/sail npm run dev
```

10. **Visit the application**
Open `http://localhost` in your browser.

### Production Setup (Traditional Server)

1. **Clone the repository**
```bash
git clone <repository-url>
cd jobifygarden
```

2. **Install dependencies**
```bash
composer install --optimize-autoloader --no-dev
npm install
npm run build
```

3. **Configure environment**
```bash
cp .env.example .env
php artisan key:generate
```

4. **Update `.env` for production**
```env
APP_NAME=JobifyGarden
APP_ENV=production
APP_DEBUG=false
APP_URL=https://yourdomain.com

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=jobifygarden
DB_USERNAME=your_username
DB_PASSWORD=your_secure_password

CACHE_STORE=redis
SESSION_DRIVER=redis
QUEUE_CONNECTION=redis

REDIS_HOST=127.0.0.1
REDIS_PASSWORD=your_redis_password
REDIS_PORT=6379
```

5. **Run migrations**
```bash
php artisan migrate --force
```

6. **Optimize for production**
```bash
php artisan config:cache
php artisan route:cache
php artisan view:cache
php artisan optimize
```

7. **Set proper permissions**
```bash
chown -R www-data:www-data storage bootstrap/cache
chmod -R 775 storage bootstrap/cache
```

## Production Deployment

See [DEPLOYMENT.md](DEPLOYMENT.md) for detailed production deployment instructions.

## Required Services

### Queue Worker (Required)

The application uses queues for background job processing. You must run a queue worker:

**Using Laravel Sail (Development):**
```bash
./vendor/bin/sail artisan queue:work --sleep=3 --tries=3 --timeout=90
```

**Using Supervisor (Production with Supervisor):**
Create `/etc/supervisor/conf.d/jobifygarden-worker.conf`:
```ini
[program:jobifygarden-worker]
process_name=%(program_name)s_%(process_num)02d
command=php /path/to/jobifygarden/artisan queue:work redis --sleep=3 --tries=3 --max-time=3600
autostart=true
autorestart=true
stopasgroup=true
killasgroup=true
user=www-data
numprocs=2
redirect_stderr=true
stdout_logfile=/path/to/jobifygarden/storage/logs/worker.log
stopwaitsecs=3600
```

Then reload supervisor:
```bash
sudo supervisorctl reread
sudo supervisorctl update
sudo supervisorctl start jobifygarden-worker:*
```

**Using Cron (Production without Supervisor):**
If your hosting provider doesn't have Supervisor, see [CRON_SETUP.md](CRON_SETUP.md) for detailed cron-based setup instructions.

### Cron Jobs (Required)

Laravel's task scheduler must run every minute. Add this to your crontab:

**Edit crontab:**
```bash
crontab -e
```

**Add this line:**
```bash
* * * * * cd /path/to/jobifygarden && php artisan schedule:run >> /dev/null 2>&1
```

**For Laravel Sail (Development):**
```bash
* * * * * cd /path/to/jobifygarden && ./vendor/bin/sail artisan schedule:run >> /dev/null 2>&1
```

### Scheduled Tasks

The following tasks are automatically scheduled and will run via the cron job above:

| Task | Schedule | Description |
|------|----------|-------------|
| `jobs:fetch` | Every 2 hours | Fetch new jobs from all API sources |
| `jobs:clean` | Daily at 3:00 AM | Remove expired and old jobs |
| `jobs:deduplicate` | Daily at 4:00 AM | Remove duplicate job listings |
| `cache:prune-stale-tags` | Hourly | Clean up stale cache tags |

**Note:** Job fetching intervals can be customized in `app/Console/Kernel.php`

## Available Commands

### Job Management
```bash
# Fetch jobs from all sources (automatically scheduled)
php artisan jobs:fetch

# Fetch from a specific source
php artisan jobs:fetch --source=indeed

# Clean expired jobs (automatically scheduled)
php artisan jobs:clean

# Clean jobs older than specific days
php artisan jobs:clean --days=60

# Remove duplicate jobs (automatically scheduled)
php artisan jobs:deduplicate

# Force dedupe even with different sources
php artisan jobs:deduplicate --force

# Enrich job data (categories, experience levels)
php artisan jobs:enrich

# Test API integrations
php artisan jobs:test-apis
```

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

# Rollback last migration
php artisan migrate:rollback

# Fresh migration with seeding
php artisan migrate:fresh --seed

# Optimize database tables
php artisan db:optimize
```

### Cache Management
```bash
# Clear all caches
php artisan optimize:clear

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

# Build caches for production
php artisan optimize
```

### Queue Management
```bash
# Start queue worker
php artisan queue:work

# Process jobs with options
php artisan queue:work --queue=high,default --sleep=3 --tries=3

# List failed jobs
php artisan queue:failed

# Retry all failed jobs
php artisan queue:retry all

# Retry specific failed job
php artisan queue:retry {id}

# Clear all failed jobs
php artisan queue:flush
```

## Project Structure

```
app/
├── Console/Commands/      # Artisan commands
├── Http/Controllers/      # Web and API controllers
├── Models/               # Eloquent models
├── Repositories/         # Data access layer
├── Services/             # Business logic
└── Traits/               # Reusable traits

database/
├── migrations/           # Database migrations
└── seeders/             # Database seeders

resources/
├── views/               # Blade templates
├── js/                  # JavaScript files
└── css/                 # CSS files

routes/
├── web.php              # Web routes
└── api.php              # API routes
```

## API Endpoints

### Public API
```
GET  /api/jobs                    # List jobs with filters
GET  /api/jobs/{id}               # Get job details
GET  /api/categories              # List categories
GET  /api/jobs/autocomplete/titles      # Title autocomplete
GET  /api/jobs/autocomplete/locations   # Location autocomplete
GET  /api/jobs/autocomplete/companies   # Company autocomplete
```

## Technology Stack

### Backend
- **Laravel 13**: PHP framework
- **PHP 8.3+**: Programming language
- **MySQL 8**: Primary database
- **Redis**: Caching, sessions, and queues
- **Guzzle**: HTTP client for API requests

### Frontend
- **Blade Templates**: Server-side rendering
- **Alpine.js**: Lightweight JavaScript framework
- **TailwindCSS**: Utility-first CSS framework
- **Vite**: Frontend build tool

### DevOps
- **Laravel Sail**: Docker development environment
- **Supervisor**: Process manager for queue workers
- **Nginx/Apache**: Web server
- **Certbot**: SSL certificate management

## Troubleshooting

### Common Issues

**1. Queue jobs not processing**
```bash
# Check if queue worker is running
ps aux | grep "queue:work"

# Restart queue worker (Supervisor)
sudo supervisorctl restart jobifygarden-worker:*

# Or start manually for debugging
php artisan queue:work --verbose
```

**2. Jobs not being fetched automatically**
```bash
# Verify cron is set up
crontab -l

# Test schedule manually
php artisan schedule:run

# Check schedule list
php artisan schedule:list
```

**3. Redis connection errors**
```bash
# Check Redis is running
redis-cli ping

# For Sail
./vendor/bin/sail redis redis-cli ping

# Restart Redis (Sail)
./vendor/bin/sail down
./vendor/bin/sail up -d
```

**4. Permission errors**
```bash
# Fix storage permissions
sudo chown -R www-data:www-data storage bootstrap/cache
sudo chmod -R 775 storage bootstrap/cache

# For development (use your user)
sudo chown -R $USER:$USER storage bootstrap/cache
chmod -R 775 storage bootstrap/cache
```

**5. Slugs not generating for new jobs**
```bash
# Regenerate slugs for existing jobs
php artisan tinker
# Then run:
# \App\Models\Job::whereNull('slug')->chunk(100, function($jobs) {
#     foreach($jobs as $job) {
#         $job->slug = \App\Models\Job::generateUniqueSlug($job->title, $job->company);
#         $job->save();
#     }
# });
```

**6. Cache issues**
```bash
# Clear all caches
php artisan optimize:clear

# Rebuild for production
php artisan optimize
```

### Performance Tips

1. **Enable OPcache in production** (add to `php.ini`):
```ini
opcache.enable=1
opcache.memory_consumption=256
opcache.interned_strings_buffer=16
opcache.max_accelerated_files=20000
opcache.validate_timestamps=0
```

2. **Optimize database queries:**
```bash
php artisan db:optimize
```

3. **Use queue workers with multiple processes:**
```bash
# Update supervisor config to use more workers
numprocs=4
```

4. **Monitor slow queries:**
```bash
# Enable query logging in .env
DB_LOG_QUERIES=true
```

## License

This project is open-sourced software licensed under the [MIT license](https://opensource.org/licenses/MIT).

---

## About Laravel

Laravel is a web application framework with expressive, elegant syntax. We believe development must be an enjoyable and creative experience to be truly fulfilling. Laravel takes the pain out of development by easing common tasks used in many web projects, such as:

- [Simple, fast routing engine](https://laravel.com/docs/routing).
- [Powerful dependency injection container](https://laravel.com/docs/container).
- Multiple back-ends for [session](https://laravel.com/docs/session) and [cache](https://laravel.com/docs/cache) storage.
- Expressive, intuitive [database ORM](https://laravel.com/docs/eloquent).
- Database agnostic [schema migrations](https://laravel.com/docs/migrations).
- [Robust background job processing](https://laravel.com/docs/queues).
- [Real-time event broadcasting](https://laravel.com/docs/broadcasting).

Laravel is accessible, powerful, and provides tools required for large, robust applications.

## Learning Laravel

Laravel has the most extensive and thorough [documentation](https://laravel.com/docs) and video tutorial library of all modern web application frameworks, making it a breeze to get started with the framework.

In addition, [Laracasts](https://laracasts.com) contains thousands of video tutorials on a range of topics including Laravel, modern PHP, unit testing, and JavaScript. Boost your skills by digging into our comprehensive video library.

You can also watch bite-sized lessons with real-world projects on [Laravel Learn](https://laravel.com/learn), where you will be guided through building a Laravel application from scratch while learning PHP fundamentals.

## Agentic Development

Laravel's predictable structure and conventions make it ideal for AI coding agents like Claude Code, Cursor, and GitHub Copilot. Install [Laravel Boost](https://laravel.com/docs/ai) to supercharge your AI workflow:

```bash
composer require laravel/boost --dev

php artisan boost:install
```

Boost provides your agent 15+ tools and skills that help agents build Laravel applications while following best practices.

## Contributing

Thank you for considering contributing to the Laravel framework! The contribution guide can be found in the [Laravel documentation](https://laravel.com/docs/contributions).

## Code of Conduct

In order to ensure that the Laravel community is welcoming to all, please review and abide by the [Code of Conduct](https://laravel.com/docs/contributions#code-of-conduct).

## Security Vulnerabilities

If you discover a security vulnerability within Laravel, please send an e-mail to Taylor Otwell via [taylor@laravel.com](mailto:taylor@laravel.com). All security vulnerabilities will be promptly addressed.

## License

The Laravel framework is open-sourced software licensed under the [MIT license](https://opensource.org/licenses/MIT).