Project Master Plan

Last reviewed: 2025-02-17

Vision

Family Shapes empowers donor-conceived families, fertility clinics, and donor communities to build, explore, and steward rich relationship graphs. The platform focuses on:

• Trust – privacy controls, verified data, and secure communications.
• Clarity – intuitive visualizations that clarify complex family relationships.
• Community – tools that nurture connections between donors, families, and clinics.

Pillars & Success Criteria

1. Unified Data Model – A single source of truth for people, donors, organizations, and relationships.
2. Interactive Canvas – Fast, resilient visualizations with best-in-class layout options.
3. Operational Excellence – Repeatable workflows for migrations, deployments, and documentation.
4. Extensible Platform – Modular components and APIs that enable future integrations.

Stakeholders & Personas

Persona	Needs	Critical Journeys
Family Members	Discover relatives, manage trees, control privacy	Account onboarding → Tree exploration → Connection follow-up
Donors	Maintain accurate, policy-compliant profiles	Donor portal onboarding → Privacy & health updates
Clinics / Banks	Govern donor programs, ensure compliance	Org onboarding → Member management → Analytics & exports
Internal Team	Ship features safely, avoid drift	Planning → Implementation → QA/Release

Current Architecture Overview

• Frontend: React 18 + TypeScript, Vite build pipeline, Tailwind/shadcn UI.
• Visualization: XYFlow (React Flow) plus Dagre/ELK/Force layouts.
• Backend: Supabase (Postgres + Auth + Edge Functions).
• Automation Guardrails: .cursorrules, .zencoder/rules/, and AGENTS.md.

Refer to .zencoder/rules/architecture.md for a deeper structural breakdown and DOCS/README.md for detailed references.

Source of Truth Matrix

Domain	Authoritative Artifact	Notes
Database schema & security	supabase/migrations/	Enforced via Makefile, mirrored in .cursorrules
Frontend component library	src/components/ + design tokens	Document breaking changes in CHANGELOG.md
Documentation	DOCS/	Update README.md within this folder when new docs are added
Automation guardrails	.cursorrules, .zencoder/rules/	Keep aligned with AGENTS.md
Deployment	DEPLOYMENT.md + Netlify configs	Use release notes in CHANGELOG.md

Documentation Workflow

1. Update or add feature docs/implementation summaries in DOCS/.
2. Reflect major changes in CHANGELOG.md.
3. If the change impacts priorities, adjust ROADMAP.md.
4. Verify .cursorrules and .zencoder/rules/ point to the updated guidance.
5. At project kickoff, create a numbered planning doc under DOCS/PROJECTS/active/ using NNNN_slug.md; keep this file updated and move it across status folders as the project progresses. See DOCS/PROJECTS/README.md.

Release Cadence & Tracking

• Changelog: Maintain per release iteration (minimum monthly or when shipping major features).
• Roadmap Review: Revisit priorities bi-weekly; update status, owners, and dependencies.
• Retro Items: Capture lessons learned in the relevant implementation summary and link them in the changelog when impactful.

Quality Gates

• Automated tests (npm run test, Playwright) and manual checklists (see DONOR_PORTAL_TEST_CHECKLIST.md).
• Database workflow compliance (Makefile commands, drift checks).
• Documentation updates reviewed alongside feature PRs.

Pending Decisions & Follow-ups

Topic	Owner	Status
Analytics instrumentation strategy	Product/Engineering	Define event taxonomy post MVP analytics integration
Role-based dashboards	Product Design	UX exploration queued for future release
API partner integrations	Partnerships	Identify top 3 targets (Ancestry, 23andMe, clinics)

Program Numbering Scheme

• P1: Sharing/Permissions/Privacy (includes Audit [P1.1], Permissions UI [P1.2], Sharing Links [P1.3], Auth Path Consolidation [P1.4])
• P2: Three-Platform Architecture
• P3: Enhanced Donor Portal
• P4: Multi-tenant SaaS Platform
• P5: Mobile Applications
• P6: International Expansion
• P7: Canvas & UX Unification
• P8: Quality & Tooling (Migrations, Testing, Docs)
• P9: Analytics & Reporting
• P10: Integrations & Partner APIs
• P11: Community Hub
• P14: AI & Matching
• P15: Research Platform

Use these identifiers in ROADMAP entries, PR titles/descriptions, and changelog bullets for traceability (e.g., "P1.2: Implement collaborator panel").

Active Workstreams

Security/Sharing/Permissions/Privacy Audit (Frontend + Backend)

• Purpose: Create a definitive inventory and plan to rationalize existing sharing/permissions/privacy/visibility features and align with the family_tree_collaborators model and invitations.
• Scope:
  • Frontend UI audit: src/pages/Share.tsx, src/pages/FamilyTreeSettings.tsx (sharing tab), src/components/family-trees/SharingSettingsPanel.tsx, organization invite flows, privacy/settings pages, public viewers
  • Backend audit: RLS policies, family_tree_collaborators, family_tree_invitations, user_tree_access view, sharing links table and related edge functions (send-invitation, process-invitation, send-sharing-link)
  • Identify redundant or non-functional UI (e.g., /share dashboard page) and propose removal or consolidation
  • Map frontend-only features lacking backend support and backend-only features lacking UI
• Deliverables:
  • Inventory spreadsheet or markdown table linked from this doc
  • Deprecation/removal list with owners and PR links
  • Gap analysis with proposed tickets to complete alignment
• Timeline: 2 business days
• Owners: Architecture + Frontend + Backend

Contribution Expectations

• Align work items with roadmap entries before starting implementation.
• Update documentation and automation rules when process changes occur.
• Capture context in implementation summaries to maintain institutional knowledge.

When in doubt, start here, then dive into the roadmap and supporting documentation.