Molnz Technical Documentation

The Settings module serves as the foundational configuration layer of the Molnz platform. It manages all global reference data that other modules depend on — geographic coverage, currency definitions, and live exchange rates. This module contains 4 Eloquent models and 6 controllers, providing a centralized admin dashboard with live entity counts.

Countries & Cities — The module defines the geographic scope of the platform through a hierarchical Country → City structure. Each entity stores bilingual names (name_ar, name_en), an activation toggle (is_active), and a sort_order field for drag-and-drop reordering via SortableJS. Countries also carry an ISO code. Both support search, filtering by status, and bulk reorder operations via AJAX endpoints.

Currencies & Exchange Rates — The platform supports multiple currencies with the Yemeni Rial (YER) as the base. Each Currency stores a code, symbol, decimal precision (up to 8 places), and a formatted label accessor (e.g., "ر.ي YER"). The ExchangeRate model maintains a timestamped history of rates against YER, with a bulk-create interface that allows the admin to update all non-YER currency rates simultaneously with optional notes per entry. The exchange rate index provides both a paginated history and current-rate summary cards.

All controllers follow a consistent pattern: full CRUD + AJAX toggle for activation + drag-and-drop reordering. The admin dashboard (AdminSettingsController) aggregates live counts of countries, cities, currencies, and exchange rates into a single overview.

The Outlets module is the first and largest business vertical of the Molnz super app, powering the "ما تشتهي" (What You Crave) section — the food vendor marketplace. With 11 Eloquent models and 11 controllers, it encompasses the full lifecycle of food outlet management from vendor onboarding to product catalog, pricing, and promotions. While the Outlets module is the first active vertical, it is one of many planned verticals (Stores, Services, Reservations, etc.) that will follow the same architectural patterns.

Outlet Types & Template System — The module uses a two-tier type system. OutletType defines vendor categories (e.g., Restaurants, Cafés, Bakeries) with color coding, images via Spatie Media Library, and activation controls. Each type owns template categories (OutletTypeCategory) and template addons (OutletTypeAddon) that serve as blueprints — when a new outlet is created under a type, these templates can be inherited, giving each outlet a pre-configured menu structure with the flexibility to add custom categories and addons.

Outlets & Profiles — Each Outlet belongs to a type, a user (owner), a city, and a currency. It stores GPS coordinates (latitude, longitude), open/closed status, activation state, and aggregated metrics (total_orders, total_rating). Media collections handle logo and cover images. The companion OutletProfile extends each outlet with a bilingual bio, working days schedule (JSON array), feature list, and a gallery media collection for multiple images.

Products, Options & Addons — Products belong to an outlet and a category, with bilingual names, descriptions, images, and sortable ordering. Instead of a fixed base price, each product defines its pricing through Options (OutletProductOption) — named variants like "Small", "Medium", "Large" — each with its own price and a is_default flag. The effective display price is derived from the default option. Products can also attach Addons (OutletAddon) via a many-to-many pivot, where each addon has its own price, bilingual unit label, and can be either inherited from the outlet type template or custom.

Discount & Coupon System — Both automatic discounts and code-based coupons are unified under a single Discount model with an activation field ("automatic" or "coupon"). The system supports percentage, fixed-amount, and free-delivery value types. Advanced targeting includes: outlet, product, category, and city scoping via pivot tables; audience segmentation (all users, new users, returning users); first-order-only restrictions; minimum order thresholds; per-user and total usage limits; date-range scheduling with day-of-week and time-of-day constraints; and a funding split model that tracks outlet vs. platform contribution percentages. A DiscountUsage model records each redemption with the exact amounts funded by each party.

Orders and Notifications are handled as sub-domains within this module rather than as separate standalone modules, keeping all food-related business logic tightly coupled for consistency and maintainability.

The Users module manages all aspects of user identity, authentication, wallet operations, and profile management across the Molnz platform. With 5 Eloquent models, API and admin controllers, and dedicated Form Requests, it handles the full user lifecycle — from OTP-based phone registration through the mobile app to admin-side user management, wallet operations, and role-based access control.

Authentication — The mobile API uses a three-step OTP flow handled by AuthController: (1) sendOtp generates a time-limited OTP for a phone number with country code, (2) verifyOtp validates the code and issues a Laravel Sanctum personal access token, (3) register completes the profile with name, email, and optional avatar upload. The OTP code and expiry are stored directly on the User model and hidden from serialization for security.

User Profiles & Addresses — Each user has a one-to-one UserProfile storing gender, date of birth, home city, and a separate browsing_city_id for location-aware content delivery. Users can maintain multiple Addresses (UserAddress) with titles, descriptions, phone numbers, GPS coordinates (via Google Maps picker), city associations, address type labels, and a default designation. The model automatically unsets other defaults when a new default is chosen via a saving event hook. Avatar images are managed through Spatie Media Library with a single-file collection.

Wallet System — The module integrates Bavix Laravel Wallet, giving each user a digital wallet with deposit, withdraw, and transfer capabilities. The admin panel provides deposit functionality with required notes, paginated transaction history, and Excel export of transactions via Maatwebsite/Excel. The user detail page displays wallet balance, total deposits, and total withdrawals.

Roles & Permissions — The module integrates with Laratrust for role-based access control. Role and Permission models extend Laratrust's base classes, and the User model uses the HasRolesAndPermissions trait. The admin interface supports assigning roles during user creation and editing, enabling the multi-role architecture needed for customers, vendors, drivers, and administrators.