Note

    1018 – SaaS Portal Platform

    Plan and implement a multi-tenant SaaS portal for cryobanks and clinics with RBAC, billing, analytics, and professional workflows, separate from the Family and Donor apps

    Executive Summary

    This project establishes the professional SaaS portal for cryobanks and clinics. It is a separate application from the Family and Donor platforms and will own pro features like Donor Database, Sibling Groups, Family Trees (SaaS-positioned), analytics, donor tracking, audit logging, and compliant messaging. Multi-tenancy, strong RBAC, and clear data ownership boundaries are foundational.

    Dependencies: Decisions and artifacts from 1018.P0.0–P0.2 (starter selection, repo plan, user journeys, consolidated decisions). Until those are approved, this plan is a proposal scaffold.

    Scope and Non-Goals

    • In scope: SaaS app bootstrap, multi-tenant auth and RLS, billing/subscriptions, core pro features MVPs, audit logging, admin onboarding, tenant routing, CI/CD, and basic analytics.
    • Out of scope: Family/Donor UI work, extensive privacy research beyond MVP policies, long-tail reporting, and advanced messaging beyond initial compliance baseline.

    Architecture Overview (high level)

    • Frontend: React/TypeScript app within monorepo, shared design system and utilities.
    • Backend: Supabase (Postgres, Auth, RLS, functions) + optional starter server components as integration layer.
    • Data: saas_* schemas for tenant-scoped entities (e.g., saas_organizations, saas_memberships, saas_subscriptions, saas_audit_logs).
    • AuthZ: JWT claims enrichment with tenant_id/tenant_slug and role; RLS policies enforce isolation.
    • Routing: tenant-slug.saas.familyshapes.com (or path-based fallback) per 1016 decisions.
    • Billing: Stripe subscriptions with seats; metering for usage-based items as applicable.

    Cross-doc references:

    • 1018.P0.0 SaaS Starter Research: DOCS/PROJECTS/active/1018/1018_P0_SaaS_Starter_Research.md
    • 1018.P0.1 Architecture & Repo Plan: DOCS/PROJECTS/active/1018/1018_P0_Architecture_Repo_Plan.md
    • 1018.P0.2 User Journeys & Requirements: DOCS/PROJECTS/active/1018/1018_P0_User_Journeys_Requirements.md
    • 1018.P0 Decision Record: DOCS/PROJECTS/active/1018/DR-1018-P0_Decision_Record.md

    Phase Plan

    1018.P1 – App Bootstrap and Tenant Routing ⏳

    • 1018.P1.1 Starter integration and repository setup
      • Scaffold app from selected starter; integrate with monorepo; configure envs and CI skeleton
    • 1018.P1.2 Auth and tenant claim plumbing
      • Implement JWT claims enrichment; wire tenant resolution from subdomain/path; add middleware/guards
    • 1018.P1.3 Base schema and RLS skeleton
      • Create saas_organizations, saas_memberships, saas_audit_logs minimal tables and baseline RLS policies
    • 1018.P1.4 Admin onboarding flow (tenant create + first owner)
      • Minimal UI to create tenant, invite first admin, and sign in with tenant context

    Checklist:

    • Starter boots locally; CI checks run; lint/types/tests pass
    • Tenant resolution works; protected route requires tenant + role
    • Baseline saas_* tables migrated via Supabase migrations; RLS enabled and tested
    • Onboarding creates tenant and owner; session scoped to tenant

    Acceptance criteria:

    • App deploys to preview environment; login and tenant create flow demo works end-to-end
    • make db/reset and make db/check clean on schema; types regenerated if needed

    1018.P2 – Billing and Subscription Management ⏳

    • 1018.P2.1 Stripe setup and webhooks
      • Products/plans, seats, webhooks receiver; subscription state mirrored in saas_subscriptions
    • 1018.P2.2 Seat management and invitations
      • Invite/accept flows; role assignment; enforcement of seat limits in UI and RLS
    • 1018.P2.3 Billing portal and plan changes
      • Manage payment methods, invoices, plan upgrades/downgrades

    Checklist:

    • Webhooks verified locally (CLI) and in preview; retries handled idempotently
    • Seats reflected in membership constraints; role-upgrade/downgrade flows tested

    Acceptance criteria:

    • Subscription lifecycle (trial→active→canceled) reflected in app; seat enforcement proven
    • Audit log entries for key billing events

    1018.P3 – Multi-tenant RBAC and Admin Controls ⏳

    • 1018.P3.1 Roles and permissions matrix
      • Owner, admin, staff, viewer; database role mapping; UI guards
    • 1018.P3.2 Tenant-scoped settings and user management
      • Invite, deactivate, role change; tenant profile/settings
    • 1018.P3.3 Audit logging foundation
      • Insert triggers for saas_audit_logs; UI for recent activity

    Acceptance criteria:

    • RLS prevents cross-tenant access; permission matrix enforced at API and UI layers
    • Admin can manage users and roles within tenant; audit log entries visible

    1018.P4 – Donor Database MVP ⏳

    • 1018.P4.1 Data model and RLS
      • Tables for donors, attributes, indexing strategy, RLS per tenant
    • 1018.P4.2 CRUD + search UI
      • List, filter, sort; detail view; basic import/export if in scope

    Acceptance criteria:

    • E2E tests for create/view/update/search; RLS validated with multiple tenants

    1018.P5 – Sibling Groups and Family Trees (SaaS-positioned) MVP ⏳

    • 1018.P5.1 Data model, RLS, and relationships
    • 1018.P5.2 Basic UI for group creation, membership, and lineage visualization (SaaS copy and constraints)

    Acceptance criteria:

    • Multi-tenant isolation proven; e2e tests cover key flows

    1018.P6 – Analytics and Reporting Foundation ⏳

    • 1018.P6.1 Metrics definitions and warehouse export plan (if needed)
    • 1018.P6.2 Overview dashboards and downloadable reports (seed set)

    Acceptance criteria:

    • Admin sees basic operational metrics; export pipeline documented or implemented (scope-dependent)

    Testing & Quality Gates

    • Unit, integration, RLS, and e2e tests required at each phase before promotion
    • Security review on auth/RLS; accessibility checks on core UI screens
    • Database migrations via make db/* only; drift check must pass

    Acceptance for Project Completion

    • Production-ready SaaS portal with multi-tenant auth, billing, admin controls, and MVPs for donor DB and sibling groups
    • Audit logging and basic analytics live; documentation and runbooks updated

    Notes

    • This document inherits and depends on decisions in 1018.P0; it will be kept in sync with DR-1018-P0.

    Provenance