PAC-SM | Africa's Market. One Connected Continent.

Documentation policy

Every new PAC-SM feature, user workflow, role, integration or material behavior change must update this documentation and the public FAQ in the same development change.

Account dropdown and mobile shortcuts

Account and Orders remain visible in the shared top bar across desktop, tablet and mobile pages.

The mobile and tablet header places regional preferences above a separate row containing Account, Orders and the authentication control; All categories is not required to reach these links.
Signed-in members open My account / Log out to view their name, email, verification status, account dashboard, order history, Seller Centre and security settings.
Super Admin Centre is shown only to the Super Admin. Assigned staff workspace links are derived from existing account privileges and duplicate destinations are grouped. Each destination continues to enforce its own authorization.
The dropdown uses a native expandable control supporting touch and keyboard without requiring JavaScript. It scrolls within shorter viewports and contains the existing secure POST logout action.
Signed-out visitors see Log in. Account and Orders lead through the existing sign-in checks when authentication is required.

Resilient product-detail loading

Public product pages remain responsive when optional services are slow and client navigation preserves React-owned page transitions.

The product record, current user and display-currency context begin loading concurrently after the route slug is resolved.
Both approved currency providers are requested in parallel under a 2.5-second deadline instead of waiting up to eight seconds for each provider sequentially.
The first complete daily-cached rate table wins; a previously successful in-process table remains the fallback.
When no valid rate table is available, PAC-SM renders the authoritative offer currency immediately and never invents an exchange rate.
Reviews and product-programme enhancements fail independently and log a server diagnostic; their temporary unavailability can no longer replace a valid product with the generic page-load error.
Form guidance sets descriptive attributes on existing labels and renders its question marks and tooltips through CSS. It never inserts, moves or removes React-owned child nodes, preventing the insertBefore navigation crash.
The product, seller offer, stock, checkout amount and transaction currency remain server-authoritative Appwrite data.

Security hardening — Phase 2

PAC-SM adds persistent abuse controls, browser-bound OAuth state, mandatory administrator MFA and immediate session invalidation.

Authentication rate limits are stored in the private Appwrite security_rate_limits collection rather than application memory, so Coolify restarts and horizontal scaling do not reset them.
Rate-limit identities are SHA-256 hashes; raw email addresses, session secrets and network addresses are not written to the limiter collection.
Password login, registration, recovery, verification, Google OAuth and MFA endpoints use route-appropriate limits and return HTTP 429 with Retry-After when exhausted.
Google OAuth state is signed, expires after ten minutes, contains only a safe internal destination and must match a secure HttpOnly SameSite=Lax nonce cookie created by the same browser. The nonce is cleared on callback or failure.
Members enable Appwrite TOTP from Account → Security, verify a six-digit code and receive single-use recovery codes that PAC-SM displays only during setup.
Every administrative workspace requires the signed-in Appwrite account to have MFA enabled in addition to the correct least-privilege label. The application proxy independently rejects direct /api/admin calls when Appwrite has not confirmed MFA for that session.
Password changes revoke all sessions and clear the current session cookie. Assigning or revoking an administrative role revokes that user's sessions so authorization changes take effect on the next sign-in.
Deploy the Appwrite security_rate_limits schema before deploying this application release. Keep the collection server-only with empty document permissions and periodically remove expired limiter records as an operational housekeeping task.

Security hardening — Phase 1

PAC-SM keeps its production framework patched and rejects cross-site administrative mutations.

The application framework is pinned to patched Next.js 16.3.5 so production is not left on the vulnerable 16.3.1 release.
Global product imports, off-taker milestone payment changes and off-taker dispute resolutions require both the correct administrative role and a same-origin request.
Session, Appwrite, payment, email, AI and supplier secrets remain server-only and must never use a NEXT_PUBLIC prefix or enter source control.
The full-scope Appwrite provisioning key is for controlled provisioning only and must not be available to ordinary production requests.
Any credential exposed through chat, logs, screenshots, source history or an unauthorized system must be revoked and replaced at its issuing provider; secret values are never copied into PAC-SM documentation.
Run the production dependency audit, type checking, linting, domain tests and production build before deployment.

Simple seller stock control

Sellers update inventory from a product-first screen while PAC-SM preserves the governed Appwrite ledger.

Open Seller Centre → Inventory; approved offers appear by product name, brand and seller SKU with available and on-hand quantities.
Search the catalogue or filter it by in stock, out of stock or low stock, then select a product to open its Add received stock form.
Enter only newly received physical units. PAC-SM adds them to on-hand stock, creates a stock_received movement and immediately recalculates buyer availability.
The first visit automatically creates an idempotent Main stock location using the seller store's country. Sellers do not need to configure a warehouse before ordinary stock entry.
Download my stock template produces the signed-in seller's product names and SKUs. Enter positive whole numbers in quantity_received; one upload accepts up to 100 unique SKUs and never accepts another seller's offer.
Advanced inventory controls retain optional additional locations, reorder points, movement history and physical-count corrections.
A physical-count correction remains approval-based because reducing stock can affect reserved customer orders; ordinary receipts post immediately.
Every stock mutation remains tenant-scoped, transactional and stored in Appwrite. The simpler screen does not bypass reservation, checkout or audit controls.

Retail quantity and cart integrity

Standard purchases use confirmed inventory while pre-orders retain their separate capacity and terms.

The product page prioritizes an in-stock approved offer before an unavailable lower-priced offer.
Quantity controls are bounded by the lower of available stock and the seller's maximum-order quantity, and never submit below the minimum-order quantity.
Standard, pre-order and white-label selections for one seller offer are separate cart lines; adding one programme no longer blocks another.
The server independently rechecks the offer, product, vendor, purchase type, stock, minimum, maximum and existing cart quantity before every cart write.
Checkout revalidates price and inventory inside an Appwrite transaction, reserves standard stock, reserves pre-order capacity separately, creates vendor orders and then starts the selected payment provider.
Products without confirmed inventory display Pre-order only instead of presenting an invalid standard quantity range.

Public storefront addresses

Seller storefront links remain stable across browsers, proxies and shared messages.

Public stores use /store/[slug] addresses and may use either an ordinary slug or an @-prefixed handle.
The storefront route safely normalizes a percent-encoded handle before querying Appwrite, so links such as /store/%40diplomats resolve to the stored @diplomats record.
Only an active store linked to an approved or active vendor is public; unknown, inactive or ineligible records continue to return a not-found response.
Product pages, Seller Centre links and the sitemap use the store slug saved in Appwrite as the canonical seller identity.

PAC-SM vertical discovery

The active shopping marketplace remains unchanged while the homepage introduces PAC-SM's continental verticals.

The discovery layer appears directly below the established shopping hero and buyer-protection ribbon, without replacing product discovery, categories, offers or seller onboarding.
Market is marked Open now and links to the current retail and wholesale product catalogue.
Property is active and links to its verified listing marketplace; Motors, Agro, Industrial, Business, Services, Finance, Logistics and Investment remain visibly marked Coming soon.
Selecting a planned vertical opens its own branded preview page and provides clear routes back to the homepage and active marketplace.
Coming soon pages do not collect listings, finance applications, investment funds or payments and do not represent an operational launch.
The expanded search language communicates the long-term direction; submitted homepage searches continue to query the product marketplace while Property has its own specialist search.
Each remaining vertical will be activated only after its verification, compliance, operational and transaction requirements are implemented and approved.

PAC-SM Property — controlled first release

A verified property discovery and inspection workflow operating separately from retail checkout.

The homepage Property discovery card now opens /property while the successful shopping homepage and product journey remain unchanged.
Public visitors can search verified homes, apartments, land, commercial spaces, offices, warehouses and short lets by purpose, country and keywords.
A signed-in owner, developer or authorized agent can submit a listing with contact details, price, location, property facts, at least three photographs, identity evidence and ownership or listing-authority evidence.
Photographs use the product-media Appwrite bucket and remain hidden until approval. Identity and ownership evidence use the private KYC bucket and are never served by the public media route.
Every submission starts as submitted and unverified. Super Admin reviews the complete file, requests changes, rejects, suspends, or verifies and publishes it with an auditable review event.
Property operations can schedule physical, video or document inspections and preserve inspection references independently of listing publication.
Signed-in buyers can send enquiries, request future physical or video viewings, and save or unsave verified properties. Owners receive in-app notifications.
The owner workspace at /account/properties shows private submissions and their current verification status; verified records link to the public page.
The first release intentionally excludes negotiation, deposits, property checkout, escrow, commission and financial settlement until verification and inspection operations are stable.
Administrators access the Property Marketplace card in the Super Admin centre to operate the review and inspection queue.

Marketplace discovery navigation

The primary Shop and Trade & Source menus expose PAC-SM destinations through clear, responsive discovery panels.

Desktop visitors can open either panel by hovering, keyboard focus or clicking the menu heading.
The top-level labels display destination counts so they do not appear empty or inactive.
Each panel begins with a plain-language introduction and separates shopping destinations from curated collections or commercial services from seller-growth tools.
Every destination includes an icon, visible title and short description before navigation.
Keyboard users can focus the heading and move through the same links; focused links receive the same strong visual treatment as hovered links.
Touch devices retain tap-to-open behavior and present a bounded scrollable panel so destinations remain usable on smaller screens.
The links continue to use ordinary Next.js navigation and remain available without client-side JavaScript.

Seller CSV bulk product and image upload

Approved sellers can publish a validated catalogue batch and securely import authorized remote product galleries.

Open Seller Centre → Products and choose Download demo CSV template.
The protected template contains the exact twenty-seven-column schema plus two clearly labelled example rows; delete or replace the examples before uploading real products.
The first nineteen required headings cover product, variant and offer data. Eight additional required headings—image_url_1 through image_url_8—provide optional image values in primary-to-last display order.
Use the active category IDs displayed beside the upload control. Country uses two uppercase letters, currency uses three uppercase letters, fulfilment uses vendor or pacsm_logistics, and money accepts no more than two decimal places.
One file may contain at most 50 non-empty product rows, 100 remote image URLs and 1 MB of CSV data. Each product may reference up to eight images.
Image cells may be blank. Supplied values must be complete public HTTPS URLs without embedded credentials. Sellers must own the images or have authorization to publish them.
Remote imports reject IP-literal and private-network hosts, redirects, authentication, non-image responses, files larger than 8 MB, unsupported formats and content whose signature does not match its JPEG, PNG or WebP type.
The parser supports quoted commas and escaped quotes, rejects unexpected or duplicate headings, and detects duplicate slugs and seller SKUs inside the file.
Product-row validation returns row and field errors without writing any product. Valid catalogue rows are committed together in one Appwrite transaction; a database conflict rolls back the whole product batch.
After product commit, PAC-SM copies each validated remote image into the private Appwrite product-media bucket and creates approved seller-owned media records. The source server is never used as the public product image host.
A remote-source failure is reported against its CSV row without deleting successfully published products or galleries; the seller can upload the missing file manually through the existing protected media form.
Bulk products auto-publish only for the authenticated approved or active vendor, start unfeatured, and retain normal PAC-SM post-publication moderation.
The batch creates one canonical product, initial variant and seller offer per row, writes an audit event, imports available media and invalidates the public catalogue cache.

PAC-SM Jollof Rice Kit homepage campaign

The official portrait advert is presented as a responsive shopping feature without displacing core marketplace discovery.

The campaign appears after Shop by category, where customers have established shopping intent and can continue into the house-brand catalogue.
The complete supplied artwork is rendered at its original 853:1280 ratio without cropping or stretching.
The desktop layout pairs the advert with concise product benefits and clear PAC-SM Products and catalogue-search actions.
On mobile, the artwork and campaign copy stack into one full-width card while retaining readable buttons and image proportions.
The advert links to /pac-sm-products; the product-specific action searches the marketplace for Jollof Rice Kit.
Campaign placement does not bypass product approval, pricing, stock, delivery or checkout controls. Availability remains governed by current catalogue records.

Homepage back-to-top control

The marketplace footer provides a fast, accessible return to the top of the shopping experience.

The Back to top arrow is positioned inside the main homepage footer.
It uses the native #top page anchor and therefore remains functional without client-side JavaScript.
Smooth scrolling is used when the browser supports it; reduced-motion and browser preferences remain authoritative.
The control has a visible text label, an accessible name, keyboard focus styling and a minimum 44-pixel touch target.
On mobile the footer reserves extra space so the control does not overlap footer links or the fixed navigation dock.

Complete brand catalogue retrieval

Dedicated company pages load their full approved collection instead of filtering the homepage's newest-product window.

The homepage intentionally uses a bounded discovery query, but /brands/[brandSlug] queries approved products directly by the company's registered brand aliases.
A large new import cannot displace an older company's products from its dedicated page.
The Thermocool company page returns all 64 approved products and the LG company page returns all 95 approved products, provided each product retains an approved offer.
Company queries reuse the same approved-media, cheapest-offer and inventory-availability enrichment used by the public marketplace.

Company product directory

Buyers can move from the homepage to dedicated manufacturer and company catalogues.

Open Shop by Company in the homepage utility bar, select a card in Products by company, or visit /brands.
The directory initially contains Haier Thermocool, LG and Panasonic and is powered by the reusable brand registry used by the sitemap and company pages.
Every company card links to /brands/[brandSlug], where approved products are grouped by their stored brand or manufacturer aliases.
Thermocool and LG are marked Products available. The LG catalogue contains 95 approved Diplomats Stores products across Garment Care, Sound and Vision, Cold Storage, Air Cooling and Kitchen Appliances; inventory remains unavailable for checkout until physically confirmed.
LG source galleries referenced 154 files. Available files are copied into private PAC-SM Appwrite storage, while unavailable source URLs are skipped without cancelling the product import and remain identifiable through import output and audit metadata.
Panasonic is marked Catalogue coming soon until approved products and confirmed inventory exist.
Adding a future company requires one registry definition and its approved catalogue import; the shared page layout, SEO metadata and directory link are then applied consistently.
A company name shown to buyers does not change the accounting owner of an imported Diplomats Stores catalogue.

Diplomats Stores brand catalogues

Structured CSV imports publish manufacturer-named collections while Diplomats Stores remains the financial and operational owner.

SEO and performance foundation

Public marketplace discovery is search-readable and media-efficient while authenticated operational areas remain private.

The canonical production origin comes from APP_BASE_URL and must remain https://africancontinentalmarketplace.store in Coolify.
/sitemap.xml lists core public routes plus approved products and active storefronts; it safely returns core routes if Appwrite is temporarily unavailable.
/robots.txt advertises the sitemap and prevents routine crawling of API, account, cart, checkout, seller, operations and administration paths.
Private route layouts also emit noindex and nofollow directives because crawler exclusions are not an access-control mechanism.
Product pages publish unique titles, descriptions, canonical URLs, share images, Product offers, stock availability, verified-seller references, aggregate ratings when genuine reviews exist, and BreadcrumbList data.
Active storefronts publish unique metadata and OnlineStore structured data. Missing or inactive records return non-indexable not-found metadata.
Retail and wholesale landing pages use stable canonicals; product filter parameters do not become competing canonical pages.
Product and storefront records are memoized within one server render so metadata and page composition do not repeat the same Appwrite read.
Product offer stock and active stores are fetched in batches, and storefront products use one batched catalogue query instead of one request per record.
Approved product images use the Next.js optimizer with AVIF and WebP output, responsive sizes and a one-day optimized-image cache; original Appwrite files remain behind the controlled media route.
Search Console, Merchant Center, real-user Core Web Vitals and Lighthouse CI remain deployment tasks. Target LCP at or below 2.5 seconds, INP at or below 200 milliseconds and CLS at or below 0.1 at the 75th percentile.

Resend transactional email delivery

Resend delivers branded PAC-SM notifications and carries Appwrite-issued authentication messages without exposing credentials to the browser.

Verify a dedicated sending domain or subdomain in Resend with its displayed SPF and DKIM records before production delivery.
The PAC-SM Coolify application uses server-only RESEND_API_KEY, RESEND_FROM_EMAIL and optional RESEND_REPLY_TO_EMAIL variables for transactional messages.
New registrations receive a branded welcome message through the Resend HTTPS API; failure to send this non-security message never rolls back a successfully created account.
Verification and password-recovery tokens remain generated and validated by Appwrite. Configure the separate self-hosted Appwrite service with Resend SMTP: host smtp.resend.com, port 587, TLS, username resend, password equal to the Resend API key, and a sender on the verified domain.
Keep RESEND_API_KEY and Appwrite _APP_SMTP_PASSWORD server-only, rotate exposed credentials immediately, and never prefix them with NEXT_PUBLIC_.
The email adapter uses a ten-second timeout, plain-text and HTML alternatives, escaped user content and an idempotency key to reduce duplicate registration messages.
Authentication responses retain account-enumeration protection, and PAC-SM never emails or stores a user's password.

Governed AI HS6 and reusable evidence

AI accelerates classification research while human confirmation, regulatory review and reusable verified evidence control legal readiness.

AI HS6 requires a completed structured export profile and is available only to approved sellers for their own products.
The structured response includes HS2022 chapter, heading, six-digit subheading, confidence, reasoning, alternatives, missing-fact questions and attributes used.
The assistant cannot return destination tariff extensions, tariffs, duties, regulatory requirements or legal eligibility.
A hierarchy guard requires HS6 to begin with its four-digit heading and two-digit chapter before storage.
Generated records start as AI_SUGGESTED; sellers can record VENDOR_CONFIRMED classifications, and Trade Compliance can approve as PACSM_REVIEWED or reject.
Sensitive pharmaceutical, chemical, medical, dual-use, machinery, animal and plant categories remain human-review-sensitive regardless of confidence.
Evidence Vault links one private Appwrite trade document to a requirement code and multiple owned products, including issuer, validity and HS coverage.
Evidence starts as verification_required; only verified, unexpired evidence can satisfy a mandatory rule.
AI generation and classification review events are written to Appwrite audit logs without treating model output as law.

Product-level ExportReady engine

PAC-SM calculates market-specific readiness from governed classification, destination tariff extensions, effective regulatory rules and verified evidence while keeping domestic selling independent.

Approved sellers open Seller Centre → ExportReady and build a structured profile for an owned catalogue product, including manufacturing country, intended use, process, material origins, packaging, target countries and category-specific facts.
Seller Centre → Trade Codes provides governed links to WCO HS 2022, AfCFTA e-Tariff, EU Access2Markets, UK Trade Tariff, US HTSUS and Schedule B, Canadian Customs Tariff, UN/LOCODE, UNECE package codes, GS1 GTIN and ICC Incoterms.
The downloadable export-codes CSV is a research worksheet for product identity, HS6, destination tariff code, source, Incoterm with named place, transport mode, UN/LOCODE, package code and GTIN; example values must be replaced and verified before use.
International HS6 is stored separately from destination national tariff extensions. Each destination record retains country, code system, official description, authority, source URL, nomenclature version, confirmation status, actor and timestamp.
Origin and destination use controlled country selections; destination tariff systems and HS/Incoterm values use controlled registries or format validation instead of unexplained free text.
Classification statuses are AI_SUGGESTED, VENDOR_CONFIRMED, PACSM_REVIEWED, CUSTOMS_BROKER_VERIFIED and CUSTOMS_RULING_VERIFIED; AI output is never silently treated as a legal determination.
The versioned rules engine filters published rules by origin, destination, HS prefix, product category and effective source version instead of hardcoding requirements in UI components.
Requirement taxonomy separates exporter, product, manufacturer, facility, shipment, customs, importer, origin, labelling, packaging, testing, certification, licensing, registration, SPS, environmental, safety and conformity obligations.
Legal status distinguishes mandatory, conditional, recommended, voluntary, buyer-specific and preference-required items.
Every regulatory rule must cite an authority, official URL, source hierarchy, jurisdiction, effective date, last verification, next review and version.
Assessment status is READY, CONDITIONALLY_READY, NOT_READY, REVIEW_REQUIRED, PROHIBITED or RESTRICTED for one product and destination; there is no unsupported global export-ready badge.
Verified evidence can satisfy matching requirement codes; expired or unverified evidence cannot satisfy a mandatory finding, and a mandatory failure overrides the numerical readiness score.
Existing Trade Passport, certification, private document and shipment workflows remain connected operational foundations; the new product matrix does not block otherwise valid domestic listings.
Trade Compliance staff and Super Admin use Regulatory Control Centre to publish source-backed rule versions and monitor classifications and assessments, with changes written to the audit log.
Official references are seeded as governed regulatory sources with review dates. Actual product conclusions still require current source review and, where risk warrants, a qualified customs broker or binding ruling.

Universal product-upload entry

A persistent marketplace action guides every user to the correct seller-onboarding or product-publishing stage without bypassing verification.

Upload new product is visible from the homepage and every customer, seller, operational, help and administration page.
Visitors are sent to sign-in with /sell/upload retained as the safe internal return destination; they may register an account from the authentication journey.
Signed-in users without a vendor record continue to the full vendor registration, KYC/KYB, settlement and storefront application.
Existing applicants who are pending, rejected or otherwise inactive see their application status and cannot enter product publishing.
Only approved or active vendors are redirected to Seller Centre → Products, where normal product validation, automatic publication and post-publication moderation remain in force.
The persistent action supplements existing seller-registration and Seller Centre links rather than replacing them.

Distributor onboarding

Qualified distributors enter PAC-SM through a dedicated opportunity page and the established governed vendor-review process.

The homepage displays a prominent Want to become a distributor opportunity panel, with additional entry points in Trade & source and the Sell footer.
/distributors explains market access, operational benefits, readiness requirements and the four-step approval journey before asking for business data.
Visitors sign in or create an account and return safely to the application with Distributor already selected as the vendor type.
The application collects business identity, ownership, operating address, settlement, storefront and required KYC/KYB documents through the existing secure vendor endpoint.
Distributor applications use the same Appwrite vendor, business, compliance, store, private-document, administrator-review and audit records as other sellers; no parallel local backend or ungoverned account type is introduced.
Approval activates the normal Seller Centre and storefront capabilities. PAC-SM may request information, reject an unsuitable application or moderate products under the existing marketplace standards.

AI-assisted catalogue drafting

Approved sellers can generate structured, editable product-copy suggestions without delegating factual responsibility or publication control to AI.

Enter a product name in Seller Centre → Products before requesting a draft; category and optional seller-supplied facts improve the suggestion.
The assistant proposes a URL slug, description, specifications, generic variant information, catalogue keywords and questions for missing facts.
Fill empty fields preserves work already entered; Replace draft fields is an explicit seller action and still does not submit the form.
Brand, manufacturer, origin, ingredients, dimensions, certifications, regulatory status, GTIN, stock and prices must come from verified seller records and are never intentionally invented by the assistant.
Only authenticated approved or active sellers may call the same-origin endpoint, with ten attempts per ten-minute application instance window.
Enable it with the locked server-only OPENROUTER_API_KEY Coolify secret. Local development may instead use OPENROUTER_API_KEY_FILE to reference a protected key file outside the repository. OPENROUTER_MODEL selects the default model and OPENROUTER_PRODUCT_MODEL can override it; none of these variables may use a NEXT_PUBLIC prefix.
OPENROUTER_STRUCTURED_OUTPUT_MODE normally remains json_schema. Set it to json_object only for a provider endpoint, such as the current Apodex free endpoint, that rejects JSON Schema; PAC-SM still validates the returned object against its own strict Zod schema before use.
Requests transmit only product drafting inputs, require compatible structured-output routing, validate the result against PAC-SM's strict schema and record successful generation metadata—not generated copy—in Appwrite audit logs.
The seller remains responsible for reviewing accuracy and PAC-SM retains its normal post-publication moderation rights.

Shared PAC-SM brand identity

The official PAC-SM logo uses one proportionally scaled brand space throughout the application.

The desktop logo space is increased from 112 × 64 pixels to 157 × 90 pixels, an exact 40 percent scale increase after whole-pixel rounding.
The mobile logo space is increased from 94 × 54 pixels to 132 × 76 pixels using the same 40 percent scale factor.
Contain sizing preserves the source logo aspect ratio without stretching or cropping.
Navigation containers expand to accommodate the larger mark without overlapping links, search, account or storefront controls.

Continental commerce module design standard

Off-takers, Procurement, Trade and Logistics use a shared production UI system that future operational modules should follow.

CommerceModuleHeader provides one cross-module navigation for Off-takers, Procurement, Trade and Logistics plus marketplace and contextual account links.
CommerceModuleHero standardizes the eyebrow, title, explanation, workflow status, metric and responsive hero composition while supporting a restrained module-specific color tone.
Off-taker Centre uses structured demand publishing, supplier proposal cards, award controls and supply-agreement tables.
Procurement uses structured RFQ creation, portfolio monitoring and a dedicated quotation-comparison screen with purchase-order conversion.
Trade Passport uses consistent readiness metrics, compliance forms, private-document controls and trade-record tables.
Logistics uses carrier trust signals, official-partner presentation, carrier cards, route summaries and a matching shipment-tracking experience.
Shared module panels standardize headings, fields, buttons, alerts, success messages, tables, cards and empty states.
Desktop, tablet and mobile breakpoints are defined centrally in commerce-modules.css; future commerce pages should reuse these primitives instead of introducing isolated page styles.
All module pages retain the global country, language, currency and Back to home controls.

Professional retail marketplace

Retail discovery and product purchasing use a responsive, trust-led commerce experience.

Open /products?market=retail for the dedicated retail catalogue.
The retail header keeps product search, account, wishlist, cart, marketplace channels, seller registration and order tracking accessible.
Category shortcuts and the filter panel support text search, category selection, buying format and in-stock filtering.
Results can be sorted by featured order, lowest price, highest price or product name; filtering and sorting remain server-authoritative.
Product cards present approved imagery, brand or seller context, retail or MOQ badges, stock urgency, display-currency pricing and a clear product action.
The product-detail page combines an approved media gallery, product origin and model, verified-review summary, buyer-protection cues and a sticky best-offer purchase panel.
All active seller offers remain comparable by store, buying format, available stock, price and quantity before cart submission.
The experience adapts to tablet and mobile layouts while preserving search, filters, two-column mobile product browsing and the global Back to home control.

Wholesale product and transaction experience

Wholesale discovery and transaction entry are separated to provide a focused, responsive buying experience.

/wholesale is the discovery catalogue and shows concise product cards rather than embedded transaction forms.
Selecting an offer opens /wholesale/[offerId], a dedicated full-screen product workspace.
The workspace presents the approved product image, origin, description, fulfilment information, processing time, MOQ, maximum quantity and every published price tier.
Approved business buyers can choose Continue to secure checkout for the listed tier price or submit a structured negotiated-price request.
Negotiation inputs occupy their own responsive panel and include quantity, proposed price, delivery country, required date and commercial message.
Unauthenticated users retain the selected product as their post-login destination, while unregistered or pending business buyers receive a clear access explanation.
Validation failures return to the same selected product with a visible message instead of dropping the buyer back into the catalogue.
Customer-facing pages using the shared marketplace shell now use modern navigation, elevated responsive cards, consistent form controls and mobile spacing aligned with the homepage visual system.

Official logistics partner

Zenith Carex Express is identified across PAC-SM as the official logistics partner.

A compact Zenith Carex Express partner panel appears near the bottom of the homepage, immediately before newsletter and footer content, and the partner also appears on /logistics.
The smaller panel uses a responsive horizontal layout on tablets and most phones, then stacks cleanly on very narrow screens.
The supplied logo is stored as a local application asset and rendered with contain sizing so its original proportions are preserved.
The partnership display directs users to the Logistics marketplace and shipment-tracking workflows.
Carrier availability, route coverage, service rates, shipment assignment and tracking statuses continue to use PAC-SM's verified logistics records and controlled workflows.
Other logistics companies may still apply through Become a carrier and enter the verification process.

Super Admin wholesale negotiation access

Wholesale price requests are exposed as a priority operation in the Super Admin Centre.

Use the highlighted Wholesale Negotiations sidebar link, the Review buyer negotiations banner near the top of the dashboard, or the Wholesale Negotiations operations card.
All three controls open /admin/wholesale-negotiations.
The queue displays the negotiation reference, product, status and available action.
Review & respond is available only for PAC-SM-owned and demo-product negotiations.
Super Admin can accept the buyer price, reject it or issue a counteroffer while preserving the administrator's identity in the audit timeline.
Independent-seller negotiations remain visible for oversight but must be answered by the owning seller from Seller Centre → Wholesale.

Checkout address handoff

A buyer who needs a delivery address can save it without losing the active retail or wholesale checkout.

Checkout links to /account/addresses with a protected internal /checkout return destination.
The address form preserves that destination through its POST request.
After Appwrite confirms the address was created, PAC-SM returns the buyer directly to checkout using a 303 redirect.
Checkout reloads the active server-authoritative cart and address list, selects the first available address and enables Place order and pay.
External or protocol-relative return destinations are rejected; only internal PAC-SM paths are accepted.
Opening Saved addresses from the Account page without a checkout destination retains the normal Address saved confirmation page.

Wholesale checkout and payment cycle

Published wholesale tiers and accepted negotiations both progress into secure delivery, payment and fulfilment.

Only an approved business buyer can begin wholesale checkout.
For a listed offer, PAC-SM resolves the most specific eligible quantity tier, verifies stock and creates the purchase order and checkout item in one Appwrite transaction.
For an accepted negotiation, the purchase order preserves the negotiation as its source and locks the accepted quantity, unit price and currency.
Both paths redirect directly to /checkout, where the buyer selects a saved delivery address and DemoPay, Paystack or PAPSS according to configured availability.
Checkout independently revalidates the purchase order, its line item, buyer ownership, seller, offer, quantity, price, currency, product approval and available inventory.
Negotiated checkout additionally verifies that the acceptance is unexpired, unused and belongs to the signed-in buyer.
Successful order creation stores the purchase-order reference on each wholesale order item, marks the purchase order converted, reserves stock and starts payment immediately.
Successful payment continues through the standard vendor-order, warehouse, dispatch, delivery, finance, return and dispute controls.

Platform overview

PAC-SM combines retail, wholesale, procurement, fulfilment, logistics and trade compliance in one Appwrite-backed marketplace.

The official PAC-SM logo is served from the application asset directory and fitted proportionally into the shared brand space across desktop and mobile interfaces.
Open FAQ or Documentation from the homepage utility menu or the Support footer.
Retail and wholesale product discovery
Multi-vendor ordering and inventory reservation
Vendor, carrier and business-buyer verification
Procurement RFQs and quotations
Trade Passport, standards and certification
Scoped merchant APIs and signed webhooks

Accounts, navigation and regional preferences

Account sessions are server-mediated, navigation remains consistent and regional settings appear across the entire application.

The homepage account control reads Hello, sign in for visitors and switches to a server-rendered Hello, [first name] greeting immediately after a valid password or Google session is established.
The greeting uses the Appwrite account name, with a safely normalised email-name fallback, and never relies on browser-supplied identity text.
Every route below the root layout displays a fixed Back to home link except the homepage itself.
The global home link covers customer, authentication, account, checkout, wholesale, seller, staff and administrator interfaces without relying on page-specific menus.
The control is keyboard accessible, has a visible focus state and moves above the marketplace mobile dock on small screens.
Register with a normalized email and strong password, or use Register with Google after the Appwrite Google provider is enabled.
Google OAuth uses Appwrite's one-time token exchange and a ten-minute HMAC-signed state token with a random nonce, timestamp and safe internal return path; it does not rely on a transient browser state cookie.
Email-and-password registration sends a verification link after Appwrite SMTP is configured. The user explicitly submits the verification to avoid link-scanner consumption; a missing session returns through sign-in without losing the token.
Verification can be resent from Account, while already verified accounts are detected before another email is requested.
Country resolution covers all 54 sovereign African countries and uses saved preference, profile, trusted proxy header, then Nigeria fallback.
English, French, Arabic, Portuguese, Kiswahili and Spanish use server-rendered dictionaries with English phrase fallback; Arabic uses right-to-left layout direction.
Seller-authored catalogue content is not silently machine-translated.
The currency selector includes every currency used by African sovereign states and selected global trading currencies.
Public catalogue prices convert through a daily server-cached ExchangeRate-API rate table.
Checkout, orders, refunds and settlements retain the source transaction currency; display conversion is informational.
If a rate is unavailable, the original offer currency is shown without an estimated substitute.

Coolify deployment health

PAC-SM separates process liveness from dependency readiness so rolling deployments do not route traffic to an unhealthy container or reject a healthy process.

Docker and Coolify call /api/health/live through 127.0.0.1:3000 to confirm that the Next.js process is accepting requests.
The liveness route returns a lightweight response without requiring Appwrite, currency, catalogue or third-party supplier availability.
Canonical production-host redirects explicitly bypass /api/health/live and /api/health/ready, so an internal probe never loops through the public Traefik route while the new container is awaiting health approval.
/api/health/ready separately checks the configured Appwrite database and may return 503 when that dependency is unavailable.
Coolify should use /api/health/live for container health and retain /api/health/ready for dependency monitoring and diagnostics.
The application listens on 0.0.0.0:3000 in the production image and the Docker healthcheck calls the same internal port.

Country and telephone data

PAC-SM separates geographic country identifiers from international telephone numbering.

Country selectors display a flag and full country name but submit a validated ISO 3166-1 alpha-2 code such as NG, GH or KE.
Telephone controls use a separate country selector that displays the international calling prefix, including one-, two- and three-digit prefixes.
New delivery-address, vendor, assisted-seller, carrier and off-taker telephone numbers are normalized on the server to E.164 format with a leading plus sign and no formatting characters.
A local leading zero is removed when the selected international prefix is applied; a number already beginning with plus is validated and retained in normalized form.
The server rejects unsupported countries, malformed phone values and numbers exceeding the E.164 fifteen-digit maximum.
Existing Appwrite records are not rewritten automatically because their original country context may be uncertain; they remain available until verified or updated through a controlled workflow.

Customer marketplace

Customers can search, compare, buy and manage marketplace activity.

Open PAC-SM Products from the homepage menu for the dedicated house-brand agro, food and beverage storefront.
The immersive 500-pixel homepage carousel rotates up to twelve image-backed PAC-SM, LG, Thermocool, Global Stores and other published catalogue products. It excludes products without usable images and scarf or wrap listings; controls support manual selection and reduced-motion preferences.
Search by name, description, brand, category and market type.
If a product is missing, Product Scout records the requested product, brand, quantity, reference and contact email for Super Admin review at /admin/product-requests; this does not create an order or guarantee supply.
Add approved offers to a server-authoritative cart.
Checkout collects delivery address, optional coupon and payment method on one page.
Place order and pay reserves inventory, creates the parent and vendor orders, and immediately starts the selected payment.
If provider launch is interrupted, the order stays pending and can be paid from its order page.
Track fulfilment, payments and shipments from Orders.
Create eligible returns, disputes, verified reviews and order messages.
Use wishlist and notification centres for ongoing engagement.

Open marketplace View orders

Product-level pre-order and white-label negotiation

Pre-order is a universal retail action and white label is a universal wholesale negotiation path.

Every approved retail product card exposes Pre-order and every retail product page contains seller-specific pre-order controls.
A seller's configured opening time, closing time, capacity and dispatch date take priority. Where none exists, PAC-SM initializes standard protected terms from the approved offer's processing time and maximum quantity.
Pre-order does not require on-hand stock; checkout revalidates the active window and atomically reserves production capacity.
Every wholesale product advertises white-label negotiation and its full-screen transaction page contains a structured private-label request form.
White-label requests require an approved business buyer, proposed quantity and unit price, brand name, delivery country, customization brief and optional date and commercial message.
White-label price, quantity and commercial terms use the existing alternating offer, counteroffer, acceptance and rejection workflow.
No white-label request enters checkout until accepted. The accepted negotiation ID, purchase type, brand, customization brief and promised dispatch date are copied into cart and immutable order records.
Buyers and sellers see the white-label brief inside the negotiation workspace; sellers see it again in fulfilment.
Retail pre-orders and accepted white-label transactions continue through address, payment, commission, vendor order, delivery, returns and disputes.
The dedicated /pre-orders and /white-label pages remain discovery channels, while the principal actions now live on each relevant product.

PAC-SM flour private label and contract manufacturing

PAC-SM's own Bean Flour and Plantain Flour programme is distinguished from independent seller programmes on the White-label Marketplace.

Eligible products are Premium Bean Flour and Premium Plantain Flour in 1kg packs, with 12 packs per carton.
The minimum order is 120 packs, equal to 10 cartons.
Contract production requires the customer to supply pouches or packaging, labels and brand artwork; PAC-SM provides raw materials, processing and milling, filling and sealing, batch coding, quality control and carton packing.
Private label requires the customer to supply approved brand artwork or a label; PAC-SM provides the premium flour, 1kg food-grade pouch, filling and sealing, label application, batch coding, quality control and carton packing.
Full private label requires the customer to supply a brand identity. PAC-SM provides raw materials, processing, packaging, label-design support, label printing and application, filling, sealing, batch coding, quality control and carton packing.
The May 2026 Bean Flour schedule is NGN 4,000, 4,500 and 5,000 per pack for contract production, private label and full private label respectively; carton values are NGN 48,000, 54,000 and 60,000.
The May 2026 Plantain Flour schedule is NGN 4,200, 4,700 and 5,200 per pack for those levels; carton values are NGN 50,400, 56,400 and 62,400.
Orders of 120–359 packs use the standard schedule, 360–719 packs receive a stated 5% volume discount, and 720 or more packs are negotiable.
Custom printed pouches, specialised packaging, product formulation, laboratory analysis, regulatory registration and other agreed services are quoted separately.
The displayed schedule is indicative, was effective May 2026, may change without prior notice and remains subject to final PAC-SM confirmation of specifications, capacity, compliance, delivery and applicable terms.
The PAC-SM programme does not silently govern independent manufacturers; their published offer terms and negotiation records remain authoritative.

Vendor onboarding and Seller Centre

Vendor access follows self-service or controlled assisted onboarding with strict ownership checks.

The homepage prominently displays Register as a seller; it opens /vendor/register, and unauthenticated applicants return there automatically after sign-in.
Applicants provide contact, legal business, ownership, local settlement, store and KYC/KYB document information before review.
SWIFT/BIC and exporter-registration numbers are excluded from the ordinary vendor-registration form and are not required to create a storefront application.
Vendors that later enter cross-border trade can provide applicable exporter information through Seller Centre → Digital Trade Passport, where it remains optional and separate from basic marketplace onboarding.
A Super Admin can appoint Seller Onboarding Managers from Admin Team.
Authorized onboarding staff create the Appwrite login, active vendor identity and store; temporary passwords are not stored and must be changed at /account/security after first sign-in.
Only approved or active sellers can publish catalogue records; pending, rejected or suspended vendor accounts cannot use the seller publishing route.
Approved-seller product, variant and offer records are assigned live status immediately and the publication is written to the audit log.
Validated JPEG, PNG and WebP product images publish immediately for approved sellers; the first image becomes primary and original files remain in private Appwrite storage behind the controlled media route.
Post-publication moderation lets Super Admin request changes, take a product down, reject it, restore it or permanently delete it. Product and offer visibility change together, and every moderation decision records the responsible administrator, reason and timestamp.
A suspended, rejected or changes-requested product is excluded from public catalogue and checkout queries until restored.
Self-service applicants complete business, beneficial-owner, banking and store fields and upload registration, tax and identity evidence privately.
Approved sellers manage products, inventory, orders, wallet, analytics, RFQs, wholesale, warehousing, compliance, trade and integrations.
Every store uses one responsive PAC-SM storefront template; Seller Centre → My Store lets the owner upload a proportionally fitted logo and select validated primary and accent colours without changing the shared customer experience.
PAC-SM Products uses the same storefront component and visual rules as independent seller stores.
Seller Centre → Wallet calculates ledger, pending-claim and available balances from posted vendor-payable journal lines. A withdrawal cannot exceed the unreserved available balance.
Withdrawal requests use the seller's verified settlement destination and remain reserved while pending. Super Admin reviews them at /admin/withdrawals; payment creates the settlement, withdrawal status and balanced journal entry in one Appwrite transaction.
Rejected claims release the reserved amount, while paid claims remain linked to their settlement and audit history.
All seller reads and mutations are scoped to the authenticated vendor.

Vendor application Seller Centre

Wholesale and procurement

Approved business buyers and sellers use structured commercial workflows.

Wholesale tiers support minimum and maximum quantities.
Buying at the listed wholesale price creates a purchase order immediately and displays a visible success or validation result.
Negotiation is enabled by default for wholesale offers, including PAC-SM demo offers without a separate settings record; sellers can disable it or configure minimum quantities, confidential price floors, maximum discounts, counteroffers and expiry per offer.
Approved buyers submit price requests from /wholesale and monitor them at /wholesale/negotiations; sellers respond from Seller Centre → Wholesale.
The negotiation state machine alternates seller and buyer turns: the receiving party may accept, reject or counter the latest proposal. The interface identifies the responsible party and preserves every proposal in an immutable timeline.
A response commits its current price, quantity, status, event and recipient notification atomically so a partial counteroffer cannot be displayed as a failed response.
Action failures use safe, specific guidance for expiry, turn ownership, disabled counteroffers, invalid values and seller pricing limits.
For PAC-SM-owned or demo inventory only, Super Admin may act as the platform seller at /admin/wholesale-negotiations. The actual administrator identity and proxy action are written to negotiation events and audit logs; independent seller negotiations cannot be proxied.
Accepted prices are single-use and bound to the buyer, seller offer, currency, exact quantity and expiry. Checkout revalidates all terms and stock inside the order transaction before recording the negotiation reference on the order item.
Super Admin monitors commercial activity at /admin/wholesale-negotiations. Financial commission, refunds and settlement calculations use the negotiated order amount actually paid.
Purchase orders preserve buyer, vendor, pricing and source information.
Proforma invoices are generated from commercial purchase orders.
RFQs support supplier invitations, quotations, negotiation history and award conversion.

Off-taker ecosystem

Verified companies publish recurring demand and operate auditable multi-supplier supply agreements.

Open Off-takers in the homepage marketplace menu or use Off-taker registration in the Trade footer.
Companies register at /offtakers/register with legal, contact, sourcing, delivery and commercial information for KYB review.
The Super Admin can appoint an Off-taker Verification Manager and authorized staff approve, reject or request more information at /admin/offtakers.
Approved off-takers publish product specifications, volumes, frequency, packaging, certification, origin, deadline, delivery and payment terms from /offtakers.
Verified sellers respond from /seller/offtake with quantity, unit price, lead time, certifications and negotiated terms.
Off-takers can shortlist, request revision, reject or award proposals and split demand among several suppliers.
Awards form one supply agreement per requirement and create supplier-specific PAC-PO scheduled purchase-order references.
Authorized staff record delivery inspection and accepted quantities before operational settlement.
Payment milestones track due, processing, paid, settled and failed states; a paid status is an operational record and does not replace an approved payment connector.
Agreement or scheduled-order disputes retain category, description, review state and resolution history.

Orders, finance and trust

Order and finance state changes are controlled and auditable.

Checkout revalidates price, approval and available stock, then creates one parent order with vendor-specific child orders.
Inventory reservations prevent overselling while the order awaits payment.
Buyers can retry an interrupted payment from the order page without recreating the order.
Demo capture exercises the complete Appwrite transaction, inventory, ledger and notification path.
Paystack is initialized only on the server and capture requires verified reference, status, order metadata, amount and currency.
PAPSS is a provider adapter awaiting certified merchant or participating-bank onboarding details; no unverified browser callback can release goods.
Provider secrets remain server-only. Successful capture is idempotent and atomically converts reservations into stock sales.
Commission, refunds and settlements use balanced journal records.
Returns, disputes and verified reviews provide buyer-protection controls.

Fulfilled by PAC-SM

Warehouse teams manage inbound stock through dispatch.

Inbound shipment notices and expected quantities.
Receiving reconciliation and shortage visibility.
Put-away into controlled warehouse bins.
Pick tasks, packing and fulfilment packages.
Role-separated receiving, picking, packing and management privileges.

Carrier and logistics marketplace

Verified third-party carriers publish coverage and fulfil assigned shipments.

Carrier onboarding includes registration, insurance, fleet and private documents.
Logistics staff approve applications and activate carrier numbers.
Carriers publish route-level base and weight rates.
Dispatchers assign existing shipments to verified carriers.
Carrier tracking uses controlled state transitions and exception recovery.
Public tracking exposes safe timeline information and delivery confirmation.

Logistics marketplace Track shipment Carrier application

Export Protocol Engine

Corridor-aware protocol packs organize the parameters and evidence needed for AfCFTA, UK DCTS, EU, Canada, United States and Caribbean destinations without pretending to issue a customs decision.

Approved sellers use the prominent Export Protocol Centre banner immediately below the Seller Centre header; pending sellers see the same workspace identified as awaiting approval.
Seller Centre → Export Protocols lists every destination assessment as a protected protocol pack.
Each pack identifies its corridor, HS decision, readiness, blocking mandatory evidence, applicable versioned rules and official sources.
The complete case dataset covers parties, product identity, bill of materials and origin, shipment, customs valuation, duty and tax, SPS/TBT controls, documents and governance.
A zero-rule result is Rule research required, never Ready; a completed evidence check progresses only to qualified professional review.
AfCFTA preference depends on the operational origin-destination schedule, tariff line, product-specific origin rule and acceptable proof of origin.
UK DCTS, EU, Canada, United States and Caribbean requirements are evaluated by destination country and product rather than by a universal checklist.
AI may assist classification and explanations, but customs brokers, competent authorities and regulators make authoritative decisions.
Trade administrators publish only effective-dated rules with an official authority, source URL, version and next-review date.

Trade Passport and cross-border operations

Trade records support export readiness without claiming regulatory authority.

Vendors declare exporter details, target markets, product groups and Incoterms.
Readiness scoring reflects profile, certification and document completeness.
Trade officers approve, reject or request additional information.
Cross-border shipments record origin, destination, HS codes and customs status.
Trade documents remain private and every decision creates an audit event.

Standards, packaging and certification

Destination rules are maintained as structured, source-backed registry records.

Standards are filtered by product category and country.
Packaging rules cover materials, labels, handling and weight limits.
Certification rules identify authority, mandatory status and validity.
Verified quality centres publish services and accreditations.
Sellers apply against owned products; trade staff control review and testing status.
Registry administrators should use only authoritative sources.

Standards Hub Seller compliance

Merchant API and webhooks

Approved vendors can integrate ERP, POS, warehouse and logistics systems.

Create sandbox or live API credentials and copy the key once.
Available scopes: products read, inventory read/write, orders read and webhook management.
Version 1 endpoints live under /api/v1/merchant.
Credentials are hashed, rate-limited, vendor-scoped and revocable.
Webhook deliveries include HMAC signatures, event IDs, attempt state and response logs.
The Developer Portal contains endpoint and verification examples.

Developer Portal Integration console

PAC-SM Trade & Export Academy

The Academy is a signed-in, Appwrite-backed learning environment with its own curriculum, dashboard, access roles and durable learner records.

Open Trade Academy from the homepage utility bar, marketplace menu, continental-services area, Trade footer or My Account.
The first curriculum version contains ten modules, 36 estimated guided hours and 40 structured lessons based on the approved PAC-SM trainer material.
Curriculum terminology uses African product or service for the integrated export project and PAC-SM for platform exercises; older Integra references are not exposed in learner-facing content.
Members enrol explicitly and receive a version-bound academy_enrollments record.
The learner dashboard shows progress, course status, pass standard and sequential access across the ten-module roadmap.
All 40 lessons include a long-form reading derived from the approved trainer notes, with objectives, explained concepts, commercial examples, key takeaways, reflection prompts and practical application.
Versioned long-form readings are stored separately from lesson metadata in academy_lesson_content, avoiding Appwrite collection attribute-size limits while keeping curriculum records in the configured backend.
A future lesson without its full reading is identified as being prepared and cannot be marked complete; a curriculum summary alone is not treated as course content.
Lesson completion is stored in academy_lesson_progress. Each module then presents a 15-question, 30-minute assessment with a 70% pass standard and maximum of three attempts; passing unlocks the next module.
The 150 approved questions are stored in academy_questions. Only prompts and options reach the learner; answerKey is an encrypted Appwrite attribute used exclusively by server-side marking after submission.
Attempt identity, start, expiry, answers, marks and result are retained in academy_attempts and academy_responses. Expired, foreign or previously graded attempts cannot be submitted.
After all ten assessments, /academy/project opens a ten-section complete export-plan workspace. Drafts and submissions are stored in academy_projects and academy_project_milestones.
The capstone rubric totals 100 marks: opportunity 10, market 15, readiness 10, compliance 15, pricing/Incoterm 15, logistics 10, buyers 10, finance 5, risk 5 and practical defence 5.
Academy Assessors grade submitted projects in /admin/academy. A score below 70 requests changes; a passing score completes the enrolment and issues one active version-bound certificate.
Certificates have unique numbers and public verification codes at /academy/certificates/[code]. Revoked or unknown codes do not produce a valid credential page.
Academy Administrator, Content Manager, Instructor and Assessor are separate cumulative privileges controlled through Admin Team.
Authorized Academy staff use /admin/academy to monitor curriculum version, enrolments, completed lessons, assessment activity, projects awaiting review and issued certificates.
Academy completion does not itself confer government, customs, food-safety or professional accreditation.
Learner identity, curriculum version, attempt history, assessor identity, marks, feedback and certificate evidence remain durable audit records.

Governed OpenRouter marketplace intelligence

OpenRouter turns PAC-SM's measured marketplace read models into bounded explanations and action plans without replacing authoritative calculations or human decisions.

Super Admin opens Marketplace Intelligence and runs the measured refresh before requesting an AI brief.
The deterministic layer calculates 30-day demand forecasts, category-affinity product recommendations and order-review risk scores from Appwrite transaction records.
One bounded OpenRouter request receives at most the latest 20 records in each advisory area plus aggregate counts; it is instructed not to invent products, sales, people, evidence, laws or obligations.
The structured response is validated with a strict PAC-SM schema, and demand, recommendation, risk and export identifiers not present in the supplied snapshot are discarded before storage.
Marketplace Intelligence displays an executive brief and action cards for demand forecasts, product recommendations, fraud and risk review, and export readiness.
A fraud signal is an investigation lead, never proof of misconduct. AI cannot suspend an account, reject an order or impose an enforcement outcome.
Export insight explains existing versioned findings only. It cannot publish a regulatory rule, issue a customs ruling, grant market access or replace a broker or competent authority.
Insights, model, confidence, generating administrator and timestamp are stored in the private ai_insights Appwrite collection; each generation also creates an audit-log event.
If OpenRouter is unavailable or returns invalid data, existing measured forecasts, recommendations, risk signals and export assessments remain available and unchanged.
Configure the locked server-only OPENROUTER_API_KEY, OPENROUTER_MODEL and optional OPENROUTER_INTELLIGENCE_MODEL. Local development can use OPENROUTER_API_KEY_FILE outside the repository. Never expose any of these through NEXT_PUBLIC variables.

Administration and intelligence

Administrative centres separate sensitive operational responsibilities.

The first highlighted operations card in Super Admin Centre is Product Management; it opens /admin/catalogue for automatic-publication oversight, legacy approvals, image moderation, takedown, restoration and deletion.
User & Seller Accounts is the Super Admin-only unified directory for Appwrite users, contacts, account state, verification, seller/store status, registration dates and active administrative roles.
The directory supports search by name, email, phone, store or merchant ID and filtering by account type.
Each directory row opens an account-lifecycle review showing Appwrite status, email verification, active sessions and permanent-deletion eligibility.
Suspend blocks authentication and revokes every session while retaining required marketplace records; Reactivate restores an eligible suspended account; Revoke sessions signs the member out on every device without disabling the account.
Every lifecycle action requires a written administrative reason and creates an Appwrite audit record with actor, target, action and timestamp.
The protected Super Administrator cannot be suspended, remotely signed out or deleted through the application.
Permanent deletion requires the exact DELETE email confirmation and is restricted to non-privileged customer accounts without seller, administrator, financial, fulfilment, return, dispute, wholesale, procurement, off-taker, carrier, risk or Academy dependencies.
Eligible deletion removes disposable profile, address, cart, wishlist and notification data before deleting the Appwrite authentication identity. Accounts with retained obligations must be suspended instead.
Admin Team retrieves registered authentication accounts directly from Appwrite in paginated batches and presents a searchable name/email selector instead of requiring manual email entry.
The selector reports verified or unverified state, marks protected or disabled accounts, and prevents those unavailable records from being submitted. Assignment is bound to the selected Appwrite user ID and the server retrieves the canonical email before writing access records.
Admin Team lets the Super Admin select several privileges for one registered account in a single grant. Readable underscore role IDs remain in admin_members and audit records, while account authorization uses deterministic alphanumeric labels accepted by Appwrite 1.8.1.
Every delegated administrator sees an Administrative access section on /account. It lists all active roles and links only to operational centres that accept that role, preventing misleading links to Super-Admin-only pages.
Bulk assignment distinguishes missing accounts, disabled accounts, protected Super Admin accounts, missing Appwrite users.read/users.write scopes and record-write failures.
Each assigned privilege can be revoked separately without removing the administrator's other roles. Super Administrator access remains excluded from ordinary role management.
Order Fulfilment Managers use the separate /operations centre and cannot access Super Admin configuration or unrelated administration.
Orders & Delivery shows payment capture, complete buyer contact and shipping details, purchased products, quantities, identifiers and vendor-order progress in one operational view.
Delivery records include recipient and account phone numbers, both street lines, city, state or region, postal code, country and the stored address identifier.
Payment records include provider, status, amount, payment number, creation and capture time, and internal identifier.
Sensitive buyer and delivery details are restricted to authenticated Super Admins and appointed Order Fulfilment Managers.
Unpaid orders cannot enter fulfilment; paid orders move through processing, warehouse picking and packing, carrier dispatch and confirmed delivery.
Dispatch requires a carrier and tracking number and creates the customer-visible shipment timeline.
Vendor, carrier, business-buyer, catalogue and certification review.
Warehouse, logistics, finance, settlements, returns and disputes.
Analytics for orders, vendors, products, disputes and reviews.
Demand forecasts, recommendation read models, fraud signals and background jobs.
Redis and external search remain deferred until measured demand requires them.

Administrative alerts and daily reconciliation

Role-scoped operations alerts and stored daily controls help staff move paid orders through delivery and investigate mismatches.

The administrative bell is rendered only for Super Admin and accounts holding at least one active operational privilege.
Notification recipients are resolved from Appwrite admin_members records plus the protected Super Admin label; customers and ordinary sellers never receive these alerts.
Order creation, payment capture, fulfilment transitions, dispatch, delivery, returns, disputes and reconciliation exceptions publish role-scoped records after their business transaction succeeds.
The bell polls the authenticated internal feed, displays unread priority badges, supports individual and bulk read actions, and stores each administrator's sound preference.
Browser sound is an optional attention aid; the durable Appwrite record and unread badge remain authoritative.
Daily Reconciliation reports total orders and value, paid and pending orders, captured, failed and pending payments, fulfilment, awaiting dispatch, transit, deliveries, complaints, returns and refunds for the selected Africa/Lagos date.
Control rules flag captured payments attached to pending orders, progressed orders without captured payments, paid orders without vendor fulfilment records, dispatched orders without shipments and delivery-state mismatches.
Each run upserts one date-specific snapshot and deduplicates its exception records. Exceptions retain severity, entity, assigned role, status, resolution, resolver and timestamps.
Super Admin, Finance Officers and Order Fulfilment Managers can run reports, resolve exceptions and download a CSV exception report.
For daily automation, set a server-only RECONCILIATION_CRON_SECRET of at least 24 characters and configure Coolify to POST /api/cron/reconciliation with Authorization: Bearer <secret>. Do not expose this secret to the browser.

AI live chat and WhatsApp support

PAC-SM exposes two distinct customer-support channels from one global launcher without mixing their conversations.

Help & chat appears throughout the marketplace and first asks the visitor to choose AI live chat or WhatsApp support.
AI live chat stays inside PAC-SM, uses the server-only OpenRouter chat-completions API and sends only the bounded conversation required for the answer.
The assistant provides marketplace guidance but cannot complete payments, refunds, KYC decisions, account changes or administrative actions.
Customers must never send passwords, OTPs, full card details, API keys, bank credentials or identity-document numbers to the AI assistant.
WhatsApp opens separately through an official wa.me link; it does not share the AI conversation transcript.
The initial official WhatsApp channel is +2349066794666.
Super Admin uses Customer Support at /admin/support to add department numbers, opening messages and display order, and to enable or disable configured channels.
WhatsApp numbers are normalized to international digits and stored in the Appwrite support_channels collection.
Provision support_channels before managing database-backed contacts; the primary number remains available as a safe fallback.
OPENROUTER_API_KEY remains server-only. OPENROUTER_MODEL selects the default model and OPENROUTER_SUPPORT_MODEL can override it for support. The endpoint applies same-origin validation, input limits, provider timeouts and per-instance abuse throttling.

Deployment and operations

PAC-SM is designed for Coolify and a self-hosted Appwrite installation.

The canonical production origin is https://africancontinentalmarketplace.store; configure www and any former domain to redirect to this hostname before authentication begins.
Public catalogue enrichment uses batched Appwrite queries with bounded retry to prevent transient connection failures during regional refreshes.
Set APP_BASE_URL to https://africancontinentalmarketplace.store; application redirects, OAuth return URLs and payment callback origins use it instead of the container's internal 0.0.0.0 address.
PAC-SM deliberately uses a host-only secure session cookie. Leave SESSION_COOKIE_DOMAIN unset in Coolify so a stale www/apex value cannot cause a successful login to be discarded by the browser.
Set Appwrite endpoint, project, database and bucket identifiers as Coolify variables.
Use one limited APPWRITE_API_KEY runtime secret for authentication administration, documents and files. Google OAuth itself uses the public Account API and never exposes this key.
For Appwrite 1.8.1 the runtime scopes are sessions.write, users.read, users.write, databases.read, databases.write, documents.read, documents.write, files.read and files.write.
Keep the full-scope provisioning key outside the application runtime and use it only for schema and runtime-key provisioning.
On Coolify, supply APPWRITE_API_KEY as a locked runtime secret instead of a local key-file path.
In Appwrite Console, register africancontinentalmarketplace.store as a Web platform, enable Google under Auth → Settings, and copy Appwrite's displayed OAuth redirect URL into the Google Cloud OAuth client. Store the Google client ID and secret only in Appwrite.
For local OAuth testing, also register localhost as an Appwrite Web platform and add only the callback values shown by Appwrite to the Google development client.
Configure self-hosted Appwrite SMTP variables for host, port, secure mode, username, password and system sender address; recreate the Appwrite services and verify the mail worker before testing verification or password recovery.
Use a sender on the verified mail.africancontinentalmarketplace.store subdomain for Resend API and Appwrite SMTP delivery.
Set PAYSTACK_SECRET_KEY only on the Coolify server to activate Paystack; configure its callback/webhook against the canonical HTTPS domain before production acceptance tests.
Complete PAPSS onboarding and implement the issued connector specification before enabling PAPSS capture.
Use HTTPS in production and preserve trusted proxy country headers.
Run typecheck, lint, domain tests, production build and Appwrite provisioning before release.

Commission and vendor revenue governance

Versioned financial policies allocate marketplace merchandise revenue without rewriting historical orders.

Super Admin opens Finance → Commission & Revenue Rules to create draft, active or scheduled policies for the marketplace, transaction channel, category, vendor or product.
PAC-SM percentage is stored as integer basis points and the vendor percentage is calculated automatically so merchandise allocation always totals 100 percent.
The resolver applies PAC-SM-owned inventory, product, vendor, category, channel and marketplace rules in that priority order. An impact calculator previews the result before activation.
Every new order item snapshots its rule ID, version, base, percentage, PAC-SM amount, vendor amount, fee bearer, currency and calculation time. Negotiated wholesale uses the final accepted line price.
Delivery journals, seller statements and refunds use the immutable order allocation rather than recalculating against a later policy.
Replacement and retirement are prospective, require an administrative reason and create audit records. Protected baseline rules prevent a transaction from having no applicable policy.
Payment-processor charges, delivery and taxes remain separate from the 100 percent merchandise allocation. The fee-bearer policy records whether PAC-SM, the vendor or both proportionately bear processing costs.

Product-media upload integrity

Seller image batches are validated completely before PAC-SM begins publishing them.

Approved sellers can select JPEG, PNG or WebP images up to 8 MB each, with no more than eight images attached to one product.
PAC-SM checks the batch count, every file size, every declared media type and every image signature before the first Appwrite storage write begins.
If any selected file is empty, oversized, unsupported or has mismatched content, the entire selected batch is rejected and none of its earlier files are published.
A successful first image becomes the product's primary image; sellers can select another approved image as primary later.
Original media stays in private Appwrite storage and is served to eligible viewers through the controlled media route.

Interactive product imagery

Retail and wholesale buyers can inspect every approved seller image without leaving the transaction page.

Product detail pages receive only approved product_media records ordered with the seller-selected primary image first.
The shared client gallery displays the selected image prominently and exposes every additional image as a numbered, accessible thumbnail.
Selecting a thumbnail immediately replaces the prominent image; selecting the prominent image opens a full-screen, contain-fitted inspection view.
Long thumbnail sets scroll horizontally through touch, trackpad, native scrollbar or visible previous/next controls, with scroll snapping on desktop and mobile.
Retail and wholesale use the same interaction and private controlled media route, while retaining their respective visual treatments.
The original files remain in Appwrite private storage. The gallery does not make rejected or pending media public.

PAC-SM website link preview and official logo

The main PAC-SM website address publishes complete social metadata and a branded image for messaging and social-media previews.

The root layout provides Open Graph and Twitter summary-card metadata with an absolute production URL derived from APP_BASE_URL.
The social image endpoint renders a crawler-friendly 1200 × 630 PNG containing the authentic PAC-SM logo, marketplace positioning and official domain.
The same official logo is declared as the browser and Apple touch icon.
WhatsApp, Facebook, LinkedIn, X, Telegram, Slack and other compatible services can retrieve the preview without authentication.
Individual product pages retain their product-specific title, description and approved product image so merchandise links remain commercially useful.
Social platforms cache previews. After deployment, an older preview may require their sharing debugger or a newly shared URL before the new image appears.

Finding pre-order and white-label products

Manufacturer programmes are presented as primary marketplace channels rather than hidden utility links.

The desktop homepage header contains highlighted Pre-orders and White label controls in the main marketplace navigation.
A large Manufacturer Opportunities section on the homepage explains both buying models and links directly to their dedicated catalogues.
On narrow screens the primary navigation remains horizontally scrollable and the two programme controls remain visible as distinct coloured pills.
The Pre-order Marketplace is available at /pre-orders and the White-label Marketplace at /white-label.
Verified manufacturers manage eligible offer settings from Seller Centre → Pre-order & White label.

Product country-of-origin selection

Sellers choose a recognizable country while PAC-SM retains a consistent machine-readable origin code.

Open Seller Centre → Products and locate Country of origin inside Product identity.
The dropdown displays supported countries by flag and full country name and defaults to Nigeria until the seller deliberately selects another origin.
PAC-SM submits and stores the corresponding uppercase ISO 3166-1 alpha-2 code, such as NG, GH or ZA.
The server independently validates the submitted code so altered or unsupported values cannot be published.
Country of origin means the place of manufacture or production, not the seller's address, current warehouse or shipping location.
CSV bulk uploads continue to use the documented two-letter country_of_origin value for repeatable machine imports.

Inventory integrity and stock reconciliation

PAC-SM protects available stock through transactional movements, expiring checkout holds, inspected returns and approval-based physical counts.

Available quantity is always on-hand minus reserved minus damaged units; incoming units remain separate until receipt.
Standard retail and wholesale checkout reserve physical stock atomically for fifteen minutes across eligible warehouses.
Pre-orders reserve governed production capacity and white-label orders retain accepted production terms without inventing warehouse stock; payment requires physical reservations only for standard items.
Configure Coolify to POST /api/cron/inventory-integrity every five minutes with Authorization: Bearer <RECONCILIATION_CRON_SECRET>. The worker releases expired holds, returns unused pre-order capacity, cancels stale unpaid parent and vendor orders and records an order event.
Payment atomically reduces on-hand and reserved stock, captures each reservation and creates sale movements; low-stock and out-of-stock thresholds publish role-scoped administrator alerts.
Seller receipts and merchant API adjustments update the balance and movement ledger in one Appwrite transaction. API adjustments cannot reduce on-hand below reserved plus damaged stock.
Seller Centre → Inventory retrieves up to 5,000 warehouses, offers and positions, displays recognizable SKU and warehouse names, shows on-hand, reserved, damaged and available quantities, and lists recent movements.
A seller can define a non-negative reorder point for each warehouse and offer position.
Physical counts require a non-negative count and written reason. Super Admin reviews pending counts at /admin/inventory; approval is refused if stock changed after counting or if the result is below committed stock.
Approved variances update the balance and create a stocktake movement and audit log in one transaction; rejection retains the submitted evidence without changing stock.
Refund approval does not silently restock goods. Super Admin inspects the return, chooses a vendor-owned warehouse and records restock or damaged disposition; damaged units increase on-hand and damaged equally so availability remains unchanged.
Daily reconciliation reads inventory positions, stale holds, low-stock thresholds and pending physical counts, and raises exceptions for expired reservations or negative availability.
Appwrite provisions inventory_balances.reorderPoint, the inventory_counts collection, return-disposition attributes and their supporting indexes; no local database is introduced.

Global Supplier Gateway — Phase 1

A provider-neutral control plane prepares PAC-SM for CJdropshipping and later global supply sources without surrendering catalogue, customer or accounting control.

Every global supplier record is bound to the approved Diplomats Stores vendor and storefront. External suppliers are fulfilment sources, never independent PAC-SM sellers.
Super Admin opens Admin → Global Commerce to register CJ, save its API key, test the API 2.0 connection and review feature-gate state.
Supplier API keys and returned access and refresh tokens are encrypted with AES-256-GCM before private Appwrite storage. Secrets are never rendered back to the browser or written to logs.
The separate SUPPLIER_CREDENTIAL_ENCRYPTION_KEY must contain 32 random bytes encoded as Base64 or 64 hexadecimal characters and must be configured as a locked Coolify server secret. Local development may read the same value from a protected external SUPPLIER_CREDENTIAL_ENCRYPTION_KEY_FILE; changing it makes previously encrypted supplier credentials unreadable.
Connection testing authenticates or refreshes CJ tokens according to their returned expiry dates, stores a masked credential summary and records connection and audit history.
Global Commerce Manager and the specialist integration, catalogue, pricing, order, logistics and finance roles can receive scoped operational visibility. Supplier credential creation and authentication remain Super Admin-only.
Feature flags enable the foundation and CJ connector while keeping global checkout, wholesale, RFQ and automatic supplier ordering disabled or in limited-pilot/manual-approval mode.
Phase 1 does not copy supplier products into the public catalogue, expose supplier credentials, submit supplier orders or accept live global checkout. Those capabilities require later acceptance gates.
The Appwrite source of truth consists of global_suppliers, supplier_credentials, supplier_connections and global_feature_flags; no local backend is introduced.

Global Product Discovery — Phase 2

Authorized staff can inspect live CJ catalogue information inside PAC-SM before any product is selected for import.

Open Admin → Global Commerce → Global Product Discovery after the CJ connection is verified.
Search by product name or SKU, browse current third-level CJ categories, filter for inventory country and paginate bounded result sets.
Product cards show the supplier identity, image, SKU, indicative USD supplier cost and available catalogue metadata; every card remains marked Not imported.
The product inspection page shows the CJ product ID, gallery, category, weight, variants, variant costs, reported inventory and warehouse country/name.
PAC-SM refreshes an expired CJ access token server-side when the refresh token remains valid. Neither token is exposed to the page or browser.
Discovery calls use bounded page sizes and timeouts because CJ applies API points and request limits. Variant stock inspection is capped per product to prevent uncontrolled fan-out.
Supplier prices are costs, not customer prices. No discovered item becomes searchable by customers, orderable or financially active until controlled import and pricing phases are completed.
All later imported CJ and global products inherit the non-negotiable Diplomats Stores ownership and accounting boundary.

Global Product Import — Phase 3

Selected CJ products enter the existing PAC-SM catalogue through a controlled, auditable and non-public draft workflow.

Super Admin and Global Catalogue Manager can import; other global-commerce roles retain read-only discovery access.
The import editor requires a PAC-SM title, existing category, country of origin, active pricing-rule reference and at least one current supplier variant.
PAC-SM re-fetches supplier data on submission and refuses stale variants or duplicate supplier-product mappings.
Products and variants receive independent PAC-SM IDs while supplier_products and supplier_variants retain CJ IDs, costs and sync provenance.
The active Diplomats Stores vendor is resolved server-side and is always the commercial and accounting owner.
Selected images are validated and copied into PAC-SM Appwrite storage; imported content does not rely blindly on supplier hotlinks.
Imported products are pending_review and appear in Imported Products and the existing Catalogue review queue.
Phase 3 creates no approved offer, public price, inventory promise or checkout access. Those remain blocked until Phase 4 landed-cost pricing.
Price and stock synchronization are prepared as enabled mappings; content synchronization defaults off to protect PAC-SM merchandising edits.

Mobile marketplace header navigation

Shop and Trade & source use dedicated touch-first navigation sheets instead of clipped desktop dropdowns.

The horizontally scrollable primary strip retains direct links to All Categories, PAC-SM Products, Global Stores and seller registration.
Dedicated Shop and Trade & source buttons appear immediately below that strip on screens up to 760 pixels wide.
Each button opens one modal navigation sheet above a dimmed backdrop, ensuring submenu content cannot be clipped by the horizontal header.
Destinations retain their grouping, icon, title and explanatory text, with large touch targets for reliable phone use.
Only one submenu is open at a time. Selecting a destination, tapping the backdrop or pressing the visible close button dismisses it.
The sheet supports internal vertical scrolling and a single-column arrangement on smaller phones.
Desktop hover, focus and native expandable-menu behaviour remains unchanged.

Global Stores navigation and catalogue placement

Global supply becomes a recognizable customer channel while retaining PAC-SM approval, pricing and category controls.

Global Stores is available from the All markets search selector, the prominent homepage navigation, the grouped Shop menu and the public /global-stores page.
The reorganized desktop navigation keeps All Categories, PAC-SM Products, Global Stores and Sell on PAC-SM prominent while grouping buying channels under Shop and operational opportunities under Trade & source.
Native expandable menus remain keyboard accessible and collapse the long navigation into understandable tasks.
Every imported supplier product carries the pacsm_global channel and an existing PAC-SM category ID.
After Phase 4 creates an approved offer and catalogue review approves the product, it automatically appears in Global Stores, global search results and its assigned marketplace category.
Pending, rejected, suspended, unpriced or offer-less imports remain absent from every public listing and cannot enter cart or checkout.
Global Stores exposes customer prices only; supplier costs, credentials, mappings and internal pricing rules stay in protected administration.
All global products remain commercially and financially owned by Diplomats Stores and use the standard PAC-SM product, cart, payment and order pages.

Global landed-cost pricing — Phase 4

PAC-SM calculates commercially viable, review-ready customer prices without exposing supplier economics.

Global Pricing Manager, Global Commerce Manager and Super Admin open Admin → Global Commerce → Global Pricing.
Editable destination rules support percentage, fixed, percentage-plus-fixed and minimum-margin methods.
Each rule records transaction currency, markup, insurance, duty, tax, payment, FX-risk, platform, local-delivery, other-cost and minimum-margin controls.
The server FX abstraction obtains a current source-to-transaction currency rate; a missing current rate blocks calculation instead of inventing a conversion.
An administrator records the freight method and estimate. The quote expires after six hours and is explicitly marked estimated until live supplier shipping validation is implemented.
The landed-cost engine applies integer minor-unit arithmetic and stores supplier cost, converted cost, freight, insurance, duty, tax, payment estimate, FX buffer, platform cost, local delivery, other cost, landed cost, protected margin and final price.
Every mapped variant receives its own immutable breakdown and Diplomats Stores offer. Supplier costs and margins never appear on public pages.
Calculated offers use pending_review status. Existing Catalogue Management must approve the product and its offers before they become searchable; Phase 5 inventory and Phase 6 global-checkout gates remain outstanding.
Recalculation updates the review offer prospectively while retaining earlier breakdown snapshots for audit.
All Phase 4 rules, quotes, breakdowns, offers, product state and audit history are stored in Appwrite; no local backend is introduced.

Global supplier synchronization — Phase 5

PAC-SM safely reconciles imported CJ records without treating external stock or price as unquestioned customer truth.

Authorized staff open Admin → Global Commerce → Global Sync Centre to inspect mappings, product subscriptions, supplier inventory, webhook events and run history.
Only imported mappings with autoSync enabled are included; scheduled work is bounded to 25 priority mappings per run to protect CJ API points and PAC-SM response times.
The CJ connector uses the official product-specific /webhook/product/subscribe endpoint in batches of no more than 100 and never enables subscribe-all.
CJ callbacks POST to /api/integrations/cj/webhook over HTTPS with a separate CJ_WEBHOOK_SECRET token. Payload size and required message identity are validated before storage.
Webhook messageId is unique per supplier, making duplicate delivery retry-safe. The endpoint records a queued event and returns 200 without performing slow supplier reconciliation inline.
The worker processes PRODUCT, VARIANT and STOCK-related product references through the canonical supplier connector, with exponential retry state and a five-attempt terminal failure boundary.
Supplier inventory is normalized by supplier, mapped product, mapped variant, warehouse and country. Sellable quantity equals reported available quantity minus the configurable stock buffer.
Supplier inventory remains separate from PAC-SM physical inventory and is not a checkout guarantee. Phase 6 revalidates destination, variant, freight and stock before payment.
A supplier price movement beyond the mapping tolerance sets price_review_required and alerts Global Pricing staff; the current customer price is not silently changed.
Set a locked CJ_WEBHOOK_SECRET of at least 24 characters and configure CJ's production HTTPS callback with that token. Configure Coolify to POST /api/cron/global-supplier-sync every 15 minutes with the existing RECONCILIATION_CRON_SECRET bearer value.
Sync runs record trigger, requested, succeeded, failed, timing and bounded error summaries in Appwrite. Mapping errors remain visible for manual recovery.

Global checkout assurance — Phase 6

Eligible global-direct products pass a supplier-aware safety gate before PAC-SM creates an order or starts payment.

Global products use supplier_inventory rather than PAC-SM warehouse balances when checking cart quantity.
Checkout refreshes the canonical supplier product and validates the exact mapped variant immediately before order creation.
Buffered sellable supplier stock must cover the complete cart quantity; supplier stock is never treated as guaranteed until this check passes.
The delivery-address country must match the current destination-specific freight quote, and the quote must still be within its validity window.
The approved customer price, currency, supplier cost and current landed-cost snapshot must agree. A supplier price requiring review blocks payment instead of silently reducing margin or surprising the buyer.
A failed global check leaves the cart intact and returns a specific, customer-readable explanation on the checkout page.
Each successful check creates time-bounded Appwrite evidence in global_checkout_validations.
Order creation groups global items by Diplomats Stores vendor and supplier in global_fulfilment_groups with awaiting_payment status.
Global Order Manager, Global Commerce Manager and Super Admin can inspect the Checkout Assurance page under Admin → Global Commerce.
The globalCheckoutEnabled feature flag runs in limited-pilot mode.

Global supplier order automation — Phase 7

A paid PAC-SM global order can create its mapped CJ fulfilment order once, under staff approval and without silently paying the supplier.

Payment capture treats global_direct items as supplier-validated stock and never invents a PAC-SM warehouse reservation.
After successful payment, PAC-SM creates one supplier_orders record per global_fulfilment_group. The fulfilment-group identity is unique, making repeated payment callbacks and recovery actions idempotent.
Every supplier line maps the PAC-SM order item, product and variant to the preserved supplier product and external CJ variant identifiers.
Global Order Manager, Global Commerce Manager and Super Admin use Admin → Global Commerce → Global Supplier Orders.
The recovery action finds paid groups that were not queued after an interruption; it does not call CJ or make payment.
Before submission, staff verify the exact CJ logistics method. PAC-SM checks that the parent order remains paid and that mapped items are complete.
CJ createOrderV2 is called with the PAC-SM supplier-order number, protected delivery details, mapped variant lines and payType=3. This creates the CJ order only and cannot debit the CJ balance.
The PAC-SM supplier order stores returned CJ order, shipment, amount and status identifiers without exposing supplier credentials.
Failures move the record to exception, retain the sanitized provider message, create an audit event and alert the responsible global-order roles.
Supplier payment confirmation is a separate administrative step requiring an external reference. AutomaticSupplierOrders remains manual_approval, and no CJ balance-payment API is called in Phase 7.
supplier_orders, supplier_order_items and supplier_order_events are stored in Appwrite; no local backend is introduced.

Live international freight quotation

PAC-SM uses the connected supplier's available delivery routes as the pricing and checkout evidence for global-direct products.

Global Pricing staff open an imported product, select a pricing rule, representative mapped variant and quantity, then request live CJ shipping options.
The connector sends the exact external variant, quantity, origin and destination to CJ's freight calculation endpoint.
Available methods display delivery timing when supplied plus freight, taxes, clearance and the total in the pricing-rule currency.
No valid supplier route means the item cannot be priced for that destination; PAC-SM does not invent a shipping amount.
A selected live method becomes the landed-cost basis used to create review offers. Product and offer approval remain separate catalogue controls.
Immediately before order creation, checkout refreshes supplier stock and requests a new freight quote for the exact cart variant, quantity and delivery country.
If the approved method disappears or the live cost exceeds the approved shipping allowance, checkout stops safely and requests repricing before payment.
Successful checkout validations expire after ten minutes and preserve the actual freight method and amount used by the safety check.
Supplier credentials and raw supplier economics remain server-only.

Global pricing to catalogue approval handoff

A completed global pricing calculation becomes one consolidated Super Admin publication review instead of requiring repeated data entry.

After Calculate and create review offers succeeds, PAC-SM redirects directly to Catalogue Management with the relevant product selected.
The focused review retrieves authoritative data from products, supplier_products, supplier_variants, seller_offers, global_price_breakdowns and global_freight_quotes; values are not copied from browser fields or entered again.
The review displays supplier identity and external reference, Diplomats Stores ownership, global-direct fulfilment, mapped-variant count, saved-offer count, customer prices, landed costs, protected margins, freight method, amount, destination and confidence.
Approve and publish is enabled when the product has mapped variants and every mapped variant has current landed-price and freight evidence.
For legacy calculations where Appwrite retained every variant breakdown but only one seller offer, approval safely reconstructs the missing offers from the reviewed breakdowns before publication.
The one-click approval uses a server-side Appwrite transaction to approve the canonical product, all product variants and all seller offers together and records the Super Admin decision in the audit log.
Incomplete pricing or freight evidence keeps publication disabled rather than publishing a partial global listing.
After approval, the page stays focused on the same product and the public catalogue cache is invalidated.

Automated global publication queue

Super Admin can move commercially ready global products into the public catalogue in controlled batches instead of opening every listing.

Catalogue Management automatically counts unpublished global products that pass all publication gates.
A ready product must belong to the controlled global-supplier mapping, have one or more mapped variants, a positive current landed-price breakdown and linked freight evidence for every variant, plus at least one approved product image.
The Publish next ready products action processes up to 100 products per batch to avoid long-running Appwrite requests.
The server recalculates eligibility from Appwrite at submission time; hidden browser fields cannot bypass the quality gates.
Every eligible product is published through the existing audited approval transaction, including repair of missing legacy seller offers.
Products that no longer qualify are skipped and remain private. Failures are counted separately so one problematic listing does not block the rest of the batch.
After each batch the dashboard reports published, skipped and failed totals. Repeating the action processes the next ready group.
This automation deliberately retains a Super Admin publication action; fully unattended publication is deferred until supplier-data quality and exception rates have been measured in production.

Privacy and cookie choices

PAC-SM requires an explicit first-visit choice before using optional preference, analytics or advertising technologies.

The consent centre blocks page interaction on first visit until the visitor accepts all, rejects non-essential cookies or saves customised choices.
Accept, reject and customised choices use a server-backed form fallback, allowing consent to be recorded even when production JavaScript is delayed or unavailable.
Strictly necessary technologies remain active for security, authentication, checkout, saved consent, regional settings and core marketplace operation.
Preferences, analytics and advertising are independent optional categories and default to off unless the visitor accepts them.
The consent decision is stored in a first-party SameSite=Lax cookie for up to twelve months and marked Secure on HTTPS.
The permanent Privacy settings control reopens the centre so choices can be changed at any time.
A versioned consent format allows PAC-SM to request a fresh decision after a material policy change.
Non-essential integrations must consult the saved category before loading; the consent interface does not falsely claim that an unimplemented tracker is active.
The public Cookies and Similar Technologies Policy is available at /cookies-policy.

Super Admin operational navigation

High-priority marketplace and global-supplier controls remain visible without searching through the full operations directory.

Open Super Admin Centre from My Account after signing in with the protected Super Admin account.
Global Commerce, Global Pricing and Catalogue Management appear in both the desktop sidebar and the highlighted action area at the top of the dashboard.
Global Commerce opens /admin/global-commerce for supplier discovery, controlled imports, synchronization, checkout assurance and supplier orders.
Global Pricing opens /admin/global-commerce/pricing for freight assumptions and landed-price calculation.
Catalogue Management opens /admin/catalogue for product and seller-offer review, approval, moderation and takedown.
On narrow screens the highlighted cards remain available even when the compact sidebar navigation is hidden.

Affiliate marketing and commission control

Approved members share attributable product links and earn governed, platform-funded rewards on qualifying sales.

A signed-in member opens My Account → Affiliate programme, declares promotion channels and accepts the anti-spam, disclosure and self-referral rules.
Super Admin reviews, approves, rejects or suspends applications in Admin → Affiliate Programme; approved accounts receive a unique PAC-AF code.
Approved affiliates can create campaign links and product share controls automatically replace the ordinary URL with a protected /r/[code] link.
The redirect records a privacy-minimized click and sets a secure, HttpOnly, SameSite=Lax first-party attribution cookie for 30 days.
Checkout validates the affiliate again, rejects self-referral and creates one immutable commission allocation per order item in the same Appwrite transaction as the order.
The reward is a separate platform-funded journal and does not silently reduce seller proceeds. The default rule is 3 percent and is versioned by Super Admin.
An allocation progresses from pending payment to pending delivery, then holding after delivery. It becomes available only after the configured return window, which defaults to 14 days.
The affiliate dashboard separates available, holding and lifetime earnings, shows campaign links and commission activity, and accepts withdrawals only against unreserved available funds.
Super Admin controls withdrawal approval, rejection and paid confirmation with written evidence. Minimum withdrawal is NGN 5,000.
Fraud controls include server-side approval checks, self-referral rejection, privacy-safe visitor hashing, immutable order-item attribution and review/suspension history.
All affiliate profiles, links, clicks, rules, allocations, withdrawals and review events are stored in Appwrite; no local backend is introduced.

Global pre-order discovery visibility, shipping and checkout

Connected-supplier products receive governed customer prices and selectable live delivery routes without exposing supplier cost.

Global Visibility Centre creates resumable supplier-category publication jobs mapped to an active PAC-SM category.
Each run processes 10 to 100 supplier records, records processed, published, skipped and failed totals, and resumes from the next page.
A Coolify scheduled task may POST /api/cron/global-discovery with the reconciliation bearer secret. It continues publication first and automatically prices the next 100 unpriced records whenever no publication batch is waiting.
Every discovery listing is commercially owned by Diplomats Stores and stores its supplier identity, public image, category, availability signal and synchronization time in Appwrite.
Administrators select an active Global Pricing rule, default destination, freight assumption and one-to-168-hour validity window in Global Visibility.
PAC-SM converts supplier cost with current FX and applies insurance, duty, tax, payment cost, FX buffer, fixed costs, minimum-margin protection and configured markup. Supplier cost remains private.
New discovery batches save a price snapshot automatically. Price next 100 products now progressively backfills previously published records without republishing them.
Retail and Wholesale cards display From prices and use Pre-order now when a valid customer price exists; unpriced records display Price updating.
The saved marketplace currency preference converts prices across homepage global features, discovery grids, product details, live shipping components and displayed payable totals. Checkout retains the independently revalidated transaction currency and amount.
On the product page a signed-in customer selects an exact CJ variant, quantity and saved delivery address before requesting live delivery routes.
Each route displays estimated days, shipping, supplier-reported taxes and clearance, and a complete landed payable total. No amount or method sent by the browser is trusted; the server retrieves it from CJ again when the customer continues.
Continuing materializes only the selected supplier variant in the governed PAC-SM catalogue under Diplomats Stores, synchronizes supplier stock, stores a live freight quote and landed-cost breakdown, and creates the approved checkout offer.
The selected product enters the ordinary PAC-SM cart as a pre-order. Checkout revalidates its mapped variant, supplier cost, available stock, destination, selected shipping method and current freight before creating a pending-payment order.
Payment activates only after successful revalidation and uses the existing demo or Paystack server flow. Supplier fulfilment remains protected behind confirmed payment and administrative supplier-order controls.
The emergency visibility control can pause discovery listings without affecting fully approved checkout-ready products.
The system uses Appwrite for discovery, canonical catalogue mappings, live freight evidence, landed-cost breakdowns, carts, orders, payments and audit records.

Starting and recovering discovery publication jobs

A created supplier-category job begins publishing immediately and provides recovery for empty CJ category IDs.

Create job and publish first batch performs both operations in one authenticated request.
A successful run reports how many products were published and updates the next supplier page, total discovered products and cumulative counters.
Jobs created before automatic execution can be recovered with Run next queued batch now.
Every queued or running row retains its own Publish next batch now control.
If CJ returns zero products for a selected leaf category ID, PAC-SM retries page one using the leaf category name. An older zero-result completed job exposes Retry with category-name fallback.
The CJ connector automatically retries a short burst of HTTP 429 rate-limit responses with bounded backoff. If CJ remains unavailable, the job changes to completed with errors and displays the provider-safe reason instead of remaining silently queued.
If the category ID and name search are both empty, the job remains visibly diagnosed instead of implying that products were published.
Each request stays bounded to protect CJ rate limits and Coolify request duration.

Export & Import Hub — Phase 1

The Hub consolidates PAC-SM's existing cross-border services around one canonical transaction and immutable event timeline while preserving the shopping homepage.

The current shopping homepage, product carousel, category discovery, brands and marketplace sections remain unchanged. Export & Import is introduced through the existing Trade & Source navigation.
The public /trade-hub landing page provides Export and Import gateways plus direct links to marketplace products, procurement, ExportReady, trade documents, logistics and the personalized dashboard.
A signed-in approved seller starts an export request from an existing seller product or a general export requirement; ordinary signed-in users can start an import sourcing requirement.
Every accepted request creates one Appwrite trade_transactions record and a collision-resistant PAC-EXP or PAC-IMP Trade ID containing direction, origin, destination and year.
Creation and future stage changes use the immutable trade_transaction_events timeline. The initial transaction record and event are committed together in an Appwrite transaction.
Controlled origin and destination selections use supported ISO country codes, prohibit same-country cross-border requests and retain quantity, unit, currency and estimated value in integer minor units.
The user dashboard summarizes active, in-transit and delivered exports and imports plus document and customs-related workload, and lists the user's recent Trade IDs.
The protected transaction detail page displays compliance, document, payment and logistics status independently, alongside a controlled end-to-end workflow and event history.
Super Admin uses Admin → Export & Import Hub to monitor all canonical Trade IDs and corridors. Phase 1 does not silently grant operational update authority or bypass specialist controls.
Existing trade_passports, export_product_profiles, product_hs_classifications, product_destination_tariffs, regulatory sources and rules, compliance assessments, trade_documents, cross_border_shipments, RFQs, quotations, purchase orders, payment and logistics records remain authoritative in their domains.
Phase 1 adds only trade_transactions and trade_transaction_events; no production collection or working route is deleted or migrated destructively.
RFQ conversion, quotation comparison, transaction-linked document requirements, freight bidding and cross-module stage automation remain explicit Phase 2 work.
PAC-SM supplies workflow and source-backed guidance, not government customs rulings, certificates, licences, financing approvals or clearance decisions.

Export & Import Hub — Phase 2 collaboration

Trade opportunities, comparable quotations, transaction documents and freight bidding attach collaboration to the canonical Trade ID.

Global Trade Opportunities supports Buyer Request, Supplier Offer, Export Opportunity and Import Opportunity with product, specifications, quantity, corridor, target price, Incoterm, certifications, payment terms, delivery date and response deadline.
An opportunity may be linked only to a Trade ID owned by the publisher. A member cannot quote their own opportunity, and each responder may hold one comparable quotation per opportunity.
Existing PAC-SM accounts, vendors, products and approved carrier identities are reused; the collaboration layer does not duplicate them.
A Trade ID owner publishes one freight RFQ containing corridor, locations, mode, weight, package count, cargo requirements and dates. Only an active approved carrier may quote.
The Trade ID detail links to its protected document vault, opportunity exchange, freight exchange and ExportReady assessment.
The vault accepts PDF, JPG and PNG up to 20 MB in existing private Appwrite storage and tracks type, reference, status, optional expiry and review fields.
Supported records include invoices, packing lists, purchase orders, contracts, certificate of origin, insurance, inspection, bills and waybills, NXP, Form M, PAAR, permits, licences and quality certificates.
Opportunity, quotation, freight and document actions append immutable events when linked to a Trade ID.
Phase 2 adds trade_opportunities, trade_opportunity_quotes, trade_freight_rfqs, trade_freight_quotes and trade_transaction_documents without deleting existing procurement, logistics or document collections.
These services facilitate trade; they do not issue government clearance, accept a commercial offer automatically or make a financing decision.

Export & Import Hub — Phase 3 trade intelligence

Country gateways, compliance navigation and transparent calculators help members prepare a corridor without presenting PAC-SM guidance as a government ruling.

Country Trade Gateways cover every country supported by PAC-SM and distinguish a directory gateway from reviewed guidance.
Reviewed profiles record version, effective date, review date, official authority and HTTPS source alongside ports, borders and payment preparation notes.
The restricted-goods register records country, direction, HS prefix, control type, conditions, authority, source and validity dates.
An empty restrictions list never means unrestricted; users must verify with customs and the relevant product regulator.
The Compliance Centre connects existing HS, tariff, origin, ExportReady, protocol-pack and evidence-vault tools instead of duplicating them.
The landed-cost calculator separately models goods, freight, insurance, duties, taxes, levies, compliance, brokerage, ports, warehousing and inland transport.
The export-pricing calculator builds a target price from production, packaging, compliance, logistics, finance, platform costs and explicit margin.
Calculator results are estimates in the selected currency, not quotations, live exchange rates, customs assessments or payment instructions.
Trade Compliance staff and Super Admin publish source-backed intelligence from the Trade Hub administration area.
Phase 3 adds trade_country_profiles and trade_restrictions in Appwrite; no local backend is introduced and the shopping homepage remains unchanged.

Export & Import Hub — Phase 4 ecosystem

PAC-SM coordinates institutional partners, trade-finance referrals, management analytics and automated compliance alerts around canonical Trade IDs.

Signed-in traders request finance only against a Trade ID they own, selecting the facility, amount, currency, tenor, purpose and an optional approved institution.
Supported categories include purchase-order, pre-shipment, working-capital and invoice finance, letters of credit, collections, guarantees, credit insurance and SME trade loans.
The applicant explicitly consents to controlled referral. PAC-SM does not share a request merely because it was submitted.
Trade Compliance staff manage a governed directory of banks, development-finance institutions, insurers, customs brokers, carriers, warehouses, inspectors, certification bodies and official agencies.
Institution entries distinguish directory, manual referral, sandbox API and contracted live API modes. Listing an institution does not claim an active API integration.
Finance decisions follow a controlled, audited status workflow; PAC-SM cannot label a request approved until the partner has made that decision.
PAC-SM remains a marketplace and facilitation layer, not the lender, insurer, customs broker, certifier or government authority.
The compliance scanner compares active Trade IDs with the published country goods-control register and creates review alerts without automatically approving or blocking cargo.
Management analytics report Trade IDs, completion, opportunities, quotes, freight demand, finance requests and leading corridors.
Declared transaction values remain grouped by currency; the dashboard does not add different currencies into a misleading total.
Phase 4 adds trade_institutions, trade_finance_requests, trade_finance_events and trade_compliance_alerts in Appwrite; no local backend is introduced.