diff --git a/docs/MARKETPLACE_MODULE_DESIGN.md b/docs/MARKETPLACE_MODULE_DESIGN.md new file mode 100644 index 00000000..53f9bbf9 --- /dev/null +++ b/docs/MARKETPLACE_MODULE_DESIGN.md @@ -0,0 +1,497 @@ +# Generic Marketplace Module — Platform-Service Design + +> **Scope:** A product-agnostic marketplace/store module in `platform-service` that any ByteLyst app can use to publish, discover, purchase, review, and install user-created templates. +> +> **Date:** 2026-03-01 +> **Status:** Proposal + +--- + +## 1. Why Build This in Common Platform? + +Multiple ByteLyst apps need a marketplace for user-created content: + +| App | Template Type | Example | +| -------------- | ----------------------------------------------------------- | -------------------------------------- | +| **JarvisJr** | Agent templates (personas, prompts, voice config) | "FAANG Interview Prep Coach" | +| **MindLyst** | Brain Packs (brain configs, triage rules, default memories) | "Freelancer Finance Brain Pack" | +| **ChronoMind** | Routine templates, timer presets | "Morning Routine for Parents (45 min)" | +| **NomGap** | Fasting protocols, custom meal plans | "Ramadan Intermittent Protocol" | +| **PeakPulse** | Route presets, challenge templates | "Colorado 14ers Checklist" | + +Building this once in platform-service means every app gets: catalog, search, reviews, ratings, comments, purchases, certification, and analytics — for free. + +--- + +## 2. What Already Exists in Platform-Service + +| Existing Module | Reusable For Marketplace? | Gap | +| -------------------------- | ---------------------------------------------- | ------------------------------------------------------------------------- | +| **items** | Item CRUD, types, statuses, visibility, labels | Tracker-scoped (bugs/features), not generic listings | +| **comments** | Threaded comments (CRUD, author-only edit) | Currently tied to `tracker_comments` container — needs generic `entityId` | +| **votes** | Upvote toggle, count per item | Currently tied to `tracker_votes` — needs generic `entityId` | +| **public** | Unauthenticated browsing, submissions, voting | Tracker-specific routes — needs generic catalog routes | +| **feedback** | In-app feedback collection | Could feed into review system | +| **products** | Product registry (productId lookup) | Marketplace listings are per-product | +| **subscriptions + stripe** | Payment infrastructure | Could handle paid template purchases | +| **blob** | File storage (SAS tokens) | Template screenshots, preview assets | + +**Conclusion:** ~60% of infrastructure exists. The main gaps are: listings with JSON payloads, star ratings/reviews, certification workflow, install tracking, discovery/search, and versioning. + +--- + +## 3. Data Model + +### 3.1 Cosmos Containers (New) + +| Container | Partition Key | Purpose | +| ---------------------------- | ------------- | --------------------------- | +| `marketplace_listings` | `/productId` | Published template listings | +| `marketplace_reviews` | `/listingId` | Star ratings + text reviews | +| `marketplace_installs` | `/userId` | Track who installed what | +| `marketplace_certifications` | `/listingId` | Certification audit trail | +| `marketplace_reports` | `/listingId` | User abuse/flag reports | + +### 3.2 Core Types + +```typescript +// ── Listing (the publishable template) ──────────────────── + +interface MarketplaceListingDoc { + id: string; // lst_ + productId: string; // "jarvisjr" | "mindlyst" | "chronomind" | "nomgap" | "peakpulse" + templateType: string; // Product-specific: "agent" | "brain_pack" | "routine" | "protocol" | etc. + + // Author + authorId: string; // userId of creator + authorName: string; // Display name + authorAvatarUrl: string | null; + + // Content + title: string; // "FAANG Interview Prep Coach" + shortDescription: string; // 1-2 sentence pitch (max 200 chars) + description: string; // Full markdown description + tags: string[]; // ["interview", "career", "tech"] + category: string; // Product-specific categories + screenshots: string[]; // Blob URLs for preview images + previewUrl: string | null; // Optional demo/preview link + + // The actual template payload (product-specific JSON) + payload: Record; // Generic JSON — each app defines its own schema + payloadVersion: string; // "1.0", "1.1" — for forward compatibility + + // Pricing + pricingModel: 'free' | 'paid' | 'freemium'; + priceInCents: number; // 0 for free, e.g. 499 for $4.99 + currency: string; // "usd" + + // Certification + certificationStatus: 'draft' | 'submitted' | 'in_review' | 'approved' | 'rejected' | 'suspended'; + certificationNotes: string | null; // Reviewer feedback + certifiedAt: string | null; + certifiedBy: string | null; // Admin userId + + // Stats (denormalized for fast reads) + installCount: number; + reviewCount: number; + averageRating: number; // 0.0 - 5.0 + voteCount: number; // Upvotes (reuse existing votes pattern) + + // Versioning + version: string; // "1.0.0" + previousVersionId: string | null; // Link to previous version + + // Metadata + visibility: 'private' | 'unlisted' | 'public'; + featured: boolean; // Admin-set + createdAt: string; + updatedAt: string; + publishedAt: string | null; +} + +// ── Review (star rating + text) ────────────────────────── + +interface MarketplaceReviewDoc { + id: string; // rev_ + listingId: string; + productId: string; + authorId: string; + authorName: string; + rating: number; // 1-5 stars + title: string; // Review headline + body: string; // Review text + helpful: number; // "Was this helpful?" count + verified: boolean; // Author actually installed the template + createdAt: string; + updatedAt: string; +} + +// ── Install (track who installed what) ─────────────────── + +interface MarketplaceInstallDoc { + id: string; // inst_ + listingId: string; + productId: string; + userId: string; + version: string; // Version at time of install + installedAt: string; + uninstalledAt: string | null; +} + +// ── Certification (audit trail) ────────────────────────── + +interface MarketplaceCertificationDoc { + id: string; // cert_ + listingId: string; + productId: string; + action: 'submitted' | 'approved' | 'rejected' | 'suspended' | 'resubmitted'; + performedBy: string; // Admin userId or "system" + notes: string; + automatedChecks: { + // Results from auto-review + promptSafety: 'pass' | 'fail' | 'warn'; + contentPolicy: 'pass' | 'fail' | 'warn'; + payloadValid: boolean; + screenshotCount: number; + } | null; + createdAt: string; +} +``` + +--- + +## 4. API Design + +### 4.1 Author Endpoints (Authenticated) + +| Method | Path | Description | +| -------- | ----------------------------------- | -------------------------------- | +| `POST` | `/marketplace/listings` | Create draft listing | +| `GET` | `/marketplace/listings/mine` | List my listings | +| `GET` | `/marketplace/listings/:id` | Get listing detail | +| `PUT` | `/marketplace/listings/:id` | Update draft/rejected listing | +| `POST` | `/marketplace/listings/:id/submit` | Submit for certification | +| `POST` | `/marketplace/listings/:id/publish` | Publish approved listing | +| `DELETE` | `/marketplace/listings/:id` | Delete listing (author or admin) | + +### 4.2 Public Catalog Endpoints (No Auth Required) + +| Method | Path | Description | +| ------ | ---------------------------------- | -------------------------------------------- | +| `GET` | `/public/marketplace` | Browse catalog (paginated, filtered, sorted) | +| `GET` | `/public/marketplace/:id` | Get public listing detail | +| `GET` | `/public/marketplace/:id/reviews` | Get reviews for a listing | +| `GET` | `/public/marketplace/featured` | Featured/trending listings | +| `GET` | `/public/marketplace/categories` | List categories for a product | +| `GET` | `/public/marketplace/search?q=...` | Full-text search | + +### 4.3 Consumer Endpoints (Authenticated) + +| Method | Path | Description | +| -------- | ----------------------------------- | ------------------------------------------ | +| `POST` | `/marketplace/listings/:id/install` | Install a listing (track + return payload) | +| `DELETE` | `/marketplace/listings/:id/install` | Uninstall | +| `GET` | `/marketplace/installs` | List my installed templates | +| `POST` | `/marketplace/listings/:id/reviews` | Add review (must have installed) | +| `PUT` | `/marketplace/reviews/:id` | Edit my review | +| `DELETE` | `/marketplace/reviews/:id` | Delete my review | +| `POST` | `/marketplace/listings/:id/vote` | Upvote toggle (reuse votes pattern) | + +### 4.4 Admin Endpoints (Admin Auth) + +| Method | Path | Description | +| ------ | ---------------------------------------- | ------------------------- | +| `GET` | `/marketplace/admin/pending` | Listings awaiting review | +| `POST` | `/marketplace/admin/:id/approve` | Approve listing | +| `POST` | `/marketplace/admin/:id/reject` | Reject with notes | +| `POST` | `/marketplace/admin/:id/suspend` | Suspend published listing | +| `POST` | `/marketplace/admin/:id/feature` | Toggle featured flag | +| `GET` | `/marketplace/admin/stats` | Marketplace analytics | +| `GET` | `/marketplace/admin/reports` | User abuse reports queue | +| `POST` | `/marketplace/admin/reports/:id/resolve` | Resolve a report | + +### 4.5 Report/Flag Endpoints (Authenticated) + +| Method | Path | Description | +| ------ | ---------------------------------- | --------------------------------- | +| `POST` | `/marketplace/listings/:id/report` | Flag a listing (reason + details) | +| `GET` | `/marketplace/reports/mine` | List my submitted reports | + +### 4.6 Query Parameters for Catalog Browse + +``` +GET /public/marketplace?productId=jarvisjr + &templateType=agent + &category=career + &tags=interview,tech + &pricingModel=free + &minRating=4 + &sortBy=installCount|rating|newest|trending + &q=interview+prep + &limit=20 + &offset=0 +``` + +--- + +## 5. Certification Workflow + +``` +Author creates listing (draft) + | + v +Author submits for review + | + v ++-- Automated checks run --------+ +| - Prompt safety scan (LLM) | +| - Content policy check | +| - Payload schema validation | +| - Screenshot count >= 1 | ++--------------------------------+ + | + +-- Auto-fail? --> REJECTED (with notes) + | + v +Manual admin review queue + | + +-- APPROVED --> Author can publish + | + +-- REJECTED --> Author can edit and resubmit + | + v +Published (visible in public catalog) + | + +-- Reports/flags --> Admin can SUSPEND +``` + +### Automated Check Details + +| Check | What It Does | Fail Criteria | +| ---------------------- | --------------------------------------------------------------- | ----------------------------------------------------------------- | +| **Prompt safety** | LLM scans system prompt for harmful content, jailbreaks | Harmful, deceptive, or policy-violating prompts | +| **Content policy** | Scan title + description for profanity, spam, misleading claims | Profanity, spam keywords, medical/legal claims without disclaimer | +| **Payload validation** | Zod schema validation per product type | Invalid JSON structure for the templateType | +| **Screenshots** | Count uploaded screenshots | Less than 1 screenshot | +| **Duplicate check** | Cosine similarity against existing listings | >90% similarity to existing listing | + +--- + +## 6. Product-Specific Payload Schemas + +Each app defines what goes inside the `payload` field. The marketplace module treats it as opaque JSON — validation is delegated to product-specific Zod schemas. + +### JarvisJr Agent Template Payload + +```typescript +{ + agentName: string; // "Coach", "Lingua", etc. (user can rename after install) + defaultVoice: string; // Voice ID from TTS provider + systemPrompt: string; // The core coaching prompt + welcomeMessage: string; // First message when session starts + coachingFramework: string; // "socratic" | "cbr" | "free_form" | "structured" + suggestedSessionLength: number; // Minutes + difficultyLevel: string; // "beginner" | "intermediate" | "advanced" + tags: string[]; + exampleConversation: string; // Sample dialogue showing the agent in action +} +``` + +### MindLyst Brain Pack Payload + +```typescript +{ + brains: Array<{ + name: string; // "Work", "Finance", etc. + description: string; + triageRules: string; // Triage prompt + defaultCategories: string[]; + }>; + suggestedRoutine: string; // "Morning brief at 8am, evening wind-down at 9pm" +} +``` + +### ChronoMind Routine Template Payload + +```typescript +{ + routineName: string; + steps: Array<{ + label: string; + durationMinutes: number; + urgency: string; + }>; + totalMinutes: number; + tags: string[]; +} +``` + +### NomGap Protocol Payload + +```typescript +{ + protocolName: string; + fastHours: number; + eatHours: number; + description: string; + difficulty: string; + electrolyteSchedule: object | null; + culturalContext: string | null; // "ramadan" | "ekadashi" | etc. +} +``` + +### PeakPulse Challenge Payload + +```typescript +{ + challengeName: string; + activityType: string; // "hiking" | "skiing" | "trail_running" + peaks: Array<{ + name: string; + elevationMeters: number; + latitude: number; + longitude: number; + difficulty: string; // "easy" | "moderate" | "hard" | "expert" + notes: string; + }>; + totalPeaks: number; + region: string; // "Colorado", "Alps", etc. + tags: string[]; +} +``` + +--- + +## 7. Reuse Strategy — Existing Modules + +| Existing Module | How Marketplace Reuses It | +| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------- | +| **comments** | **Decision: keep reviews separate.** Reviews are structurally different (star rating, verified install, helpful count). Comments remain tracker-only. | +| **votes** | Generalize to support `entityType: 'tracker_item' | 'marketplace_listing'`. Same toggle pattern. | +| **blob** | Template screenshots upload via existing SAS token endpoints. New container: `marketplace_assets`. | +| **stripe** | Paid template purchases via existing Stripe integration. New `line_item` type for marketplace. | +| **flags** | Feature-flag new marketplace features per product. | +| **delivery** | Email notifications: "Your listing was approved", "New review on your template". | +| **audit** | Audit trail for certification actions. | + +--- + +## 8. Implementation Phases + +### Phase 1 — Core Marketplace (Sprint 1-2) + +New module: `services/platform-service/src/modules/marketplace/` + +| File | Content | +| ----------------------------- | ----------------------------------------------- | +| `types.ts` | All Zod schemas + TypeScript interfaces above | +| `listing-repository.ts` | Listing CRUD against `marketplace_listings` | +| `review-repository.ts` | Review CRUD against `marketplace_reviews` | +| `install-repository.ts` | Install tracking against `marketplace_installs` | +| `certification-repository.ts` | Certification audit trail | +| `routes.ts` | Author + consumer + public + admin endpoints | +| `marketplace.test.ts` | Full test suite | + +**Estimated:** ~800-1000 lines, ~40-50 tests. + +### Phase 2 — Automated Certification (Sprint 3) + +- LLM-based prompt safety scan +- Content policy checker +- Payload schema validation per product type +- Auto-reject pipeline + +### Phase 3 — Paid Templates + Revenue Share (Sprint 4) + +- Stripe integration for marketplace purchases +- Revenue share tracking (70% author / 30% platform) +- Payout management + +### Phase 4 — Discovery and Analytics (Sprint 5) + +- Trending algorithm (installs _ recency _ rating) +- Featured curation (admin) +- Author analytics dashboard +- Recommendation engine ("Users who installed X also installed Y") + +--- + +## 9. Cosmos Container Cost Impact + +| Container | Estimated Docs (Year 1) | RU Impact | +| ---------------------------- | ----------------------- | -------------------------- | +| `marketplace_listings` | ~5,000 | Low (mostly reads) | +| `marketplace_reviews` | ~20,000 | Low | +| `marketplace_installs` | ~100,000 | Medium (high write volume) | +| `marketplace_certifications` | ~10,000 | Low | + +Serverless Cosmos DB: ~$0.25/100K RU. Total estimated cost: **<$5/month** at launch scale. + +Additional blob container needed: `marketplace_assets` (screenshots, preview images) — uses existing `blob` module SAS token endpoints. + +--- + +## 9.1 Rate Limiting + +All public marketplace endpoints inherit the rate limiting from the `public` module pattern: + +| Endpoint Type | Rate Limit | +| --------------------- | ------------------- | +| Public browse/search | 60 req/min per IP | +| Public listing detail | 60 req/min per IP | +| Report/flag | 5 req/min per IP | +| Install | 30 req/min per user | +| Review | 10 req/min per user | + +--- + +## 9.2 Versioning and Update Workflow + +When an author updates a published listing: + +1. Author edits listing and bumps `version` field (e.g., 1.0.0 -> 1.1.0) +2. Updated listing goes through certification again (same workflow) +3. Once approved, the listing is updated in-place (same `id`) +4. `previousVersionId` points to a snapshot of the old version +5. Users who installed v1.0.0 see a "Update Available" badge on their agent card +6. Update is optional — users keep their customizations, only the base template payload changes +7. Delivery module sends email: "A template you installed has been updated" + +--- + +## 10. Dashboard UI (Admin + Tracker) + +### Admin Dashboard — Marketplace Management + +New pages under `/ops/marketplace/`: + +| Page | Features | +| ---------------------------- | ------------------------------------------------------------ | +| `/ops/marketplace` | Overview: pending reviews, total listings, installs, revenue | +| `/ops/marketplace/pending` | Certification queue: approve/reject with notes | +| `/ops/marketplace/listings` | All listings: filter by product, status, author | +| `/ops/marketplace/analytics` | Charts: installs over time, top listings, revenue | + +### Per-App — Marketplace Browse UI + +Each app builds its own browse UI consuming the public API: + +``` +/marketplace — Browse catalog (grid of cards) +/marketplace/:id — Listing detail (description, reviews, install button) +/marketplace/mine — My published templates +/marketplace/create — Create/edit listing wizard +/marketplace/installed — My installed templates +``` + +--- + +## 11. Cross-App Benefits Summary + +| App | Without Generic Marketplace | With Generic Marketplace | +| -------------- | --------------------------------------------- | ------------------------------------------------ | +| **JarvisJr** | Build custom agent store from scratch | Just define payload schema, get full marketplace | +| **MindLyst** | Brain Pack sharing via simple deep links only | Full catalog, reviews, ratings, discovery | +| **ChronoMind** | Routine sharing not planned | Community routine templates with ratings | +| **NomGap** | Custom protocols stuck in-app | Share protocols, cultural fasting templates | +| **PeakPulse** | No sharing mechanism | Route/challenge templates from community |