Architecture
A deep dive into the architectural design and module structure of Omega Shop.
Overview
Omega Shop follows a layered Laravel architecture with an API-first design. The versioned REST API (v1) serves as the primary interface for the companion mobile app, while the Filament v5 admin panel provides a web-based management interface. External integrations (Shopify, WooCommerce) communicate via webhooks processed as queued jobs. Stripe sync is handled through model observers, and the Spatie ecosystem provides cross-cutting concerns (permissions, media, activity logging, backups, health checks).
The platform is designed around an API-first philosophy. All core business logic is accessible through the versioned REST API, making it straightforward to build additional clients beyond the existing mobile app and admin panel.
API Layer
Versioned REST API (v1) with Sanctum token authentication.
- 12 API controllers handling auth, products, categories, cart, wishlist, checkout, billing, delivery, purchases, downloads, ratings, and webhooks
- 12 API resource transformers for consistent JSON serialization
- Form request classes for input validation
- Rate limiting per route
Admin Panel
Filament v5 admin dashboard with full CRUD management.
- 13 resources: Products, Users, Purchases, Categories, Ratings, BillingDetails, Companies, Specifications, Roles, Activities, Emails, SMS, Integrations
- Relation managers for nested data
- Bulk CSV import with error reporting
- Health check dashboard
Product Catalog
Multi-type product management system.
- Three product types: License (digital), Solution (service), Physical
- Three license tiers: Standard, Extended, Unlimited with per-tier pricing
- Spatie Media Library for image galleries and file attachments
- Product specifications (key-value pairs)
- Category hierarchy with parent/child relationships
- Meilisearch-powered full-text search via Laravel Scout
Commerce Engine
Shopping cart, wishlist, checkout, and order management.
- Persistent cart (authenticated) and session cart (anonymous)
- Wishlist with move-to-cart functionality
- Multi-step checkout with billing detail and delivery address selection
- Purchase lifecycle:
Pending→Processing→Completed/Refunded/Failed/Cancelled - Invoice PDF generation via Dompdf
Payment Processing
Stripe integration via Laravel Cashier v16.
- Automatic product and price sync to Stripe on approval
- Payment intent creation and tracking
- Webhook handling for payment events
- Subscription support
- Invoice generation
Products are automatically synced to Stripe when approved by an admin. The ProductObserver handles creating and updating Stripe products and prices whenever the local model changes.
Digital Delivery
License management and secure file distribution.
- License key generation per purchase
- Download tracking with count limits and expiration dates
- Signed URL generation for secure file access
- ClamAV virus scanning on upload
Integration Hub
Multi-channel commerce via Shopify and WooCommerce.
- Integration configuration and API key management
- Product mapping between internal and external catalogs
- Queued sync jobs:
SyncIntegrationProducts,SyncIntegrationOrders,SyncIntegrationInventory - Webhook receivers for incoming updates
- Retry logic with 3 attempts and 60s backoff
Authentication & Authorization
Multi-method auth with role-based access control.
- Email/password registration with email verification
- Social login via Google and Facebook (Laravel Socialite)
- API token auth via Laravel Sanctum
- Role-based access control via Spatie Permission (super admin, manager, customer)
- User blocking middleware
Notifications
Email and SMS communication system.
- Purchase placed and purchase completed email notifications
- Cart and wishlist reminder campaign emails
- Newsletter dispatch system
- Low stock product notifications
- SMS via Vonage
- Email and SMS logging with 90-day auto-pruning
Observability
Monitoring, logging, and debugging infrastructure.
- Sentry — Error tracking (server and browser)
- Laravel Telescope — Local debugging
- Spatie Activity Log — Audit trails
- Spatie Health — Health checks dashboard
- OpCodes Log Viewer — Server logs
- Laravel Horizon — Queue monitoring