Surface
/admin consoleSuper AdminMulti-step registration, document verification, store approvals, and suspensions.
Category-wise rates, automated settlement, and withdrawal control.
Catalog administration, order lifecycle, and refund operations end to end.
Granular permission gates on every admin action.
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.
Access control
Roles + 32 permissionsGranularStack
Laravel 13 / PHP 8.3Self-hosted01 / 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.
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 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.
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
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.
Two Flutter clients ship alongside: the customer app and the seller app. Both talk to the same versioned API described in this document.
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.
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.
https://your-domain.com/api/v117 / 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.
Navigation groups
| Group | Modules |
|---|---|
| Overview | Dashboard |
| Commerce | Orders, Invoices, Coupons, Loyalty, Reviews |
| Notification | Push notifications, Newsletter, Promos |
| Customers | Customers |
| Marketplace | Sellers, Delivery pickup, Applications |
| Content | Pages, Blog, Media |
| Communication | Messages, Inbox |
| Administration | Administrators, Languages |
| Themes & appearance | Themes |
| Settings | Settings |
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
| Role | Super | Access |
|---|---|---|
super_admin | Yes | Everything, plus the bypass in hasPermission(). |
administrator | No | All 32 permissions. Effectively identical day to day; it simply cannot grant itself new ones by virtue of existing. |
editor | No | dashboard.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
| Group | Permissions |
|---|---|
| Overview | dashboard.view |
| Commerce | orders.view, coupons.manage, loyalty.manage, notifications.manage, promos.manage, reviews.manage, products.manage, customers.manage, wallets.manage |
| Marketplace | sellers.manage, sellers.impersonate, registrations.manage, packages.manage, delivery.settings.manage, applications.manage, payouts.manage, delivery.manage |
| Administration | messages.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 |
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
| Action | Route | Effect |
|---|---|---|
| Create | POST /admin/orders | Manual order, with product and customer search endpoints behind it. |
| Change status | PATCH /admin/orders/{order}/status | Drives customer notifications and loyalty accrual. |
| Change payment | PATCH /admin/orders/{order}/payment | Status, method, and reference. |
| Generate invoice | POST /admin/orders/{order}/invoice | Renders a PDF through dompdf. |
| Email invoice | POST /admin/orders/{order}/invoice/send | Sends the rendered document. |
| Delete | DELETE /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.
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.
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.
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.
Paid promotion
- Feature or unfeature any product by hand.
- Approve or reject seller featured-placement requests.
- Define and price the featured packages themselves.
featured:expireclears 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_idand 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.manageCustomer accounts
- List, create, edit, and delete customer accounts.
- Bulk delete for cleanup.
- Search powers the manual-order customer picker.
wallets.manageWallets
- 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.manageDiscounts 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
- Customer requests a top-up.
The request is written to
wallet_transactionsas pending. Money has not moved and the balance has not changed. - It appears in the admin queue.
/admin/wallets/pendinglists every outstanding request with its method, reference, and amount. - 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.
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
| Surface | Route | Permission | What it does |
|---|---|---|---|
| Applications | /admin/applications | applications.manage | Submissions from the public "become a seller" form, with per-item and bulk status actions. |
| Registrations | /admin/sellers/registrations | registrations.manage | Approval workflow with a configurable approval mode and its own settings page. |
| Sellers | /admin/sellers | sellers.manage | CRUD, verify toggle, suspend toggle, bulk delete. |
| Impersonation | POST /admin/sellers/{seller}/impersonate | sellers.impersonate | Opens a full seller session as that seller. |
| Store FAQs | /admin/faqs | sellers.manage | Per-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-expirywarns 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/settlementsshow the full ledger: gross, discount, commission, seller earning, and admin earning per line. - Withdrawal requests at
/admin/sellers/withdrawalsare approved or rejected; paid and rejected history is kept separately at/admin/sellers/withdrawals/history. - Global presets at
/admin/sellers/withdrawal-presetsdefine the supported methods (bank transfer, PayPal, bKash, and so on). - Per-seller accounts at
/admin/sellers/{seller}/withdrawal-methodshold the payout destination for that seller.
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
| Surface | Route | What it does |
|---|---|---|
| Pickup requests | /admin/delivery/pickup-requests | Seller to warehouse pickups. |
| Drop-off requests | /admin/delivery/dropoff-requests | Warehouse to customer drop-offs. |
| Request lifecycle | POST /admin/delivery/requests/{id}/… | Approve, reject, schedule, assign personnel, change status, add a note, set the warehouse. |
| Shipments | /admin/delivery/shipments | Outbound shipments with courier, tracking number, and tracking URL. |
| Tracking | /admin/delivery/tracking | One 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.
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
CRUD for delivery staff at /admin/delivery/personnel, assignable to any request.
/admin/delivery/locations, created, updated, and deleted.
/admin/delivery/couriers, the courier partners available when creating a shipment.
/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.
| Route | Rate limit | Purpose |
|---|---|---|
inbox | none | Conversation list |
inbox/{conversation} | none | Message thread |
inbox/reply | 20 / 1 min | Send as the platform |
inbox/{id}/poll | none | Polling fallback |
inbox/{id}/delivered | 60 / 1 min | Read and delivered receipts |
inbox/ably/token | 30 / 1 min | Short-lived client token |
inbox/messages/remove | none | Moderation 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.
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
POST /admin/translatetranslates arbitrary content, throttled to 20 requests per minute.POST /admin/translate/taxonomybulk-translates taxonomy in one pass, throttled to 10 per minute.POST /admin/generateandPOST /admin/generate-imageproduce copy and imagery, gated byproducts.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:
Text generation
Tokens consumed by copy and description generation.
Translation
A separate token pool, because translation volume scales very differently from authoring.
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.
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.
| Surface | Route | What it does |
|---|---|---|
| Branding | /admin/appearance/branding | Site logo, favicon, and brand marks. |
| Storefront themes | /admin/appearance/themes | Install, activate, and remove storefront themes. |
| App themes | /admin/appearance/app-themes | Activate the mobile app's visual system. |
| Colours | /admin/appearance/colors | Edit 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.
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.
| Page | Route | Permission | Contains |
|---|---|---|---|
| Shop | /admin/settings/shop | settings.manage | Site name, tagline, contact details, currency, free-shipping threshold, flat shipping, product grid columns, pagination. |
| Shipping | /admin/settings/shipping | shipping.manage | Shipping rates, flat rate, free-shipping zone, and shipping method CRUD. |
| Locations | /admin/settings/countries | locations.manage | Countries with nested states and cities. |
| Taxes | /admin/settings/taxes | taxes.manage | Tax classes and rates with priorities. |
| Payments | /admin/settings/payment-gateways | payments.manage | All fourteen gateway configurations. |
| Invoices | /admin/settings/invoices | settings.manage | Enable, triggers, number prefix, tax ID, footer. |
| SMTP | /admin/settings/smtp | settings.manage | Mail server and a test-send button. |
| Firebase | /admin/settings/firebase | settings.manage | FCM web config and service-account upload. |
| Scheduled jobs | /admin/settings/scheduled-jobs | settings.manage | Job table with frequency, enable/disable, and run-now. |
| Chat | /admin/settings/chat | settings.manage | Ably configuration. |
| Mobile app | /admin/settings/mobile-app | settings.manage | App-facing configuration served to both Flutter clients. |
| AI | /admin/settings/ai | settings.manage | Providers, model list, and translator, generator, and image model selection. |
| Cookie consent | /admin/settings/cookie | settings.manage | Consent banner copy and behaviour. |
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.
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.