Omega Docs
Omega Docs

Development

Commands, project structure, and deployment workflow for Omega Shop.

Development Commands

Setup & Server

# Install PHP dependencies
composer install

# Install Node.js dependencies
npm install

Database

# Run database migrations
php artisan migrate

# Reset database and seed with test data
php artisan migrate:fresh --seed

Testing

# Run the full Pest test suite
php artisan test --compact

# Run a specific test or filter
php artisan test --compact --filter=testName

Queue & Search

# Start the Horizon queue worker
php artisan horizon

Product Export & Campaigns

# Export product catalog as JSON
php artisan app:export-products-json

# Export product catalog as XML
php artisan app:export-products-xml

# Export product catalog as CSV
php artisan app:export-products-csv

Project Structure

PathDescription
app/Models/27 Eloquent models: User, Product, Purchase, Cart, Wishlist, Category, BillingDetail, DeliveryAddress, Payment, Download, Rating, Company, Specification, Integration, ProductMapping, NewsletterSubscriber, and pivot models
app/Http/Controllers/Api/V1/12 versioned API controllers handling auth, products, categories, cart, wishlist, checkout, billing, delivery, purchases, downloads, ratings
app/Http/Controllers/WebhookController for Shopify/WooCommerce, DownloadController for file delivery
app/Http/Resources/Api/V1/12 API resource transformers for consistent JSON output
app/Http/Requests/Api/V1/Form request classes for API input validation
app/Filament/Resources/13 Filament admin resources with forms, tables, relation managers, and page classes
app/Jobs/4 queue jobs: SyncIntegrationProducts, SyncIntegrationOrders, SyncIntegrationInventory, ScanUploadedFile
app/Mail/5 mailable classes: PurchasePlaced, PurchaseCompleted, NewsletterMail, CartAndWishlistReminder, ResendMail
app/Notifications/LowStockNotification for alerting admins about low inventory
app/Observers/3 model observers: ProductObserver (Stripe sync), CategoryObserver, UserObserver
app/Enums/7 enums: ProductType, LicenseType, PurchaseStatus, Platform, NewsletterSubscriptionStatus, RatingEnum, and more
PathDescription
app/Services/VirusScanService for ClamAV file scanning with quarantine support
app/Console/Commands/9 Artisan commands for export, newsletter, reminders, platform sync, search index management, and quarantine cleanup
database/migrations/52 migration files defining the complete database schema
database/factories/Model factories for testing and seeding
database/seeders/Database seeders for development and testing data
routes/api.phpVersioned API routes (v1) with public and Sanctum-protected groups
routes/web.phpWeb routes for admin redirect, email verification, downloads, and logout
resources/views/Blade templates for email notifications, components, and mobile deep-link redirects
config/34 config files including custom: integrations.php, mobile.php, clamav.php
tests/Pest v3 test suite with feature and unit tests, plus Dusk browser tests
Envoy.blade.phpZero-downtime deployment script with CI/CD gate, symlink releases, and old release cleanup

Deployment

Omega Shop uses a zero-downtime deployment strategy powered by Laravel Envoy with symlink-based releases.

Prerequisites

Before deploying, ensure the production server has the following installed:

  • PHP 8.3-FPM
  • Composer
  • Node.js and npm
  • Redis
  • MySQL

The Envoy deployment script automatically checks that all CI/CD tests pass before proceeding. If the CI gate fails, the deployment will be aborted.

Deployment Steps

  1. Ensure all CI/CD tests pass on the main branch (Envoy checks this automatically).
  2. Configure deployment environment variables in .env: DEPLOY_USER, DEPLOY_HOST, DEPLOY_REPOSITORY, DEPLOY_APP_DIR, DEPLOY_RELEASE_DIR, DEPLOY_BRANCH.
  3. Set up the shared .env file on the server at DEPLOY_APP_DIR/.env with production credentials.
  4. Set up the shared storage directory at DEPLOY_APP_DIR/storage with proper permissions (775, owned by deploy-user:www-data).
  5. Run the deployment:
php vendor/bin/envoy run deploy

What the Envoy Script Does

The deployment script automatically performs the following steps:

  1. Checks CI status via GitHub CLI
  2. Clones the repository to a timestamped release directory
  3. Symlinks shared storage and .env
  4. Runs composer install and Laravel optimization commands
  5. Runs npm install and npm run build
  6. Atomically switches the current symlink to the new release
  7. Reloads PHP-FPM
  8. Cleans up old releases (keeps last 5)

Post-Deployment Configuration

After the first deployment, complete these additional steps:

  • Configure Nginx to point to DEPLOY_APP_DIR/current/public as the document root
  • Set up a cron job for the Laravel scheduler: * * * * * cd /path/to/current && php artisan schedule:run >> /dev/null 2>&1
  • Start Laravel Horizon for queue processing: php artisan horizon (use Supervisor to keep it running)
  • Configure Stripe webhooks to point to your production URL
  • Set up Meilisearch and run php artisan scout:import to index products

To rollback a deployment, push a correcting commit and redeploy. Previous releases are retained on the server for reference.

Was this page helpful?