02 / Overview

Stack, panels, and how a request flows

Technology stack

03 / Overview

Installation on shared hosting and on a dev machine

MONO installs two ways. The web installer is the supported path for shared hosting, where you have a control panel but no shell. The Artisan path is for developers and CI. The walkthrough below was captured on a cPanel account; other control panels follow the same shape.

Part 1 — Create the database in cPanel

1. Open the database manager.

   In cPanel, scroll to the Databases section and open Manage My Databases.

   

2. Create the database.

   Under Create New Database, type a name after your account prefix and click Create Database. cPanel prepends the account prefix — mono becomes something like clotcode_mono. Note the full name; the installer will ask for it exactly.

   

3. Create the database user.

   Scroll to Database Users → Add New User, pick a username, and generate a strong password. Note the username and password too, then click Create User.

   

4. Attach the user to the database.

   In Add User To Database, select the user and the database you just created, and click Add.

   

5. Grant all privileges.

   cPanel opens the privilege screen for that user/database pair. Tick ALL PRIVILEGES, then click Make Changes to save. The installer migrates and seeds through this user, so it needs full rights on this database.

   

Part 2 — Upload and extract the installer

1. Open File Manager.

   In cPanel, open Files → File Manager and enter the document root of the domain you are installing on — public_html for the primary domain, or the subfolder the domain points at.

   

2. Upload the archive.

   Click Upload and select mono-marketplace-installer.zip. Stay on the page until the progress bar reaches 100%.

   

3. Extract it in place.

   Back in File Manager, select the zip, click Extract, keep the destination path /public_html, and click Extract Files. The archive expands into the application tree; delete the zip afterwards to reclaim the space.

   

Part 3 — Run the installer wizard

Visit https://your-domain.com/install.php. If .env is still missing, public/index.php also redirects the storefront's first request there automatically. The wizard is five steps and takes about a minute.

1. Welcome — server requirements.

   The installer checks PHP 8.3+, every required extension, the presence of vendor/, and that storage/, bootstrap/cache/, and .env are writable. When each row reads Ready, continue to the database step.

   

2. Database connection.

   Keep the type on MySQL / MariaDB, leave the host on localhost and the port on 3306 unless your host says otherwise, and enter the database name, username, and password from Part 1. Test connection & create tables verifies the login, writes .env, and runs the migrations. SQLite is also accepted for small or staging installs.

   

3. Site & admin account.

   The site URL is auto-detected — change it only if the store will be served from another address or a subfolder. Set the store name and tagline, then create the first administrator; the account is attached to the super_admin role automatically. Leave Install the current catalog demo ticked if you want starter products, categories, brands, vendors, and bundles to explore.

   

4. Pick a theme.

   Choose one of the nine storefront themes. The installer runs that theme's migrations and copies its assets. You can switch or add themes later in the admin panel under Appearance → Themes.

   

5. Finish.

   The installer writes storage/app/installed.lock and shows your admin login and URLs. Log in to the Admin Panel → signs you in with a one-time token that deletes itself on first use.

   

cPanel Server Environment & PHP Configuration

To ensure peak performance and seamless file uploads on cPanel, configure your PHP environment according to the specifications below:

* * * * * /usr/local/bin/php /home/username/public_html/artisan schedule:run >> /dev/null 2>&1

*/2 * * * * /usr/local/bin/php /home/username/public_html/artisan queue:work --stop-when-empty --tries=3 >> /dev/null 2>&1

MAIL_MAILER=smtp
MAIL_HOST=mail.yourdomain.com
MAIL_PORT=465
MAIL_USERNAME=noreply@yourdomain.com
MAIL_PASSWORD=your_secure_email_password
MAIL_ENCRYPTION=ssl
MAIL_FROM_ADDRESS=noreply@yourdomain.com
MAIL_FROM_NAME="Mono Marketplace"

04 / Overview

Updates, scheduled jobs, and the queue worker

Applying an update

1. Back up first.

   Copy the database and the storage/ directory. Uploads and the environment file both live outside version control.

2. Replace the code.

   Upload the new release archive and extract it over the existing files. Do not delete storage/, .env, or public/storage during extraction.

3. Migrate.

   Run php artisan migrate. Theme migrations are registered automatically by ThemeServiceProvider, so migrate picks up tables declared by the active theme.

4. Rebuild CSS if you customised it.

   Run npm run build:css only if you edited resources/css/app.css or a theme stylesheet.

5. Clear caches.

   php artisan config:clear, php artisan cache:clear, and php artisan view:clear are enough after a migration run.

Scheduled jobs

Background work is data-driven rather than hard-coded in routes/console.php. The scheduled_jobs table holds each job's key, Artisan command, frequency, and enabled flag, and ScheduledJobService registers them with Laravel's scheduler at boot. Admins edit the table at /admin/settings/scheduled-jobs and can run any job on demand.

05 / Storefront

Themes and the theme engine

A theme is a folder under themes/ that contains a theme.json manifest. The filesystem is the source of truth: a theme exists because its folder exists, and removing the folder removes it from the admin panel.

Every theme below was activated live and captured from its home page at a desktop viewport, so what you see is what each theme actually ships — hero, palette, typography, and storefront sections.

Open capture

Open capture

Open capture

Open capture

Open capture

Open capture

Open capture

Open capture

Open capture

Switching themes is instant and reversible — the admin panel activates a theme by writing one setting; no rebuild, no downtime. Captures above were taken by activating each theme in turn on the same demo catalog.

06 / Storefront

Products, variations, and taxonomy

Product model

Concern	Fields
Identity	vendor_id, category_id, brand_id, name, slug
Pricing	price, old_price
Merchandising	badge (new / sale / bestseller), rating, reviews_count, is_featured, featured_until
Inventory	stock, released on fulfilment by OrderInventoryService
Digital goods	is_digital, digital_delivery_window, plus assets, licence keys, and entitlements
Content	description, long_description, return_days, delivery_method
SEO and i18n	seo_title, seo_meta, translations, seo_translations

Variations

Variable products carry product_variations rows. Buyers pick attributes on the storefront and the variation modal resolves the matching row: it opens from any product card, lists one group per attribute, disables unavailable combinations, and enables Add to bag only when the chosen combination is in stock.

Open capture

Open capture

Shared taxonomy

Categories, brands, and attributes are shared platform-wide but can also be vendor-owned. Each carries vendor_id and an is_global flag: vendors create their own, and an administrator can promote an entry to global with the "make global" action. Categories are a tree via parent_id and can require approval before they appear.

Attributes carry values in attribute_values. The seeded demo set includes Size, Color, Storage, and Capacity.

Bundles

ProductBundleService validates and replaces a bundle's ordered item list. Variable children can be pinned to a specific variation rather than left open, and cancellation restocks every bundle line through OrderInventoryService.

Digital products are first class.

A digital product owns digital_assets, optional digital_license_keys, and per-purchase digital_entitlements. DigitalDeliveryService owns the lifecycle: an entitlement starts pending on order, becomes active on delivery, and is revoked on cancellation or refund. Download limits and expiry windows are enforced server-side.

07 / Storefront

Cart, coupons, tax, shipping, and order placement

Cart

Carts live in carts and cart_items and are shared between the website and the mobile apps. ShippingMeter produces the product-aware free-shipping progress data the cart drawer renders, and OrderInventoryService is the only place stock is decremented or restored.

Discounts

Table	Role
coupons	Discount rules: type, value, minimum spend, maximum discount, usage limit and count, expiry, free-shipping flag, and scope.
coupon_customer	Per-customer redemption limits.
customer_vouchers	Vouchers issued to customers, including loyalty tier redemptions.
loyalty_redemption_tiers	Tier definitions: name, points cost, voucher value, minimum spend.

VoucherService decides which coupons are publishable as vouchers and serialises the voucher cards the apps display.

Tax and shipping

TaxService is a country-and-state aware tax engine with tax classes, rates, and priorities, so it behaves the way a WooCommerce store does. Shipping is configured per method with a flat rate, a free-shipping threshold, and a free-shipping zone. Both are managed from /admin/settings/shipping and /admin/settings/taxes.

Order placement

OrderPlacementService is the single canonical path for placing an order, used by both the website and the API. It revalidates, server-side, everything the client submitted: order ownership, gateway availability, stock, coupon validity, shipping cost, and tax. Totals are always recomputed on the server; the client total is never trusted.

Never trust a client total.

That is the entire point of this service. If you add a checkout entry point, route it through OrderPlacementService rather than writing totals by hand.

Orders carry a human-readable code such as MN-98412, a denormalised customer name and email for display, and snapshot shipping details so historical invoices stay accurate after a customer edits their address book.

08 / Storefront

Payment gateways

Fourteen payment methods ship in the box: twelve online gateways plus cash on delivery and bank transfer. They are defined as constants on PaymentGatewayService:

09 / Storefront

Customer accounts, loyalty, wallet, and digital downloads

Accounts

Customers register with email and password or sign in with Google. The Google client id is served from the API so the apps and the site share one configuration. Password recovery is an OTP flow: request, verify, then reset. Addresses live in a per-customer address book.

Loyalty

LoyaltyService earns points on delivered and paid orders, lets customers redeem tiers as vouchers, and expires stale balances. Every movement is a row in loyalty_transactions with its type, points, linked order or coupon, description, and expiry, so a balance is always auditable.

Administrators configure earning rules at /admin/loyalty and can adjust any customer's balance by hand with a recorded reason.

Wallet

10 / Storefront

Pages, blog, menus, media, and the page builder

Pages

Built-in pages (home, about, contact, FAQ, privacy, terms) are edited at /admin/pages/<slug>/edit. Additional pages are created with the visual custom page builder at /admin/pages/custom, so non-technical staff can compose landing pages without touching Blade.

The homepage hero is a separate editor at /admin/hero. HomePageContent and HomePageSchema make it theme-aware: each theme declares which content keys exist and what fields they accept, so switching themes does not strand a half-configured homepage.

Menus

MenuService reads and writes the header and footer navigation trees at /admin/pages/menus. Menus are nestable, and the reset action restores the theme's shipped default rather than leaving an empty menu.

Blog

Posts are managed at /admin/blog with draft and publish state, cover imagery, categories, and bulk actions. Post content goes through the same translation pipeline as products and pages.

Media library

MediaService backs a shared library at /admin/media, with upload, delete, and bulk delete. Uploads are written under storage/app/public and served through PublicMedia::url().

Upload roots are enumerated by BackfillMedia and cover products, categories, brands, blog, branding, customers, vendors, admins, and AI output. The library is isolated per owner where it matters: a vendor sees their own media, an administrator sees everything.

Cookie consent

The consent banner is configured at /admin/settings/cookie and rendered by the shared layout partial, so it appears on every theme without per-theme work.

11 / Storefront

Languages, RTL, and the translation editor

MONO ships English, Arabic, and Bengali. Arabic is a full right-to-left experience, not a mirrored stylesheet: layouts, the admin and vendor panels, and the storefront all flip, and PanelRtlLocalizationTest guards that behaviour.

Two independent defaults

This is the detail that trips people up. Each language has a web default and a separate mobile default, stored as default and default_mobile. Setting English as the web default does not make English the app default. Admins toggle each independently at /admin/languages.

12 / Vendor panel

Vendor dashboard and store operations

The vendor portal is served from /dashboard behind the auth:vendor guard, vendor.verified, and vendor.approved middleware. Each vendor operates inside an isolated tenancy boundary: every query is scoped to vendor_id, so merchants only ever see and manage their own store catalog, orders, media, and finances.

Dashboard metrics

The landing page provides immediate operational visibility for merchants:

• Net Earnings (30d): Net income from paid, fulfilled items minus marketplace commission and refunds.
• Order Volume: Total order count with monthly delta comparisons.
• Average Order Value (AOV): Average transaction spend across store orders.
• Live Products: Published catalog count with inventory growth metrics.
• AI Usage & Quotas: Real-time consumption meter for text generation tokens, translation tokens, and generated product imagery. Displays clear status indicators when allowances are reached.
• 12-Week Revenue Trajectory: Rolling financial bar chart plotting sales momentum.
• Top Products Leaderboard: Top 5 revenue-generating items in the vendor's catalog.

Vendor portal navigation

13 / Vendor panel

Products, digital fulfilment, settlements, and AI

Vendors manage their complete ecommerce lifecycle from the web dashboard, supporting physical goods with complex variations as well as instantly deliverable digital goods.

Catalog and variations

Product creation in DashboardController handles both simple and variable products. Variable products synchronize attribute combinations (sizes, colors, fabrics) using VariationSyncService:

• Each variation has its own SKU, inventory stock, regular price, and sale price.
• Dynamic matrix creation generates all valid permutations without manual database configuration.
• Vendors can request new categories (/dashboard/categories/request) or register custom brand names (/dashboard/brands) subject to admin review.

Product bundles

The bundle editor at /dashboard/product-bundles lets vendors group complementary products into discounted bundle packages. ProductBundleController validates inventory across all bundle items and ensures accurate pricing on checkout.

Digital goods & instant delivery

Products marked is_digital support downloadable files, license keys, and digital entitlements. When an order is placed and paid:

• The vendor accesses /dashboard/orders/{order} and triggers orders.digital-deliver.
• The system mints a DigitalEntitlement record with access limits and secure download tokens.
• The customer immediately receives download access in their account library and via email notification.

Settlements and withdrawals

Every completed sale generates a settlement row calculating the exact revenue breakdown:

The settlements table at /dashboard/settlements tracks pending, available, and paid earnings. Vendors request payouts via /dashboard/withdrawals once their balance satisfies the minimum withdrawal threshold configured in platform settings.

Featured sponsorships

Vendors can promote individual products to prime homepage and category slots via /dashboard/products/{product}/feature. The vendor chooses a featured duration package and completes payment directly in the panel using Stripe, SSLCommerz, or PayPal. Upon payment verification, the product is flagged is_featured = 1 until the expiration timestamp.

Vendor AI suite

The dashboard incorporates integrated AI tooling powered by OpenAI / Google Gemini providers:

• Product Description Writer: Generates compelling ecommerce copy and bullet points from minimal attribute inputs.
• Multilingual Translation: 1-click translation of titles and descriptions across English, Arabic, and Bengali.
• Credit Packs: When monthly package quotas are exhausted, merchants purchase non-expiring AI credit packs directly through /dashboard/ai-credits.

14 / Admin panel

Dashboard and admin navigation

The admin panel is served from /admin behind auth:admin. The sidebar is defined as PHP arrays in resources/views/layouts/admin.blade.php and filtered by permission, so an administrator only ever sees the modules they can actually use. The same permission keys guard the routes, which means the menu is not the security boundary — the middleware is.

Navigation groups

15 / Admin panel

Administrators, roles, and the permission system

There is no admin self-registration. The first account is created by the installer; every account after that is created by another administrator at /admin/administrators. Administrators authenticate against the admin guard and the App\Models\Admin model, which is entirely separate from customers and vendors.

How permissions work

Roles and permissions are hand-rolled, not Spatie. Five tables carry it: roles, permissions, the role_permission pivot, the admin_role pivot, and admins. A role carries an is_super flag, and Admin::hasPermission() returns true unconditionally for a super administrator.

Routes declare a permission through the permission: middleware. Pipe-separated values mean "any of", so permission:products.manage|blogs.manage|pages.manage grants access to any one of the three.

Seeded roles

16 / Admin panel

Orders, invoices, and refunds

Everything in the commerce group sits behind orders.view. The order list filters by status, including the returned state, and the detail page is the hub for everything about a purchase.

Order actions

17 / Admin panel

Catalog administration

The whole catalog block shares one permission, products.manage. That is a deliberate simplification: a catalog that a role can add to but not moderate is worse than one it cannot touch at all.

Taxonomy approval

Vendors create their own categories, brands, and attributes. Those entries are pending until an administrator acts on them:

• Categories are a tree via parent_id and are approved or rejected at /admin/categories.
• Brands and attributes can be promoted to global with "make global", which makes them available to every vendor.
• Every list view has a JSON search endpoint, which is what the pickers in the product forms call.

Review moderation

Reviews are managed at /admin/reviews with approve, reject, status change, and bulk delete. ProductReviewService resolves who is allowed to review what from the review settings, so the eligibility rule is one decision rather than one per entry point.

18 / Admin panel

Customers, wallets, coupons, and loyalty

Wallet approval flow

1. Customer requests a top-up.

   The request is written to wallet_transactions as pending. Money has not moved and the balance has not changed.

2. It appears in the admin queue.

   /admin/wallets/pending lists every outstanding request with its method, reference, and amount.

3. An administrator approves or rejects.

   Approval credits the wallet and records the administrator. Rejection leaves the balance untouched. Neither is silent: both are ledger rows.

Unapproved requests that expire are reversed rather than left open, which is why a pending top-up never becomes a surprise balance later.

19 / Admin panel

Vendors, packages, settlements, and withdrawals

This is the largest group in the admin panel, and it is split across three permissions so that approving a seller, selling them a plan, and paying them are three separate decisions.

Getting vendors on the platform

20 / Admin panel

Delivery operations

Delivery covers the physical path from a vendor's shelf to a customer's door. It is split into operations and configuration, because the people who run shipments are rarely the people who set courier contracts.

Operations, behind delivery.manage

21 / Admin panel

Chat, messages, push, and newsletters

Realtime chat inbox

The admin inbox is the platform operator's view of every customer-vendor conversation. It uses Ably for delivery with a REST polling fallback, so the inbox still works if the realtime connection drops.

22 / Admin panel

AI tools, providers, and vendor quotas

The AI toolset is available to authenticated administrators for translating content, generating copy, and generating images. Providers and model selection live at /admin/settings/ai.

What administrators can do

• POST /admin/translate translates arbitrary content, throttled to 20 requests per minute.
• POST /admin/translate/taxonomy bulk-translates taxonomy in one pass, throttled to 10 per minute.
• POST /admin/generate and POST /admin/generate-image produce copy and imagery, gated by products.manage|blogs.manage|pages.manage.

Translation runs through AiTranslationService, which chunks long fields and keeps every field that succeeded. A record with one untranslatable field is partially translated rather than rolled back, and the response lists what was skipped.

Vendors get metered access

Sellers reach the same tools from the vendor panel and the vendor API, but through VendorAiQuotaService, which enforces three separate pools:

Vendor AI endpoints are throttled to 30 requests per minute each, and quota is checked before the call, not after. Credits are drawn down from the active package allowance, and unused allowances expire rather than rolling over: ai-credits:cancel-expired runs every minute.

Every AI call is recorded in ai_usage with its provider, model, token counts, and cost attribution, so you can reconcile spend against packages.

23 / Admin panel

Themes, app themes, and colours

Everything here sits behind themes.manage and lives under /admin/appearance.

24 / Admin panel

Settings reference

/admin/settings redirects to the shop settings page. The rest of the group is a set of focused screens rather than one long form, so an operator changes one thing at a time.

25 / Admin panel

Administrators, roles, languages, and media

These four modules sit in the "Administration" group. They are the ones that change who can do what, in what language, and with what imagery.

Administrators

/admin/administrators creates, edits, and deletes admin accounts behind admins.manage. There is no public registration path: the installer creates the first account, and every account after that comes from this screen.

Roles

/admin/roles is where permissions are assigned. Each role is a name, a label, an is_super flag, and a set of permissions drawn from the 32 available. Changing a role's permission set changes it for every administrator holding that role, immediately.

Languages

/admin/languages manages the three shipped languages plus any you add. Each has a web default and an independent mobile default, an enable/disable switch, and a per-language translation editor at /admin/languages/{language}/translations.

Media

/admin/media is the shared library behind every image picker in the panel, with a JSON listing endpoint, upload, delete, and bulk delete. Uploads land under storage/app/public in the owner-appropriate subdirectory and are served through PublicMedia::url().

The library is owner-isolated: a vendor only ever sees their own media, while an administrator sees everything. MediaIsolationTest guards that boundary.

26 / Backend

API version 1: shape, auth, and limits

Both Flutter clients talk to the same versioned JSON API. The prefix is set once in bootstrap/app.php as api/v1; there is no content negotiation, so the version is explicit in every path.

Response envelope

Authentication

Sanctum personal access tokens, sent as Authorization: Bearer. Two middleware variants exist, and the difference matters when you add a public endpoint that still wants to know who is asking:

• auth:sanctum requires a valid token and rejects without one.
• auth.optional resolves the user when a token is present and never rejects. The public catalog runs on it so that wishlisted and collected flags can be resolved for a signed-in customer without turning browsing into a login wall.

Rate limits

There is no global limiter. Limits are declared per route:

27 / Backend

Customer API surface

Roughly forty endpoint families serve the customer app. The shape below is grouped by what a user is doing rather than by controller, because that is how the apps consume it.

Content and localisation

GET /content/about, /content/contact, and /content/page/{slug} return CMS content. GET /country, /country/states/{cc}, and /country/cities/{state} drive the address forms. GET /languages and GET /translations/{code} supply the app's interface strings, including the separate mobile namespaces.

28 / Backend

Vendor API surface

Everything a seller needs is namespaced under /api/v1/vendor, served by sixteen controllers in Api/V1/Vendor/. Vendor auth, profile, and settings mirror the customer equivalents.

29 / Backend

Schema overview

The application carries 147 migrations producing 94 tables, backed by 78 Eloquent models. Most of the volume is marketplace and delivery surface rather than framework scaffolding.

30 / Backend

Services, jobs, events, and commands

Business rules live in services, not in controllers. If a rule is about orders, money, delivery, or entitlement, it belongs in app/Services.

The services that matter most

Jobs and events

Three queued jobs: SendNewsletterCampaign (chunked, timeout = 1800), SendPushNotification, and SendVendorPushNotification (both tries = 2, both pruning dead device tokens). One observer, AiCreditPurchaseObserver, fires the vendor notification when a credit purchase becomes active from any flow and de-duplicates it.

Four broadcast events run through Ably: MessageSent, MessageRemoved, ChatReceiptUpdated, and VendorNotificationReceived.

Artisan commands

31 / Backend

Going live: deployment and the pre-launch checklist

Production configuration

Pre-launch checklist

1. Remove the demo data.

   Delete the seeded admin, customer, and vendor accounts, or run migrate without --seed. Confirm no @mono.test account can still authenticate.

2. Delete the installer.

   Remove public/install.php and confirm storage/app/installed.lock exists.

3. Set the app key and rotate the seeded Firebase keys.

   Run key:generate for a fresh APP_KEY, and replace the Firebase web configuration that the seeders wrote.

4. Configure only the gateways you need.

   Fill in real credentials at /admin/settings/payment-gateways and leave the rest disabled. A half-configured gateway is hidden from checkout automatically, which is the behaviour you want while you set it up.

5. Verify mail actually sends.

   Use the test-send button at /admin/settings/smtp. Until mail works, order confirmations, invoices, OTPs, and password resets all fail silently from the customer's point of view.

6. Confirm the cron and the queue worker are running.

   Unpaid orders will not be cancelled, featured placements will not expire, and newsletters and push will not be delivered without them.

7. Add rate limiting to the auth endpoints.

   Login, register, and the OTP routes have no limiter in this build. Add one before exposing the site publicly.

8. Review file upload handling.

   Confirm uploads land outside any executable path, that extensions and MIME types are validated server-side, and that chat attachments and digital downloads verify the requesting user before streaming a file.

9. Set a real admin password policy and rotate shared logins.

   Particularly before granting vendors.impersonate to anyone.

Backups

Back up the database and storage/ together. The database holds every setting, every uploaded media record, and the entire wallet and settlement ledger; storage/ holds the actual files and the generated invoice PDFs. A backup of one without the other is not a backup.