Hocuwa Marketplace — Functional & Technical Handover

This document describes the delivered Hocuwa application from a client, operational, and technical perspective. It is based on the current application routes, database models, business-rule services, administrator controls, and automated tests—not on a generic marketplace feature list.

Hocuwa is available in a separate staging environment for client review. The production domain is intentionally held on a Coming Soon page until business approval, production payment credentials, content, and launch operations are confirmed.

Hocuwa is a responsive web marketplace for livestock and the wider agriculture sector. It brings discovery, seller profiles, structured listings, negotiations, auctions, checkout, delayed seller payouts, communication, verification, and administration into one application.

Public visitors can browse listings, seller information, membership plans, blog posts, help content, and company pages. Registration is required for personalised actions such as favouriting, offering, bidding, purchasing, messaging, publishing a listing, and using the dashboard.

Public account labels

Registration offers Private and Business account labels. These labels change how names and contact details are presented; they are not hard buyer-versus-seller permissions. Every registered account can both buy and sell, subject to its effective membership plan and account status. This allows a farm, company, or private individual to use one account for both sides of a trade.

Account lifecycle and access controls

• Email/password registration with bot protection, terms acceptance, and optional email OTP verification.
• Optional Google sign-in when platform credentials are configured.
• Password recovery, password change, remember-me sessions, and optional authenticator-based MFA.
• Active, suspended, and deleted account states are enforced on protected routes.
• Users can manage notification preferences and request account deletion from settings.
• The marketplace session and administrator session are separate.

Listing creation and management

The five-step wizard covers category, product or animal details, media, price, and final review. A listing may include title, description, quantity and unit, age, weight, sex, condition, health and vaccination information, location, country, price, auction rules, up to ten images, one video, and up to five supporting PDF documents. Fields appear where relevant to the selected category.

Drafts do not consume an active-listing allowance. Publishing requires the mandatory structured data and at least one image. With manual moderation enabled, a submitted listing enters Pending Review; otherwise it becomes Active. The owner can edit it or remove it from active use, with protections when offers or bids may be affected. Removal archives the record so linked commerce history is preserved. Stock quantity decreases by one after each successful checkout, and a listing is marked Sold when no quantity remains.

Search, browse, and comparison

Search covers listing titles, descriptions, locations, item/subcategory details, and seller or farm names. Users can narrow results by category structure, pricing method, price, and country, then sort by newest, price, popularity, or auction end. Up to three listings can be compared side by side using category, type, age, weight, price, health, location, and seller-rating information.

Dashboard

Every account receives a unified dashboard because every account may buy and sell. It includes an overview, listings, messages, favourites, offers, auctions and bids, purchases, transactions, reviews, profile, verification, and settings. Team management appears only when the owner's plan enables it.

Trust, messaging, and notifications

• One reusable conversation is maintained for each buyer/seller pair, with text and image messages.
• Direct messaging is available only when the seller's effective plan includes it.
• Users may block conversations and report inappropriate listings or reviews.
• Verification accepts supported ID and address documents for administrator review.
• Paid purchases permit one buyer-to-seller review per transaction.
• The public trust score considers review activity, average rating, verification, and account age.
• Important events create in-app notifications; email is best effort and preference-aware where applicable.

Membership plans are database-driven and administered without a code deployment. The active default free plan applies when an account has no current paid membership. A paid plan is purchased through a one-time Stripe checkout and remains active for its configured term; it is not an automatically recurring subscription.

The table below records the seeded delivery baseline. Administrators can change plan prices, duration, limits, fees, badges, and activation state, so the live Membership page is the authority for customer-facing values.

Commission is plan-configurable. For each sale, Hocuwa calculates the percentage fee, fixed fee, and marketplace service fee against the seller's effective plan. Deductions reduce the seller's net payout rather than increasing the buyer's item total.

Payment architecture

Buyer payments use Stripe-hosted Checkout. Server-side quoting calculates quantity, gross amount, configured fees, and seller net amount. Signed Stripe webhooks are the authoritative payment signal, with idempotent reconciliation when a customer returns from checkout. Hocuwa uses one administrator-selected platform currency for listings, checkout, transactions, memberships, and reports.

Delayed seller settlement

The delivered workflow is escrow-style delayed payout, not a regulated legal escrow account. Payment is received by the platform and linked to a Stripe transfer group. When collection confirmation is required, payout remains Not Ready until the buyer confirms receipt. It is then scheduled after the configured delay. The background processor transfers the seller net amount only when the seller's Stripe Connect account is ready and no dispute is holding the transaction.

• Sellers complete Stripe Connect onboarding from dashboard settings before receiving payouts.
• Buyers can download a PDF receipt from an eligible transaction.
• A dispute can be opened before payout processing has started.
• Administrator refunds are full refunds; partial-refund tooling is not delivered.
• If a seller transfer has already been paid, the normal admin refund is blocked until handled externally.

The separate administration area centralises marketplace operations. Administrative changes and sensitive support actions are protected and logged where applicable.

Administrative access is role-based in both the interface and server API. Super Admins have full access and are the only accounts that can assign operational roles. Admins retain full operational access without role assignment; Product Managers manage listings and membership products; Content Managers manage blog, podcast, and advertising content; and Staff handle users, listing moderation, and disputes.

Configurable operating rules

The settings interface is organised into Categories, Regions, Moderation, Auction Rules, Commerce, Page Content, and Social Links. It includes listing moderation, email verification and reCAPTCHA switches, auction timing, winner-payment windows, automatic lifecycle control, currency, payout delay, collection confirmation, Connect countries, Stripe webhook setup, company/legal/help content, and social URLs.

• Passwords are one-way hashed; password-reset links and email OTPs are time-limited.
• Registration, login, contact, recovery, and verification actions use validation and targeted rate limits.
• Uploads are restricted by file type, signature, size, and ownership checks.
• Server routes enforce authentication, account state, ownership, team ownership, plan rules, and transaction-party access.
• Stripe webhook signatures are verified and event handling is idempotent.
• MFA supports authenticator applications and one-time backup codes.
• Administrator support impersonation is time-limited, restricted, and audit logged.
• Verification documents are available only to the account and authorised administrators.

The application is built as a standalone Next.js server suitable for the current hosted deployment, with persistent upload storage separated from replaceable application releases. A health endpoint checks application and database availability. Scheduled lifecycle and payout endpoints are designed for protected scheduler invocation.

Routine operating tasks

• Review pending listings, verification documents, disputes, and failed payouts.
• Monitor Stripe webhooks, seller onboarding, refunds, and scheduled payout processing.
• Maintain database/upload backups and periodically verify restoration.
• Review administrator access and audit logs; remove obsolete accounts promptly.
• Keep categories, regions, legal content, plans, fees, rules, and support details current.
• Run regression tests before release and verify key flows after deployment.

The repository contains 57 Playwright end-to-end tests across nine browser-test files, executed against isolated test data. The configured browser matrix includes desktop Chromium and a Pixel 7-sized mobile project. A separate four-scenario Stripe test-mode suite exercises the real payment integration when approved test credentials and network access are available.

Standard verification commands are npm run lint, npm run build, npm run test:e2e, and, in an authorised Stripe test environment, npm run test:payments.

These statements prevent business users and support staff from assuming adjacent capabilities that have not been implemented.