​

Module Marketplace — Design Spec

​

1. Goal

• Self-serve / instant activation. The manual approval step is the cash gate.
• Per-tenant version pinning. Every clinic always runs latest.
• Public unauthenticated views. No portal.odontox.io exposure, no anonymous browsing, no SEO surface.
• Plan-bundled module listings (Patients, Appointments, etc.). The catalog is addons only.
• Smart usage-threshold recommendation engine (G2 emails) — deferred to v2.
• Free trials on addons.

​

2. Lifecycle (authoritative)

[ requested ] → [ invoiced ] → [ paid ] → [ active ]
                                              ↓
                                       [ cancel_requested ]
                                              ↓
                                          [ cancelled ]
                       ─── rejected ──→ [ rejected ]   (from any pre-active state)

​

3. Schema

​

3.1 marketplace_listings (new)

​

3.2 marketplace_releases (new)

​

3.3 addon_requests (extend existing)

• Broaden addonType to include module keys: add new values dicom_imaging, whatsapp_api, ipd, insurance, marketing, mrn.
• Add status value cancel_requested, cancelled (existing has pending, approved, rejected).
• Add nullable cancelledAt, cancelReason.
• For module addons (non-resource), quantity = 1, unitPricePkr and totalPricePkr populated by superadmin at invoice-issue time (or via new module_addon_pricing if we want a default table — see §3.4).

​

3.4 addon_pricing (extend existing)

moduleAddonPricing: jsonb('module_addon_pricing').notNull().default(sql`'{}'::jsonb`)
// shape: { dicom_imaging: { pro: 8000, proPlus: 8000 }, whatsapp_api: { pro: 5000, ...}, ... }

​

3.5 No new permission system

• marketplace.view — list addons, see detail pages. Granted by default to all roles except portal/patient.
• marketplace.request — submit subscribe requests. Owner + clinic_admin only by default.
• marketplace.cancel — submit cancellation requests. Owner + clinic_admin only by default.

​

4. Backend surface

​

4.1 Tenant-facing routes (server/src/routes/marketplace.ts, new)

​

4.2 Superadmin routes (server/src/routes/superadmin/marketplace.ts, new)

​

4.3 Cron jobs (extend server/src/scheduled.ts)

• marketplace-overdue-invoices — daily 09:00 PKT. Finds invoiced requests >7 days old, sends G3 overdue email (idempotent: tracked via last_overdue_email_at column on request).
• marketplace-idle-nudge — weekly Monday 10:00 PKT. Finds active subscriptions where the module hasn’t been used in 30+ days (heuristic per-addon: dicom_imaging → no DICOM uploads, whatsapp_api → no outbound messages, etc.), sends G4 idle nudge. Capped 1 per addon per clinic per 60 days.

​

4.4 Egress + security

• Returns only the fields the tenant UI renders. No updated_by, no draft/archived rows, no superadmin internal notes.
• Screenshot URLs are R2 signed URLs with 1-hour TTL, generated per request.
• Listings cached short-lived (5 min) in worker memory; busts on superadmin PATCH (event hook).

• Requires verifySuperAdmin.
• Writes an audit log via recordAuditLog for every state transition + listing edit.

• Tenant subscribe: 1 per (clinic, listing) per hour.
• Tenant cancel: 1 per (clinic, listing) per hour.
• Listing detail: 60/min/clinic (prevents scrape if creds leak).

​

5. Frontend surface

​

5.1 Tenant — /dashboard/marketplace

• Hero band: “Extend OdontoX — apps built for your practice.” No marketing fluff for non-tenants since there are no non-tenants here.
• Search input + category chips (All / Clinical / Admin / Comms / Infra).
• Grid of listing cards (responsive: 1col mobile, 2col tablet, 3col desktop).
• Card anatomy: icon tile (32×32 with hero_color gradient bg), display_name, tagline, version badge, “v1.2.0 · Updated 2d ago”, pricing_summary, state pill (none → “Subscribe” button, requested → “Pending review”, invoiced → “Invoice issued”, paid → “Awaiting activation”, active → “Installed” check, cancel_requested → “Cancellation pending”).
• Hover: subtle scale + ring transition. No shadow noise.
• Empty state: 0 published listings → “No apps available yet” with illustration.

• URL: /dashboard/marketplace/:key
• Hero: large icon + display_name + tagline + state pill + primary CTA (Subscribe / Cancel / view request status).
• Tabs: Overview (long_description_md + what_you_get + security_badges), Screenshots (carousel), What’s new (releases list, newest first, each expandable), FAQ (accordion), Pricing (pricing_summary + “Final pricing confirmed at invoice”).
• Subscribe action: confirm modal — “We’ll review your request and email an invoice. Module activates after payment.” No internal mention of superadmin.
• Cancel action (active state only): confirm modal — “Cancellation takes effect after review.”
• Request history strip at bottom: “Your requests for this app” with status timeline.

• URL: /dashboard/marketplace/requests
• Table of all this clinic’s marketplace requests with status timeline + per-row drill-in.

• Add to ui/src/lib/nav-registry.ts as a top-level item between Settings and Help, icon Store from lucide. Gated on marketplace.view.

​

5.2 Superadmin — /superadmin/marketplace

• List of all listings (draft/published/archived) with status filter.
• Click row → side drawer editor.
• Editor: form for all metadata, markdown preview pane, screenshot upload (drag-drop to R2), release manager (add release with is_major checkbox), status dropdown.
• “Publish” action goes from draft → published. Confirm modal warns “Tenants will see this immediately. Send launch email?” → checkbox triggers G1 broadcast.

• Inbox view of all in-flight requests (extends existing /superadmin/addon-requests).
• Filter by status. Default = requested + invoiced + paid + cancel_requested.
• Per-row actions: Issue invoice (price + email), Mark paid, Approve, Reject, Confirm cancel. Each action requires confirmation; each writes audit + fires the matching email.

• Extends existing addon-pricing CMS to cover the new moduleAddonPricing jsonb. Per-module per-tier fields.

​

5.3 Visual direction

• No new design system. Reuse the same Tailwind tokens, fonts, and shadcn primitives already in ui/src/components/ui/.
• Card gradient = bg-gradient-to-br from-{hero_color}-50 to-{hero_color}-100 dark:from-{hero_color}-950/20 dark:to-{hero_color}-900/10.
• Icon tile: bg-{hero_color}-500/10 text-{hero_color}-600 with the lucide icon, rounded-xl.
• Typography: existing text-balance headlines, mono for version badges.
• No icons of dollars (memory: “no DollarSign / use Banknote”).

​

6. Emails (v1)

​

7. Security checklist (top-priority per user)

• Every tenant route requires verifyAuth + clinic context. No anonymous access anywhere.
• No public marketplace surface. Not on portal.odontox.io, not on q.odontox.io.
• Every superadmin route requires verifySuperAdmin.
• Permission split: marketplace.view / marketplace.request / marketplace.cancel. Owner + clinic_admin only get request/cancel by default.
• Rate limits on subscribe/cancel POST (1/hr per clinic per listing).
• CSRF token required on all POST/PATCH/DELETE routes (existing middleware).
• R2 screenshot URLs are short-lived signed URLs, not public.
• Tenant API responses strip superadmin-internal fields (updated_by, draft/archived rows, internal notes).
• Audit log entry on every state transition + every listing edit.
• No tenant or addon internal UUIDs exposed in user-facing URLs — use module key (dicom_imaging) which is already public knowledge.
• Email templates never include billing internals or superadmin role names.
• No “instant activation” code path; clinic_modules.isEnabled = true only writable from the approve route which requires verifySuperAdmin + state guard status === 'paid'.
• Cron jobs idempotent (track last_overdue_email_at, last_idle_nudge_at on requests).

​

8. Migrations

1. CREATE TABLE marketplace_listings (...) per §3.1
2. CREATE TABLE marketplace_releases (...) per §3.2 + index
3. ALTER TABLE addon_requests ADD COLUMN cancelled_at timestamptz NULL
4. ALTER TABLE addon_requests ADD COLUMN cancel_reason text NULL
5. ALTER TABLE addon_requests ADD COLUMN last_overdue_email_at timestamptz NULL
6. ALTER TABLE addon_requests ADD COLUMN last_idle_nudge_at timestamptz NULL
7. ALTER TABLE addon_pricing ADD COLUMN module_addon_pricing jsonb NOT NULL DEFAULT '{}'::jsonb
8. Seed marketplace_listings with 8 initial rows (6 module addons + storage + portal_seats) — status draft so nothing goes live until superadmin reviews.

​

9. File-level deliverables

• server/src/schema/marketplace_listings.ts (new)
• server/src/schema/marketplace_releases.ts (new)
• server/src/schema/addon_requests.ts (extend — verify path)
• server/src/schema/addon_pricing.ts (extend)
• server/src/routes/marketplace.ts (new — tenant)
• server/src/routes/superadmin/marketplace.ts (new — CMS + request inbox)
• server/src/lib/marketplace-usage.ts (new — idle heuristics)
• server/src/scheduled.ts (extend — 2 new crons)
• server/src/emails/MarketplaceListingLaunchedEmail.tsx
• server/src/emails/MarketplaceReleaseEmail.tsx
• server/src/emails/MarketplaceInvoiceReadyEmail.tsx
• server/src/emails/MarketplaceInvoiceOverdueEmail.tsx
• server/src/emails/MarketplaceAddonLiveEmail.tsx
• server/src/emails/MarketplaceAddonIdleEmail.tsx
• server/drizzle/<next>_marketplace.sql (migration)
• docs/api-reference.md (extend — per memory rule)

• ui/src/pages/marketplace/MarketplaceIndex.tsx (new)
• ui/src/pages/marketplace/MarketplaceDetail.tsx (new)
• ui/src/pages/marketplace/MarketplaceRequests.tsx (new)
• ui/src/pages/superadmin/SuperadminMarketplace.tsx (new — listings + requests + pricing tabs)
• ui/src/components/marketplace/ListingCard.tsx
• ui/src/components/marketplace/ListingHero.tsx
• ui/src/components/marketplace/ChangelogList.tsx
• ui/src/components/marketplace/RequestStateBadge.tsx
• ui/src/components/superadmin/MarketplaceListingEditor.tsx
• ui/src/components/superadmin/MarketplaceRequestRow.tsx
• ui/src/hooks/use-marketplace-listings.ts (TanStack Query)
• ui/src/hooks/use-marketplace-requests.ts
• ui/src/lib/queryKeys.ts (extend)
• ui/src/lib/nav-registry.ts (extend — add Marketplace entry)
• ui/src/lib/permissions-keys.ts (extend — 3 new perms)
• ui/src/lib/permissions.ts (extend — default role grants)
• ui/src/App.tsx (extend — routes)

​

10. Out-of-scope follow-ups (v2 backlog)

• G2 smart usage-threshold recommendation emails (needs per-addon trigger rules engine).
• In-marketplace payment (Stripe Checkout / saved PM). Today payment is offline.
• Per-tenant version pinning + version-gated code paths.
• Public marketing surface on q.odontox.io (explicitly excluded by user — “no public views allowed”).
• Per-addon free trial windows.
• Tenant-to-tenant referral discounts.

​

11. Open assumptions (assumed true, flag if wrong)

• Existing addonRequests.addonType is a text column not a strict enum, so widening values is a code-side change only. Verify in migration plan.
• R2 signed URL helper exists in server/src/lib/r2.ts or similar — reuse, don’t reinvent.
• Existing notification preference table has a marketplace_emails toggle slot or accepts a new key. Otherwise add one in the migration.
• Sidebar nav and permission tree changes will not require touching the mobile codebase (mobile is patient-only — confirmed in memory).