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.
01
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.
02
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.
03
Product-level ExportReady engine
PAC-SM calculates market-specific readiness from governed classification, 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.
- International HS6 is stored separately from origin and destination national tariff extensions; each classification retains HS nomenclature version, confidence, reasoning, attributes used and governance status.
- 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.
- Initial authoritative references include the Nigeria Trade Portal tariff tools, NEPC export-document guidance and GOV.UK DCTS guidance; actual product conclusions require published rules and current source review.
04
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.
05
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 OPENAI_API_KEY Coolify secret; OPENAI_PRODUCT_DRAFT_MODEL selects the structured-output model and the key must never use a NEXT_PUBLIC prefix.
- Requests disable provider storage, transmit only product drafting inputs, validate a strict response 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.
06
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.
07
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.
08
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.
09
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.
10
Official logistics partner
Zenith Carex Express is identified across PAC-SM as the official logistics partner.
- The Zenith Carex Express logo appears in the homepage logistics-partner strip and on /logistics.
- 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.
11
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.
12
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.
13
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.
14
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
15
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.
16
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.
- Search by name, description, brand, category and market type.
- 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.
17
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, settlement, store and KYC/KYB document information before review.
- 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, store and trade 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.
18
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.
19
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.
20
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.
21
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.
22
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.
23
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.
24
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.
25
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.
26
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.
- Admin Team lets the Super Admin select several privileges for one registered email in a single grant. Appwrite labels are merged without duplicates, each role remains an independent active assignment, and the complete grant set is written to the audit log.
- 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.
27
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.