Developer Docs

Beta Readiness Checklist

Audience: Internal platform engineers preparing for the Family & Friends beta launch.

This document is the single source of truth for beta readiness. Before testers arrive, every engineer should understand the architecture, core user flows, known limitations, and what happens during key lifecycle events.

1. Architecture at a Glance

Mallnline is a federated GraphQL platform with 17 subgraphs composed via Hive Gateway into a single supergraph (~525K characters of SDL).

┌─────────────────────────────────────────────────────────────────┐
│                    ngwenya-gateway :30000                        │
│            Hive Gateway  ·  Federation v2.9  ·  525K SDL        │
├──────┬──────┬──────┬──────┬──────┬──────┬──────┬───────────────┤
│malets│prods │servs │ucart │media │blogs │comms │  + 7 NestJS   │
│:3001 │:3004 │:3003 │:3005 │:3006 │:3007 │:3016 │  subgraphs    │
├──────┴──────┼──────┴──────┼──────┴──────┼──────┴───────────────┤
│    auth     │   uchat     │    scim     │ intelligence (Rust)  │
│   :3008     │   :3017     │   :3019     │   :3026              │
├─────────────┴─────────────┴─────────────┴──────────────────────┤
│  postgres   │   redis     │   mongo     │ meilisearch │conduit │
│   :5432     │   :6379     │  :27017     │    :7700    │ :8448  │
└─────────────────────────────────────────────────────────────────┘

Subgraph Registry (17 total)

# Subgraph Port Technology Purpose
1 malets 3001 NestJS Storefront management, ownership, verticals
2 services 3003 NestJS Bookable services, schedules, add-ons
3 products 3004 NestJS Product catalog, variants, inventory
4 ucart 3005 NestJS Shopping cart, multi-malet aggregation
5 media 3006 NestJS File uploads, image editing, Cloudflare R2
6 blogs 3007 NestJS Blog posts, publishing workflow
7 auth 3008 Rust (Axum) OIDC, passkeys, OTP, social login
8 nodes 3009 NestJS User profiles, handles, follows, social graph
9 organizations 3010 NestJS Teams, RBAC, invitations, audit
10 murchases 3013 NestJS Orders, fulfillment, workrooms, tracking
11 payments 3014 NestJS Stripe, subscriptions, invoice, tier enforcement
12 search 3015 NestJS Full-text search, facets, trending
13 community 3016 NestJS Q&A, reviews, discussions, moderation
14 uchat 3017 Rust (Axum) End-to-end encrypted messaging
15 alerts 3025 NestJS Email/SMS/in-app notifications, WS subscriptions
16 scim 3019 Rust (Axum) SCIM 2.0 directory provisioning (REST only)
17 experiences 3020 NestJS 13 vertical experience modules

Infrastructure

Service Port Purpose
PostgreSQL 5432 Auth, uChat, SCIM databases
MongoDB 27017 All NestJS subgraph data
Redis 6379 Response caching, APQ, rate limiting, WS presence
Meilisearch 7700 Search index (products, services, malets, blogs)
Conduit 8448 Matrix homeserver for uChat E2E encryption

Cross-service communication: TCP microservices (NestJS ClientProxy) for payments, alerts, and nodes. Events are fire-and-forget via EventPattern (emit()); queries use MessagePattern (send()) with firstValueFrom.

Database: MongoDB (Typegoose ODM) for all NestJS services. PostgreSQL (SQLx) for Rust services (auth, uchat, SCIM).

2. Core User Flows (E2E)

Flow A: Visitor Browses → Buys → Tracks

Browser → Gateway → search (product discovery)
  ↓
Browser → Gateway → products (product detail)
  ↓
Browser → Gateway → ucart (addToCart, checkout)
  ↓
ucart → payments (charge via Stripe)
  ↓
payments → murchases (create Murchase record)
  ↓
murchases → alerts (order confirmation email)
  ↓
Browser → Gateway → murchases (trackMurchase)

Flow B: Owner Creates Malet → Lists Product → Fulfills Order

Browser → Gateway → auth (sign in)
  ↓
Browser → Gateway → malets (createMalet with vertical config)
  ↓
Browser → Gateway → products (createOneProduct)
  ↓
[Visitor purchases — see Flow A]
  ↓
Browser → Gateway → murchases (advanceWorkroom)
  ↓
murchases → alerts (shipping notification)

Flow C: Organization Lifecycle

Browser → Gateway → organizations (createOrganization)
  ↓
organizations → payments (bootstrap_org_subscription → free Starter)
organizations → alerts (org_created notification)
  ↓
Browser → Gateway → organizations (sendInvitation)
  ↓
organizations → alerts (invitation email)
  ↓
Browser → Gateway → malets (transferMaletToOrganization)
  ↓
Browser → Gateway → organizations (deleteOrganization)
  ↓ [BLOCKED if: active paid subscription OR owned Malets > 0]
organizations → alerts (organization_deleted notification)

3. Known Gaps & Workarounds

WARNING

These are known limitations that beta testers may encounter.

✅ Fully Wired

Feature Notes
Guest checkout Email-only checkout, OTP lookup, order reassignment on account creation
Stripe payments Test mode; PaymentIntents for products, SetupIntents for subscriptions
Email notifications Via Resend (alerts service) — purchase confirmations, OTP, org invites
WebSocket subscriptions Real-time notifications through Hive Gateway federation
Search sync Meilisearch with facets, real-time index sync via TCP events
Org subscription bootstrap Free Starter auto-created on org creation via TCP event
Org deletion safety Blocks deletion if active paid subscription or owned Malets
Malet transfers Bidirectional Personal ↔ Organization via Deck UI

🟡 Partially Wired (Mock/Stub)

Feature Current State Bug
Invoice history Billing page shows "Demo Data" badge with mock invoices P2 — Stripe Customer ID not linked
Payment methods Mock card display on billing page P2 — Stripe PaymentMethod API not exposed
Checkout totals Subscription checkout sidebar may show wrong amount Bug #71
Org invite in-app Email sent but no IN_APP AlertLog created Bug #72
Malet contact form UI exists, form submit is a no-op Bug #74
Onboarding flow Auth returns is_new_user but frontend doesn't redirect Bug #68

🔴 Not Built

Feature Notes
CI/CD pipeline Manual deploys only
Production domain No beta.mallnline.com DNS/SSL
Database backups No mongodump / pg_dump schedule
Error tracking No Sentry — crashes invisible
M-Pesa payments Stripe is the only active processor

4. Event Flow Map

The platform uses NestJS TCP microservice transport for inter-service communication:

  • emit() — Fire-and-forget (no response). Used for notifications and index updates.
  • send() — Request-response (RPC). Used for queries like get_active_tier.

Event Flow Diagram

┌────────────┐    bootstrap_org_subscription     ┌────────────┐
│organizations│ ────────────────────────────────▶│  payments   │
│            │    org_invite_created             │            │
│            │ ────────────────────────────────▶│   alerts    │
│            │    organization_deleted           │            │
│            │ ────────────────────────────────▶│   alerts    │
└────────────┘                                   └────────────┘

┌────────────┐    item_upserted / item_deleted   ┌────────────┐
│  products   │ ────────────────────────────────▶│   search    │
│  services   │ ────────────────────────────────▶│            │
│   blogs     │    blog_post_upserted            │            │
│   malets    │    malet_upserted/soft_deleted    │            │
└────────────┘                                   └────────────┘

┌────────────┐    order_status_changed           ┌────────────┐
│  murchases  │ ────────────────────────────────▶│   alerts    │
│            │    workroom_action_required       │            │
└────────────┘                                   └────────────┘

┌────────────┐    issue_created/assigned          ┌────────────┐
│  community  │    discussion_created/assigned    │   alerts    │
│            │    question_answered/flagged      │            │
└────────────┘ ────────────────────────────────▶└────────────┘

┌────────────┐    user_created                   ┌────────────┐
│    auth     │ ────────────────────────────────▶│   nodes     │
│            │ ────────────────────────────────▶│   alerts    │
└────────────┘                                   └────────────┘

Complete Event Registry

Verified from @EventPattern and .emit() calls across all subgraphs (2026-04-25).

Organization Lifecycle

Event Producer Consumer Pattern
bootstrap_org_subscription organizations payments emit
org_invite_created organizations alerts (email) emit
org_invite_sms organizations alerts (SMS) emit
organization_deleted organizations alerts emit
get_active_tier organizations, malets payments send (RPC)

Auth & Identity

Event Producer Consumer Pattern
user_created auth nodes, alerts emit
notify_email gateway, various alerts emit
send_sms / notify_sms various alerts emit

Commerce & Fulfillment

Event Producer Consumer Pattern
order_status_changed murchases alerts emit
workroom_action_required murchases alerts emit
payment_captured payments services (bookings) emit

Search Index Sync

Event Producer Consumer Pattern
item_upserted products, services search emit
item_deleted / item_soft_deleted products, services search emit
malet_upserted malets search emit
malet_soft_deleted / malet_restored malets search emit
malet_verification_updated malets search emit
malet_tags_updated malets search emit
blog_post_upserted / blog_post_deleted blogs search emit
rating_updated community search emit

Community & Alerts

Event Producer Consumer Pattern
issue_created / issue_assigned / issue_unassigned community alerts emit
issue_state_changed community alerts emit
discussion_created / discussion_assigned community alerts emit
question_answered / question_flagged community alerts emit
vertical_intelligence_suggestion malets alerts emit

Media

Event Producer Consumer Pattern
transcode_video_hls media video emit

5. "What Happens When…?" FAQ

Answers to lifecycle questions that beta testers and developers frequently ask.

What happens when I delete my Organization?

Pre-conditions (must all pass):

  1. ✅ No active paid subscription (Starter/free is OK)
  2. ✅ No owned Malets (transfer or delete them first)
  3. ✅ Actor has OWNER role

Cascade:

  • All memberships deleted
  • All pending invitations deleted
  • Organization record deleted
  • Audit event created (ORG_DELETED)
  • organization_deleted event emitted to alerts

What is NOT deleted: User accounts, personal Malets, payment history

What happens to org-owned Malets after org deletion?

With the new safety guards: You cannot delete an org that owns Malets. The deleteOrganization mutation returns:

"Cannot delete organization that owns 3 Malet(s). Transfer or delete all Malets before deleting the organization."

Use the Deck → Transfer button to move Malets back to your personal account first.

What happens when a subscription is cancelled?

  • Subscription status → CANCELLED at end of billing period
  • Org reverts to Starter plan limits (1 Malet, 3 members)
  • Excess Malets become read-only (not deleted)
  • Team members above the limit lose write access (not removed)
  • Data is never deleted — renewing restores full access

What happens when a Malet is soft-deleted?

  • Malet status → TRASHED, hidden from all public surfaces
  • Products and services become invisible in search
  • Owner can restore from /trash within 30 days
  • After 30 days: permanently deleted (data + media purged)

What happens when a user deletes their account?

  • User record → soft-deleted, anonymized after 30-day grace period
  • Personal Malets → soft-deleted (same 30-day window)
  • Org memberships → removed (other members unaffected)
  • uChat messages → retained but author shown as "Deleted User"
  • Reviews/Q&A → retained but author anonymized

What happens when a product goes out of stock?

  • inventory.quantity → 0
  • Product still visible in storefront with "Out of Stock" badge
  • Add to uCart is disabled
  • Low stock alert fires if quantity < lowStockThreshold

6. Pre-Launch Checklist

Must-Have (Blocking)

  • All 17 subgraphs healthy and registered in gateway
  • Stripe test mode configured with webhook endpoint
  • Email delivery verified (Resend)
  • Placeholder content removed (press section, fake metrics)
  • Org deletion safety guards in place
  • FAQ page live at /help/faq with 25 categorized questions
  • Error boundaries on 17 routes
  • Workroom tracking UI for order fulfillment
  • Legal pages have "Draft — Not Legally Reviewed" banner

Should-Have (Important)

  • Database backup strategy (MongoDB Atlas + cron)
  • CORS locked to production origins
  • Error monitoring (Sentry or equivalent)
  • Guest checkout smoke test (no account)
  • Multi-Malet uCart test (items from 2+ Malets)
  • Fix /help broken sub-routes
  • Fix /careers non-functional apply buttons
  • Empty state messages audit (lobby, uCart, murchases, notifications)
  • Loading skeleton audit (all data-fetching pages)
  • Mobile responsive audit (Safari + Chrome)

Nice-to-Have (Post-Beta)

  • Custom domain support
  • M-Pesa payment integration
  • Mobile app (KMP scaffold exists, iOS/Android shells not started)
  • AI-powered search recommendations (Intelligence service)

File Reference

Document Path Purpose
Backend TODO BACKEND_TODO.md Active backend tasks
Frontend TODO FRONTEND_TODO.md Active frontend tasks
Bug Tracker bugs.md All bugs with resolution status
Beta Audit beta-readiness-audit.md Original gap analysis (2026-04-24)
Org Lifecycle FAQ org-lifecycle-faq.md End-user FAQ about org lifecycle