Docs
    Family Shapes + 1Updated May 7, 2026MD

    1018 – SaaS Portal Platform

    Markdown file

    ../PROJECTS/active/1018/1018_saas_portal_platform.md

    Executive Summary

    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

    • 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

    Dataset Preview

    • Raw CSV row/table content is available in the source artifact.