For Stakeholders

Why this matters

Dentolize has historically been a single-sided practice-management tool: one clinic, its own patients, its own books. This PR is the first piece of a genuine two-sided platform — clinics/pharmacies as buyers, dental/medical suppliers as sellers, transacting through Dentolize. That's a meaningfully different kind of product surface (new revenue motion for suppliers, new stickiness for clinics) and a new engineering pattern (cross-tenant records, subscription tiers, a second front-end product) that other teams will build on.

This branch is explicitly one-third of a larger plan — three feature branches (marketplace-suppliers, marketplace-labs, marketplace-core) building on a shared foundation (feat/marketplace), designed from the start to merge with minimal conflict. This is the suppliers slice: physical-goods procurement. The labs slice (services) and the core marketplace slice (search, RFQ engine, multi-vendor routing) are separate, not-yet-merged efforts.

What shipped in this milestone

• A working, tested order lifecycle: a clinic can place an order with a supplier, the supplier fulfils it through a defined status flow, and revenue/COGS post to the supplier's books automatically, with a tested reversal path.
• A working receive bridge: a clinic can turn a fulfilled order into real inventory and a real expense in one action, reusing (not duplicating) the existing purchase/expense machinery — meaning stock valuation and tax treatment stay consistent with every other purchase already supported.
• A subscription-tier system for suppliers (free vs. paid capabilities, listing quotas) — the underlying revenue lever for the supplier side of this product, already wired to real gating in the code, not just a UI mock.
• A new deployable front-end app for suppliers (supplier-web), architecturally proven (built on the same pattern as the existing pharmacy-web app) but not yet wired into any deployment pipeline — see Risks below.

What's explicitly deferred

Per the engineering plan (docs/trade-platform/FEATURE-SUPPLIERS.md, "Later phases"): contract/tiered pricing per linked buyer, listing promotions, supplier analytics, and bulk catalog import. Per the same doc's ownership boundaries, the RFQ engine (creating/awarding RFQs) and richer multi-vendor marketplace search belong to the sibling marketplace-core branch and are not part of this milestone at all.

Risks / gaps to know about

• The seller portal isn't deployable anywhere yet. supplier-web has no production hostname configured (hostnames: [] in its brand config, pending trade-name/registrar approval) and isn't wired into this sandbox's deployment pipeline. The application code is complete and was verified to build/typecheck, but nobody outside this repo can use it today, including for further QA, without dev-server access. This is an infrastructure gap to plan for before the next demo or pilot.
• A coded state-machine gap: the code contains logic to reverse a supplier's recognized revenue if a fulfilled order is later cancelled or rejected — but the actual allowed status transitions never let an order reach "cancelled" or "rejected" after it's shipped. That reversal path is tested in isolation but is currently unreachable through the real product flow. Low risk today (nothing is silently wrong — it just means "cancel a shipped order" isn't a supported action yet), but worth a product decision: either add that transition, or accept that post-shipment cancellation isn't supported in this milestone.
• Cross-tenant financial independence is by design, not a gap: each side (buyer and supplier) posts its own books independently, with no shared ledger or reconciliation between them, and no commission/platform fee is taken in this version (the schema reserves fields for it, unused). This matches the stated v1 scope ("order-routing only, on-account") — flagging it here so it isn't mistaken for a missing feature.
• Buyer-side "Marketplace" search is intentionally minimal — a stopgap the team built specifically so this branch could be verified end-to-end before the shared marketplace-core search engine exists. Expect it to be replaced, not extended, once that lands.

How to think about "done" for this milestone

The PR's own verification claims (schema assembly, lint, build/typecheck, unit tests for the money math and quota gates) were spot-checked against the actual code during this documentation pass and hold up — the accounting balance/reversal guarantees and quota logic are real and tested. What has not been verified end-to-end is a live sandbox walkthrough of a full order (place → accept → ship → receive → stock + GL) — the PR description itself notes that full sandbox E2E is planned to run on the CI preview deploy, and this documentation pass could not exercise it either, since the sandbox has no seeded listings/vendor company and the seller portal isn't reachable from it (see the Walkthrough for exactly what was and wasn't observable live).