Geezap Job Aggregator

A comprehensive job aggregation platform that consolidates job listings from multiple sources (LinkedIn, Upwork, Indeed, ZipRecruiter) into one unified search interface with AI-powered features.

⚡ Ultra-Fast Search Performance

NEW: Revolutionary search experience with sub-200ms response times - that's 4000%+ faster than traditional APIs!

• Direct Client Integration: Browser connects directly to Typesense server
• Secure Architecture: Scoped API keys with automatic rotation
• Zero Server Load: Search operations bypass Laravel entirely
• Real-time Suggestions: Instant search-as-you-type functionality

Architecture Comparison:

Traditional (SLOW - 8+ seconds):
User → Laravel API → Database Query → Response

Ultra-Fast (NEW - <200ms):
User → Direct Typesense Client → Instant Results ⚡

---

Quick Start Installation

Prerequisites

Ensure your system has:

• PHP 8.2 or higher
• Composer
• Node.js 18+ and npm
• MySQL 8.0+
• Redis server
• Typesense 27.1+ server (for ultra-fast search functionality)

Step 1: Download and Setup

git clone https://github.com/theihasan/geezap.git
cd geezap
composer install
npm install

Step 2: Environment Configuration

cp .env.example .env
php artisan key:generate

Step 3: Database Setup

Create a MySQL database and update your .env file:

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=geezap
DB_USERNAME=your_username
DB_PASSWORD=your_password

Run database migrations:

php artisan migrate
php artisan db:seed

Step 4: Build Assets

npm run build

Step 5: Start Background Services

The application requires multiple background services to function properly:

# Terminal 1 - Main application
php artisan serve

# Terminal 2 - Typesense server (required for ultra-fast search)
./typesense-server --data-dir=/tmp/typesense-data --api-key=your-api-key

# Terminal 3 - Queue worker (required for job processing)
php artisan queue:work

# Terminal 4 - WebSocket server (required for real-time features)
php artisan reverb:start (### Currently Not Running)

# Terminal 5 - Scheduler (required for automated job fetching)
php artisan schedule:work

After starting Typesense, index your job listings:

# Import job listings to Typesense for search functionality
php artisan scout:import "App\Models\JobListing"

Step 6: Initial Admin Setup

1. Access admin panel at: http://localhost:8000/geezap -Admin Email: admin@geezap.com -password: password
2. Default admin credentials are created by the seeder
3. Add job categories via: /geezap/job-categories
4. Configure API keys via: /geezap/api-keys

Required API Credentials

Essential Services

AI Service (Choose One):

# OpenAI (Recommended)
OPENAI_API_KEY=sk-your-openai-key

# Or Gemini
GEMINI_API_KEY=your-gemini-key

# Or DeepSeek
DEEPSEEK_API_KEY=your-deepseek-key

Bot Protection (Required):

CLOUDFLARE_TURNSTILE_SITE_KEY=your-site-key
CLOUDFLARE_TURNSTILE_SECRET_KEY=your-secret-key

Get Cloudflare Turnstile keys from: https://dash.cloudflare.com/

Email Configuration

Configure email service for user notifications:

# Primary email service (Brevo/Sendinblue)
BREVO_API_KEY=your-brevo-key
BREVO_SMTP_HOST=smtp-relay.brevo.com
BREVO_SMTP_PORT=587
BREVO_SMTP_ENCRYPTION=tls
BREVO_SMTP_USERNAME=your-brevo-username
BREVO_SMTP_PASSWORD=your-brevo-password

# Backup email service (Resend)
RESEND_KEY=your-resend-key

# Or use ZeptoMail
ZEPTO_SMTP_HOST=smtp.zeptomail.com
ZEPTO_SMTP_PORT=587
ZEPTO_SMTP_ENCRYPTION=tls
ZEPTO_SMTP_USERNAME=your-zepto-username
ZEPTO_SMTP_PASSWORD=your-zepto-password

Typesense Search Configuration

Ultra-Fast Search Engine: Typesense provides instant search results with <200ms response times.

# Typesense Configuration (Required for search functionality)
TYPESENSE_API_KEY=your-typesense-admin-key
TYPESENSE_HOST=localhost
TYPESENSE_PORT=8108
TYPESENSE_PROTOCOL=http

# Optional: Search-only key for enhanced security
TYPESENSE_SEARCH_ONLY_API_KEY=your-read-only-key

Typesense Installation:

1. Install Typesense Server:

   # Using Docker (Recommended)
   docker run -d \
     --name typesense \
     -p 8108:8108 \
     -v typesense-data:/data \
     typesense/typesense:27.1 \
     --data-dir /data \
     --api-key=your-api-key \
     --enable-cors
   
   # Or install directly
   curl -O https://dl.typesense.org/releases/27.1/typesense-server-27.1-linux-amd64.tar.gz
   tar -xzf typesense-server-27.1-linux-amd64.tar.gz
   ./typesense-server --data-dir=/tmp/typesense-data --api-key=your-api-key
   

2. Configure Laravel Scout:

   # Install required packages
   composer require laravel/scout typesense/typesense-php
   
   # Publish Scout configuration
   php artisan vendor:publish --provider="Laravel\Scout\ScoutServiceProvider"
   

3. Index Job Listings:

   # Create the search index and import all job listings
   php artisan scout:import "App\Models\JobListing"
   
   # Check indexing status
   php artisan tinker
   >>> \App\Models\JobListing::search('*')->count()
   

Security Features:

• Scoped API Keys: Automatic generation of search-only keys with 24-hour TTL
• Admin Key Protection: Admin API keys are never exposed to frontend clients
• Role-Based Access: Admin-only endpoints for key management
• Secure Caching: Search keys cached for optimal performance with security

Search Performance:

• Direct Client Integration: Frontend bypasses slow server APIs for instant results
• Response Times: Sub-200ms search responses (4000%+ faster than traditional APIs)
• Real-time Suggestions: Ultra-fast search-as-you-type functionality
• Grouped Results: Organized search results with faceting support

API Endpoints:

• GET /api/typesense/config - Public endpoint returning secure search configuration
• POST /api/typesense/refresh-key - Admin-only endpoint for manual key refresh

Frontend Integration:

The application includes a TypesenseSearch JavaScript class that automatically:

1. Fetches secure configuration from /api/typesense/config
2. Initializes direct Typesense client connection
3. Provides ultra-fast search suggestions on the homepage
4. Handles errors gracefully with fallback mechanisms

Social Authentication (Optional)

# GitHub OAuth
GITHUB_CLIENT_ID=your-github-client-id
GITHUB_CLIENT_SECRET=your-github-client-secret

# Google OAuth
GOOGLE_CLIENT_ID=your-google-client-id
GOOGLE_CLIENT_SECRET=your-google-client-secret

Redis Configuration

For production environments with separate Redis instances:

REDIS_CLIENT=predis
REDIS_HOST=127.0.0.1
REDIS_PASSWORD=null
REDIS_PORT=6379
REDIS_SCHEME=tls

Production Deployment

Server Requirements

• Web Server: Nginx with Laravel configuration
• PHP: 8.2+ with extensions: PDO, MySQL, Curl, OpenSSL, JSON, Tokenizer, XML, Ctype, BCMath
• Database: MySQL 8.0+ or MariaDB 10.3+
• Cache: Redis 6.0+
• Memory: Minimum 2GB RAM (4GB+ recommended)
• Storage: 10GB+ with room for growth

Production Installation

# Install dependencies
composer install --no-dev --optimize-autoloader
npm ci && npm run build

# Configure environment
cp .env.example .env
# Edit .env with production values
php artisan key:generate

# Database setup
php artisan migrate --force

# Cache optimization
php artisan config:cache
php artisan route:cache
php artisan view:cache
php artisan optimize

File Permissions Setup

Critical: Proper file permissions are essential for the application to function correctly. Run these commands on your production server:

# Set ownership of the application directory
sudo chown -R deploy:www-data /var/www/html/geezap

# Set base permissions for the entire application
sudo chmod -R 755 /var/www/html/geezap

# Set writable permissions for storage and cache directories
sudo chmod -R 775 /var/www/html/geezap/storage
sudo chmod -R 775 /var/www/html/geezap/bootstrap/cache

# Set permissions for public assets
sudo chmod -R 755 /var/www/html/geezap/public

# Ensure web server owns critical directories for write operations
sudo chown -R www-data:www-data /var/www/html/geezap/storage
sudo chown -R www-data:www-data /var/www/html/geezap/bootstrap/cache

Permission Structure Explained:

• 755 (rwxr-xr-x): Owner can read/write/execute, group and others can read/execute
• 775 (rwxrwxr-x): Owner and group can read/write/execute, others can read/execute
• www-data: Web server user that needs write access to logs, cache, and uploaded files
• deploy: Deployment user that owns the application files

Required Directories with Write Permissions:

• storage/ - For logs, cache, sessions, and uploaded files
• storage/logs/ - Application and error logs
• storage/framework/cache/ - Application cache files
• storage/framework/sessions/ - User session data
• storage/framework/views/ - Compiled Blade templates
• bootstrap/cache/ - Configuration and route cache files

Verification: After setting permissions, verify they are correct:

# Check storage directory permissions
ls -la /var/www/html/geezap/storage

# Check bootstrap cache permissions  
ls -la /var/www/html/geezap/bootstrap/cache

# Test write permissions
sudo -u www-data touch /var/www/html/geezap/storage/logs/test.log
sudo rm /var/www/html/geezap/storage/logs/test.log

Common Permission Issues:

• 500 Internal Server Error: Often caused by incorrect file ownership
• Permission Denied: Web server cannot write to storage or cache directories
• Failed to open stream: Log files or cache files cannot be created or accessed

Security Notes:

• Never set 777 permissions on any directory
• Ensure only necessary directories have write permission