Note

    Family Shapes Changelog

    Chronological record of shipped changes and production incidents (including the documented RLS 403 collaborator insert issue).

    Source Summary

    --- title: Changelog description: Chronological list of notable changes to Family Shapes status: stable lastUpdated: 2025-10-02 15:28 ET owner: Engineering Team --- # Changelog All notable changes to the Family Shapes project will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.

    Imported Context

    title: Changelog description: Chronological list of notable changes to Family Shapes status: stable lastUpdated: 2025-10-02 15:28 ET owner: Engineering Team

    Changelog

    All notable changes to the Family Shapes project will be documented in this file.

    The format is based on Keep a Changelog.

    ℹ️ How to add entries: Use the helper scripts instead of manual timestamps.

    • Add a new entry interactively: npm run changelog:interactive
    • Add a new entry non-interactively: npm run changelog:add "Title" "Bullet 1" "Bullet 2"
    • Generate a header or timestamp if needed: npm run changelog:header / npm run changelog:timestamp
    • Keep entries in reverse-chronological order (newest entries at the top).
    <!-- NEW CHANGELOG ENTRIES START BELOW -->

    2025-10-30 11:00 ET - Documentation IA Cleanup: Flattened, Consolidated, Historical Split

    • Renamed DOCS/PROJECTS/archived → DOCS/PROJECTS/stale; updated references in DOCS/README.md and projects index.
    • Consolidated all database docs under DOCS/database/; updated AGENTS.md to link to DOCS/database/README.md as the single source of truth.
    • Flattened DOCS/development/ by moving nested features/, frontend/, performance/, and testing/ into a flat layout; removed those subfolders.
    • Introduced DOCS/historical/ and moved iteration/fix summaries there (XYFlow cleanup, connections summaries, performance/testing summaries, etc.); added a Historical section to DOCS/README.md.
    • Moved misfiled product docs into DOCS/features/ (e.g., CONTACT_FORM_IMPLEMENTATION.md, LAYOUT_FEATURES.md, ENHANCED_TENANT_MANAGEMENT.md).
    • Merged DOCS/contributing/agents.md into root AGENTS.md (now the single authoritative agent guide); flattened DOCS/contributing/documentation/ into DOCS/contributing/.
    • Removed DOCS/contributing/code-review.md; policy is now “Use PR reviews; no separate guide.” Updated references accordingly.
    • Corrected Getting Started: moved product page write-up to DOCS/historical/ and updated DOCS/getting-started/index.md for developer onboarding (env, run, DB setup, core links).
    • Deduplicated donor portal docs: kept DOCS/features/donor-portal.md; removed DOCS/features/DONOR_PORTAL.md.
    • Decided against a docs manifest for now; removed DOCS/_manifest.json and marked it optional in the plan.
    • Added project plan DOCS/PROJECTS/active/1017_docs_ia_cleanup.md to track the IA changes and next steps.

    Files/Dirs touched (high level): DOCS/README.md, AGENTS.md, DOCS/development/*, DOCS/database/*, DOCS/features/*, DOCS/contributing/*, DOCS/historical/*, DOCS/getting-started/index.md, DOCS/PROJECTS/README.md, DOCS/PROJECTS/stale/README.md, DOCS/PROJECTS/active/1017_docs_ia_cleanup.md.

    2025-10-03 16:15 ET - Environment Variables Fixed + Migration 0010 Deployed (RLS 403 Issue Persists)

    Problem: Production application experiencing persistent 403 Forbidden errors when attempting to insert records into family_tree_collaborators table, blocking collaborator management functionality.

    Actions Taken:

    1. ✅ Fixed Environment Variable Configuration:

      • Corrected .env.local to use Vite-required VITE_SUPABASE_URL and VITE_SUPABASE_ANON_KEY (previously used incorrect SUPABASE_* names)
      • Application was always hitting production due to fallback to hardcoded credentials in client.ts
      • Updated to point to production instance: https://nhkufibfwskdpzdjwirr.supabase.co

    2. ✅ Deployed Migration 0010 to Production:

      • File: supabase/migrations/20251003145104_0010_fix_collaborators_insert_policy.sql
      • Dropped and recreated INSERT policy on family_tree_collaborators to use has_tree_role() SECURITY DEFINER function
      • Updated UPDATE and DELETE policies to prevent RLS recursion
      • Added constraint preventing non-owners from adding/modifying owner roles
      • Applied via npx supabase db push

    3. ✅ Verified Migration Dependencies:

      • Confirmed has_tree_role() function exists in migration 0007 (already applied to production)
      • Function is marked as SECURITY DEFINER with STABLE volatility
      • Function queries family_tree_collaborators table to check user roles

    Current Status:

    • ⚠️ RLS 403 errors persist after migration deployment
    • 🔍 Root cause suspected: The has_tree_role() SECURITY DEFINER function may still be subject to RLS policies when it queries family_tree_collaborators, potentially causing recursion or access denial
    • 📋 Added to roadmap: See P1.2 bug tracking in ROADMAP.md

    Technical Details:

    • Environment: Production Supabase instance (nhkufibfwskdpzdjwirr.supabase.co)
    • Error: POST requests to /rest/v1/family_tree_collaborators return 403 Forbidden
    • RLS policies updated but issue not resolved
    • SECURITY DEFINER function exists but may not be bypassing RLS as intended

    Next Steps Required:

    1. Verify dev server was restarted after .env.local changes
    2. Capture exact error message from browser console or application logs
    3. Verify in Supabase Studio that policies were actually updated
    4. Check if user attempting to add collaborators has admin role on the tree
    5. Investigate whether SECURITY DEFINER function is properly bypassing RLS
    6. Consider alternative approaches to break RLS recursion cycle

    Files Modified:

    • .env.local - Corrected environment variable names and pointed to production
    • supabase/migrations/20251003145104_0010_fix_collaborators_insert_policy.sql - Deployed to production

    Reference:

    • Implementation guide: DOCS/PROJECTS/active/1001_family_tree_permissions.md
    • Related migrations: 0007 (function definitions), 0008 (previous RLS fix), 0010 (current attempt)

    2025-10-03 10:40 ET - Hotfix: RLS recursion fix + env/client updates

    • Fixed infinite recursion (42P17) in family_tree_collaborators RLS that caused 500s across the app:

      • Dropped recursive SELECT policy referencing family_trees/self
      • Added non-recursive self-row SELECT policy: "Users can view their collaborator rows"
      • Migration: supabase/migrations/20251003095021_0008_fix_rls_recursion.sql
      • Applied to remote via make db/push; make db/check → ✅ No drift

    • Supabase client now reads env vars for runtime configuration:

      • Updated src/integrations/supabase/client.ts to use import.meta.env.VITE_SUPABASE_URL and import.meta.env.VITE_SUPABASE_ANON_KEY (with safe fallbacks)

    • Local development environment upgrades:

      • Upgraded Supabase CLI to v2.48.3 (installed prebuilt binary in .bin/)
      • Restarted local stack; services healthy (supabase start shows all endpoints)
      • Updated supabase/config.toml auth redirects to include http://localhost:8080, http://127.0.0.1:8080

    • Smoke tests:

      • Sign-in working (remote and local)
      • Family Trees, People, Connections load without 500s

    • Next actions:

      • P1.2 Permissions UI completion (collaborator management UI + gating)
      • P1.1 audit cleanup (remove Share.tsx, rename SharingSettingsPanel → SharingLinksPanel, add invitation acceptance route)
      • P1.3 Sharing Links persistence

    2025-10-02 18:30 ET - P1.2 Permissions UI: services/hooks/UI integration

    Progress toward P1.2 with initial UI and enforcement:

    • Added service: src/services/familyTreeCollaborators.ts (collaborators + invitations CRUD, role checks)
    • Added hooks: src/hooks/useTreePermissions.ts, src/hooks/useCollaborators.ts, src/hooks/useInvitations.ts
    • Added UI: src/components/family-trees/CollaboratorPanel.tsx
    • Added route/page: src/pages/TreeInvitationAcceptPage.tsx and route in src/App.tsx
    • Gated editing in src/pages/FamilyTreeDetail.tsx via useTreePermissions (readOnly respected in visualization + managers)
    • Added unit test: tests/unit-tests/services/familyTreeCollaborators.test.ts for permission hierarchy
    • Updated docs: DOCS/PROJECTS/active/1001_family_tree_permissions.md to reflect partial UI + integration

    Next: expand tests (unit + E2E), finalize collaborator management UX, and complete gating across all editors.

    2025-10-02 17:00 ET - Family Tree Permissions Database Migration Deployed

    This entry documents the creation and local testing of the database migration for the family tree permissions system, which is the #1 immediate priority from the roadmap. The migration fixes the fundamental issue where family_tree_members incorrectly used person_id instead of user_id, preventing proper user-based access control.

    Database Changes (Migration 0007)

    • ✅ Created family_tree_collaborators table:

      • Tracks authenticated users (via user_id) with roles: owner, admin, editor, viewer
      • Enforces one role per user per tree with unique constraint
      • Includes audit fields: added_by, created_at, updated_at

    • ✅ Created family_tree_invitations table:

      • Manages invitation workflow with token-based acceptance
      • Tracks invitation status: pending, accepted, declined, expired, cancelled
      • 7-day expiration by default
      • Links to inviter, invitee email, and optional invitee_user_id

    • ✅ Data Migration:

      • Migrated all existing tree owners from family_trees.user_id to family_tree_collaborators with 'owner' role
      • Created backup table: family_tree_members_backup
      • Preserved family_tree_members table for backward compatibility (tracks which persons are depicted in trees)

    • ✅ Helper Functions:

      • has_tree_role(tree_id, user_id, required_role): Checks if user has specific role or higher
      • has_sharing_link_access(tree_id, link_token): Validates sharing link access
      • accept_tree_invitation(invitation_token): Accepts invitation and creates collaborator record

    • ✅ Updated RLS Policies:

      • family_trees: Role-based SELECT/UPDATE/DELETE (viewers can read, editors+ can update, only owners can delete)
      • family_tree_collaborators: Owners/admins can manage collaborators (cannot add/modify/remove owner role)
      • family_tree_invitations: Inviters and tree admins can manage invitations
      • persons: Users can view/edit persons in trees they have access to (respects collaborator roles)
      • connections: Similar role-based access control

    • ✅ Created user_tree_access view: Convenient view showing all trees with user's role and tree metadata

    Technical Fixes

    • ✅ Fixed ES module error in scripts/create-migration.js:

      • Converted from CommonJS (require, module.exports) to ES modules (import, export)
      • Added ES module equivalents for __dirname and __filename
      • Script now works correctly with "type": "module" in package.json

    • ✅ Fixed migration timestamp:

      • Old (incorrect): 20250102000000 (January 2025 - would run before baseline)
      • New (correct): 20251002162313 (October 2025 - runs after all existing migrations)

    • ✅ Fixed schema references:

      • Corrected persons table policies to use user_id instead of non-existent created_by column

    Testing

    • ✅ Migration tested locally with make db/reset - all migrations applied successfully
    • ✅ Schema drift check passed with make db/diff - no unexpected changes
    • ✅ TypeScript types regenerated with make db/types

    Deployment

    Deployed to production via make db/push; make db/check reports ✅ No drift. UI work will follow to expose collaborator management and enforce roles in the editor (see DOCS/PROJECTS/active/1001_family_tree_permissions.md).

    Reference Documentation

    • Migration file: supabase/migrations/20251002162313_0007_fix_family_tree_permissions.sql
    • Implementation guide: DOCS/PROJECTS/active/1001_family_tree_permissions.md (single source of truth)
    • Roadmap: ROADMAP.md (updated with accurate status)

    Documentation Cleanup

    • ✅ Consolidated three overlapping docs into single implementation guide
    • ✅ Deleted DOCS/HANDOFF_PERMISSIONS_UI.md (redundant)
    • ✅ Moved DOCS/archived/WIP_DATABASE_ARCHITECTURE_ANALYSIS.md to archived (discovery phase complete)

    ...[truncated for intake]

    Provenance

    domain:builderdomain:entrepreneurchangelog