Guided Onboarding & Organization Setup

After a user registers, they must either join an existing church organization or provision a new one before they can access operational features.

---

1. Onboarding Paths

Upon reaching the /welcome route, users are presented with two primary actions:

Path A: Create a New Organization

Used by pastors or administrative leaders setting up the platform for their parish.

• Input parameters: Church Name, City, State, Contact Email, Contact Phone, and Organization Type ('church' or 'diocese').
• Database Execution: The client executes the RPC create_organization_with_admin.
• System Initialization:
  1. Inserts a new record into public.organizations.
  2. Generates a unique 8-character join_code via database trigger (generate_org_join_code).
  3. Inserts default platform roles (Admin, Member) via the trigger trg_seed_church_roles.
  4. Associates the creator’s profile with the new organization (profiles.organization_id = org_id).
  5. Grants the user the system Admin role in public.user_church_roles.

Path B: Join an Existing Organization

Used by church members, volunteers, and servants to register under their local parish.

• Input parameter: Unique 8-character join_code (e.g., A3F9B2C7).
• Verification: The system checks if an organization exists with a matching join_code.
• Submission: If verified, the client inserts a request into public.join_requests containing the user’s ID, organization ID, contact phone, and optional signup form answers (form_data JSONB).

---

2. Join Requests Flow (join_requests)

When a user submits a join request, they are placed in a holding pattern.

[User Submits Join Request]
             │
             ▼
    [Status: 'pending'] ◄─── (User sees "Pending Approval" loading screen)
             │
      (Church Admin Reviews)
             ├──────────────────────────┐
             ▼ (Approve)                ▼ (Reject)
    [Status: 'approved']       [Status: 'rejected']
             │                          │
    * Link profiles.org_id      * Remains disconnected
    * Grant default 'member'    * User can re-try
      church role

Review Logic

• Admin Visibility: Requests are displayed in the Church Settings panel under Pending Invites & Requests. Admins can view submitted names, phone numbers, and message content.
• Approval Processing:
  • The admin approves the request.
  • The system updates join_requests.status = 'approved'.
  • The system updates the applicant’s profiles.organization_id to match the church ID.
  • The applicant is assigned the default 'member' role inside user_church_roles.
• Rejection Processing:
  • The admin rejects the request.
  • The status is updated to 'rejected'. The user is informed and can apply to a different church using another code.