ADMIN / 01 Governance
Sellers + KYC Approvals

Multi-step registration, document verification, store approvals, and suspensions.

ADMIN / 02 Money
Commissions & Payouts

Category-wise rates, automated settlement, and withdrawal control.

ADMIN / 03 Catalog
Orders, Refunds & Invoices

Catalog administration, order lifecycle, and refund operations end to end.

ADMIN / 04 Access
Roles + 32 Permissions

Granular permission gates on every admin action.

Super admin documentationOperate · Govern · Scale

Laravel · /admin

Mono. Admin Panel.

Complete operations and governance guide.

The Laravel super-admin console behind the marketplace: govern sellers and KYC approvals, tune commissions and settlements, run catalog, order, delivery, chat, and AI operations, and control every platform setting from one place.

A / 01

Surface

/admin consoleSuper Admin
A / 02

Access control

Roles + 32 permissionsGranular
A / 03

Stack

Laravel 13 / PHP 8.3Self-hosted

01 / Overview

One codebase, three front doors

MONO Marketplace is a multi-seller commerce platform. A single Laravel application serves three completely separate front doors, and they all share one database, one permission system, and one theme engine.

STOREFRONT

Customer website

  • Themeable catalog with nine shipped storefront themes.
  • Cart, coupons, vouchers, wishlist, loyalty, and wallet.
  • Fourteen payment methods including cash on delivery and bank transfer.
  • Digital goods, bundles, and seller chat with realtime delivery.
SELLER PANEL

Seller dashboard

  • Applications, product, bundle, and taxonomy management.
  • Order fulfilment with per-item digital delivery.
  • Settlements, withdrawal requests, subscription packages.
  • AI suite with metered text, translation, and image quotas.
ADMIN PANEL

Platform control

  • Orders, invoices, refunds, and a full finance ledger.
  • Seller approvals, subscriptions, payouts, and delivery operations.
  • Roles, permissions, languages, media, and site settings.
  • Push broadcasting, newsletters, and an AI administration toolset.

What ships in the package

Storefront themes

Nine themes on disk: mono (built in), plus beauty, electronics, fashion, fullwidth, grocery, home, petshop, and sports. Each is a self-contained package with its own views, assets, palette, and optional database tables.

Mobile applications

Two Flutter clients ship alongside: the customer app and the seller app. Both talk to the same versioned API described in this document.

Web installer

public/install.php is a self-contained wizard that creates the database, writes the environment file, creates the first administrator, and activates a theme. No Composer, Node, or shell access is required on the host.

The three front doors, at a glance

Each interface is purpose-built for desktop web workflows — responsive Blade templates styled with Tailwind CSS, with zero client-side compilation steps.

Storefront — Customer web marketplace
Seller Panel — Seller dashboard & catalog
Admin Panel — Platform operations control

Who this documentation is for

This guide covers the web product: the storefront, the seller panel, the admin panel, and the backend services that support them. The two Flutter applications have their own companion documents. Everything here is written against the shipped source, so route names, table names, and permission keys match what you will find in the package.

API PREFIXhttps://your-domain.com/api/v1

17 / Admin panel

Dashboard and admin navigation

Live Admin Panel Demo ↗

The admin panel is served from /admin (on your domain: https://your-domain.com/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.

Admin Dashboard — real-time sales overview, revenue trends, and operational status

Navigation groups

GroupModules
OverviewDashboard
CommerceOrders, Invoices, Coupons, Loyalty, Reviews
NotificationPush notifications, Newsletter, Promos
CustomersCustomers
MarketplaceSellers, Delivery pickup, Applications
ContentPages, Blog, Media
CommunicationMessages, Inbox
AdministrationAdministrators, Languages
Themes & appearanceThemes
SettingsSettings

Dashboard

The landing page shows revenue, order, seller, and customer totals each with a thirty-day delta, a revenue chart, order status counts, the six most recent orders, the five most recent pending seller applications, and the five top sellers. Every figure is computed from current rows rather than a cached summary, so it cannot drift.

Global admin search

/admin/search is a JSON endpoint that searches a fixed index of roughly forty admin pages plus records, so an operator can jump straight to a setting or an order from anywhere in the panel.

Your own profile

/admin/profile edits your name, email, avatar, and password. It is deliberately outside every permission gate: changing your own password must never depend on a role assignment that someone else controls.

18 / 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 sellers.

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

RoleSuperAccess
super_adminYesEverything, plus the bypass in hasPermission().
administratorNoAll 32 permissions. Effectively identical day to day; it simply cannot grant itself new ones by virtue of existing.
editorNodashboard.view, orders.view, coupons.manage, reviews.manage, products.manage, customers.manage.

Administrators and roles are managed at /admin/administrators and /admin/roles, guarded by admins.manage and roles.manage.

The thirty-two permissions

GroupPermissions
Overviewdashboard.view
Commerceorders.view, coupons.manage, loyalty.manage, notifications.manage, promos.manage, reviews.manage, products.manage, customers.manage, wallets.manage
Marketplacesellers.manage, sellers.impersonate, registrations.manage, packages.manage, delivery.settings.manage, applications.manage, payouts.manage, delivery.manage
Administrationmessages.manage, languages.manage, themes.manage, shipping.manage, taxes.manage, locations.manage, payments.manage, settings.manage, blogs.manage, pages.manage, media.manage, roles.manage, admins.manage
Impersonation is a separate grant.

sellers.impersonate is deliberately not bundled into sellers.manage. "Login as seller" signs you in as a seller with their full session, so it should be held by as few people as possible and revoked when someone leaves.

19 / 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

ActionRouteEffect
CreatePOST /admin/ordersManual order, with product and customer search endpoints behind it.
Change statusPATCH /admin/orders/{order}/statusDrives customer notifications and loyalty accrual.
Change paymentPATCH /admin/orders/{order}/paymentStatus, method, and reference.
Generate invoicePOST /admin/orders/{order}/invoiceRenders a PDF through dompdf.
Email invoicePOST /admin/orders/{order}/invoice/sendSends the rendered document.
DeleteDELETE /admin/orders/{order}Single, or bulk via bulk-destroy.

Invoices

InvoiceService issues numbered invoices and is idempotent per (kind, trigger, reference), so a repeated trigger cannot produce a duplicate document. Each invoice stores its number, sequence, fiscal year, kind, trigger, bill-to details, a line breakdown, the company block as a JSON snapshot, the generated PDF path, and its email delivery status and error.

Triggers are configurable at /admin/settings/invoices: order placed, paid, delivered, status change, refund, wallet adjustment, package purchase, and featured promotion. The number prefix, tax ID, and footer are set in the same place.

One active invoice per order.

Regenerating supersedes rather than stacks, and the invoice list at /admin/invoices shows the current document for each order plus the full history of downloads and re-sends.

Refunds

Refunds are supported for three gateways only: Stripe, PayPal, and SSLCommerz. The admin controller exposes refundStripe, refundPaypal, and refundSslCommerz. There is no generic refund path, because a generic path would be a generic way to lose money.

20 / 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.

PRODUCTS

Listing and editing

  • Create and edit products with digital assets, variations, SEO, and per-field translations.
  • Bulk and single delete.
  • Digital assets, removed files, and bulk licence keys are handled by DigitalProductService, shared with the seller form.
BUNDLES

Bundled sets

  • Create and edit bundles at /admin/product-bundles.
  • Candidate lookup for choosing line items.
  • Variable children can be pinned to a specific variation.
  • Cancellation restocks every line.
FEATURED

Paid promotion

  • Feature or unfeature any product by hand.
  • Approve or reject seller featured-placement requests.
  • Define and price the featured packages themselves.
  • featured:expire clears lapsed placements automatically.

Taxonomy approval

Sellers 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 seller.
  • 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.

21 / Admin panel

Customers, wallets, coupons, and loyalty

customers.manage

Customer accounts

  • List, create, edit, and delete customer accounts.
  • Bulk delete for cleanup.
  • Search powers the manual-order customer picker.
wallets.manage

Wallets

  • Wallet list, single wallet detail, and the full transaction ledger.
  • Pending top-ups queue for approval or rejection.
  • Manual credit and debit with an attributed administrator.
coupons.manage · loyalty.manage

Discounts and points

  • Coupon CRUD, bulk delete, and scoped target search.
  • Loyalty settings and redemption tier CRUD.
  • Manual point adjustment with a customer search.

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.

Wallet writes are auditable by design.

Every transaction row carries the acting admin_id when a person caused it, plus a reference, method, and free-form metadata. If you add a balance path, populate all four.

22 / Admin panel

Sellers, 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 sellers on the platform

SurfaceRoutePermissionWhat it does
Applications/admin/applicationsapplications.manageSubmissions from the public "become a seller" form, with per-item and bulk status actions.
Registrations/admin/sellers/registrationsregistrations.manageApproval workflow with a configurable approval mode and its own settings page.
Sellers/admin/sellerssellers.manageCRUD, verify toggle, suspend toggle, bulk delete.
ImpersonationPOST /admin/sellers/{seller}/impersonatesellers.impersonateOpens a full seller session as that seller.
Store FAQs/admin/faqssellers.managePer-store FAQs, with translations.

Verification, suspension, and approval are independent states. A verified seller can still be suspended, and suspending one does not delete their catalog.

Subscription packages

Sellers buy plans. A seller_packages row carries price, duration, a benefits array, and either a global commission or a per-package commission percentage and fixed amount. SellerBillingService owns the maths, and subscriptions snapshot price, duration, and commission at the moment of purchase so a later plan edit cannot rewrite history.

Lifecycle

  • Requested, then approved, rejected, or cancelled by an administrator.
  • Payment status tracked separately from subscription status.
  • seller-packages:notify-expiry warns sellers before a plan lapses.

Settlement lines

  • One line per seller and subscription.
  • Gross, discount, commission, seller earning, admin earning.
  • Refund columns so a reversed commission stays visible instead of vanishing.

Money out

  • Settlements at /admin/sellers/settlements show the full ledger: gross, discount, commission, seller earning, and admin earning per line.
  • Withdrawal requests at /admin/sellers/withdrawals are approved or rejected; paid and rejected history is kept separately at /admin/sellers/withdrawals/history.
  • Global presets at /admin/sellers/withdrawal-presets define the supported methods (bank transfer, PayPal, bKash, and so on).
  • Per-seller accounts at /admin/sellers/{seller}/withdrawal-methods hold the payout destination for that seller.
Route ordering matters here.

The payouts group must stay above the sellers group in routes/web.php. The static withdrawal-presets path has to match before the /sellers/{seller} wildcard swallows it. If you reorder those groups, that page will 404.

AI credit packs

Sellors can buy token packs for the AI suite. Packs are defined at /admin/sellers/ai-packs, purchases are approved or rejected, and a pack can also be granted directly to a seller. AiCreditPurchaseObserver fires the "credits added" notification when a purchase becomes active from any flow, and de-duplicates it against the explicit notification call so sellers are not told twice.

23 / Admin panel

Delivery operations

Delivery covers the physical path from a seller'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

SurfaceRouteWhat it does
Pickup requests/admin/delivery/pickup-requestsSeller to warehouse pickups.
Drop-off requests/admin/delivery/dropoff-requestsWarehouse to customer drop-offs.
Request lifecyclePOST /admin/delivery/requests/{id}/…Approve, reject, schedule, assign personnel, change status, add a note, set the warehouse.
Shipments/admin/delivery/shipmentsOutbound shipments with courier, tracking number, and tracking URL.
Tracking/admin/delivery/trackingOne merged timeline per order.

Every state change on a request is written to delivery_request_events, so the timeline is a record rather than a reconstruction. TrackingService merges request events and shipment events into the single per-order timeline that customers and sellers both see.

Order status is synced conservatively.

ShipmentService moves the parent order forward only when the evidence is unambiguous. It will not downgrade an order to match a lagging shipment, because a late courier scan should never tell a customer their delivered order is processing again.

Configuration, behind delivery.settings.manage

Delivery personnel

CRUD for delivery staff at /admin/delivery/personnel, assignable to any request.

Warehouses and pickup points

/admin/delivery/locations, created, updated, and deleted.

Couriers

/admin/delivery/couriers, the courier partners available when creating a shipment.

Feature flags

/admin/delivery/settings via DeliverySettings, including the delivery_notify_* switches that gate seller, admin, and customer notifications.

DeliveryService is the single source of validation shared by the seller panel, the admin panel, and the API, so a request created from any of the three is checked the same way.

24 / Admin panel

Chat, messages, push, and newsletters

Realtime chat inbox

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

RouteRate limitPurpose
inboxnoneConversation list
inbox/{conversation}noneMessage thread
inbox/reply20 / 1 minSend as the platform
inbox/{id}/pollnonePolling fallback
inbox/{id}/delivered60 / 1 minRead and delivered receipts
inbox/ably/token30 / 1 minShort-lived client token
inbox/messages/removenoneModeration removal

The Ably secret never leaves the server. AblyTokenService mints short-lived client tokens per request, and routes/channels.php authorises each private channel against the correct guard. Admin access to a conversation requires both messages.manage and that the conversation belongs to the platform seller.

Message content is untrusted.

It arrives from customers and sellers. Escape it on render, and do not allow it to introduce markup. Chat attachments are served through signed URLs with a one-hour expiry, and the download route must verify the caller.

Contact messages

The public contact form feeds /admin/messages. ContactMessageService persists the message first and then treats the admin notification email as best-effort, so a mail failure never loses a customer's enquiry.

Push notifications

/admin/notifications/push broadcasts to customer devices over Firebase Cloud Messaging. FcmClient implements the FCM HTTP v1 API directly, including JWT-bearer OAuth2 token caching, so no Firebase Admin SDK is required. SendPushNotification fans out across a customer's registered devices and prunes tokens that have gone dead.

Service-account credentials are uploaded at /admin/settings/firebase and stored in the database, not .env.

Newsletters

/admin/newsletter manages subscribers, a campaign editor, CSV export, test sends, and dispatch. SendNewsletterCampaign chunks through active subscribers in one worker run with a thirty-minute timeout, which is why a queue worker matters on a real site.

Promo banners

/admin/promos controls the promotional banner shown on the mobile apps' home screen. It is a separate surface from the storefront hero, so a campaign can target app users without changing the website.

25 / Admin panel

AI tools, providers, and seller 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

TRANSLATE 20 / minTAXONOMY BATCH 10 / minGENERATE rate limited
  • 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.

Sellers get metered access

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

POOL 1

Text generation

Tokens consumed by copy and description generation.

POOL 2

Translation

A separate token pool, because translation volume scales very differently from authoring.

POOL 3

Images

Counted per generated image rather than per token.

Seller 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.

AI keys live in the database.

Provider credentials are stored through the settings store and edited from the admin panel. They are never written to .env, and they are never returned to the browser.

26 / Admin panel

Themes, app themes, and colours

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

SurfaceRouteWhat it does
Branding/admin/appearance/brandingSite logo, favicon, and brand marks.
Storefront themes/admin/appearance/themesInstall, activate, and remove storefront themes.
App themes/admin/appearance/app-themesActivate the mobile app's visual system.
Colours/admin/appearance/colorsEdit and reset the active palette.

Palette resolution

ThemePalette maps a manifest palette onto CSS custom properties. Each colour carries a label, a default, and a variable name, so an administrator sees "Button background" rather than --el-primary-500. The palette also carries shape radii, an isDark flag, and status colours for the seven order statuses, so a dark theme automatically gets readable status badges instead of inheriting light ones.

Storefront and app themes move independently

Switching the storefront theme does not change the mobile app's layout, and switching the app theme does not change the website. They share a colour palette, but each has its own activation state. Legacy /settings/branding, /settings/themes, and /settings/colors URLs redirect here, so old bookmarks and old documentation links keep working.

Removing a theme is destructive.

Uninstall drops every table the manifest declares. The mono theme is kept outside the removable tree for exactly this reason.

27 / 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.

PageRoutePermissionContains
Shop/admin/settings/shopsettings.manageSite name, tagline, contact details, currency, free-shipping threshold, flat shipping, product grid columns, pagination.
Shipping/admin/settings/shippingshipping.manageShipping rates, flat rate, free-shipping zone, and shipping method CRUD.
Locations/admin/settings/countrieslocations.manageCountries with nested states and cities.
Taxes/admin/settings/taxestaxes.manageTax classes and rates with priorities.
Payments/admin/settings/payment-gatewayspayments.manageAll fourteen gateway configurations.
Invoices/admin/settings/invoicessettings.manageEnable, triggers, number prefix, tax ID, footer.
SMTP/admin/settings/smtpsettings.manageMail server and a test-send button.
Firebase/admin/settings/firebasesettings.manageFCM web config and service-account upload.
Scheduled jobs/admin/settings/scheduled-jobssettings.manageJob table with frequency, enable/disable, and run-now.
Chat/admin/settings/chatsettings.manageAbly configuration.
Mobile app/admin/settings/mobile-appsettings.manageApp-facing configuration served to both Flutter clients.
AI/admin/settings/aisettings.manageProviders, model list, and translator, generator, and image model selection.
Cookie consent/admin/settings/cookiesettings.manageConsent banner copy and behaviour.
Settings are stored in the database.

Everything above is key and value rows in the settings table, not environment variables. That is deliberate: it lets an operator change a mail server or rotate a payment key without shell access. It also means backing up the database backs up your configuration.

28 / 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.

Guard the last super administrator.

An is_super role bypasses hasPermission() entirely. If you remove super-admin status from every account, nobody can restore it through the panel and you will be editing the database by hand.

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 seller only ever sees their own media, while an administrator sees everything. MediaIsolationTest guards that boundary.