Family Groups

Family Groups lets you share finances with family, roommates, or friends. Create a group, invite members via iCloud, and collaborate on shared budgets and split expenses — all while keeping your personal financial data private.

Manage all your shared finance groups from a single list. Role badges indicate your relationship to each group.

Overview

Family Groups is built on top of Apple’s CloudKit sharing infrastructure. Each group creates a dedicated CloudKit zone where shared data (budgets, expenses, settlements) lives. Your personal accounts, transactions, and balances are never shared — only data you explicitly contribute to the group is visible to other members.

Key concepts:

• Groups: A named container for shared financial collaboration (e.g., “Smith Family”, “Roommates”).
• Memberships: Each user’s relationship to a group, tracked locally via SwiftData. Includes role, display name, and join date.
• Roles: Owner/Parent, Adult, or Minor — each with different permissions.
• Family Dashboard: A dedicated hub for managing your family’s finances, with sections for joint accounts, children, budgets, and expenses.
• Joint Accounts: Share an existing personal account with your partner so both can view its balance and transactions.
• Child Oversight: Parents can set spending limits, configure allowances, and grant account access to minor members.
• Shared Budgets: Group-wide spending limits tracked by category.
• Split Expenses: Divide costs among group members using equal, percentage, or custom splits.
• Settlements: Track who owes whom and mark debts as paid.
• Coaching Messages: Parents can send encouraging financial guidance messages to family members.

Groups support up to 10 members by default.

Creating a Group

Any Coincert user with an active iCloud account can create a group.

Steps:

1. Navigate to Groups (iOS) or Settings > Groups (macOS).
2. Tap the + button or Create Your First Group if no groups exist yet.
3. Enter a group name (1—50 characters). Examples: “Smith Family”, “Apartment 4B”.
4. Tap Create.

Creating a new group. The name is visible to all members you invite.

What happens behind the scenes:

1. Coincert creates a FamilyGroup record and a GroupMembership record with the owner role.
2. A dedicated CloudKit zone (Group-<UUID>) is created in your private iCloud database.
3. A CKShare is created with publicPermission = .none (private by default).
4. Your iCloud display name is fetched and set as your member display name (if available).
5. Both records are queued for sync via Harmony Sync.

If CloudKit share creation fails (network error, iCloud not signed in, schema not deployed), the local records are rolled back automatically. You will see a specific error message explaining the cause.

Family Dashboard

Once you belong to a family group, the Family tab shows a dedicated dashboard for managing shared finances.

Accessing the Dashboard

iPhone iPad: Navigate to More > Family in the tab bar.

Mac: Select Family in the sidebar.

Empty State

If you are not a member of any group, the Family tab shows:

• A person.3.fill icon with “Family Finance” title and “Manage finances together” subtitle.
• A prominent Create Family button.
• A “Have an invite?” helper text directing you to accept invitations from notifications or links.

Dashboard Sections

When you have an active group, the dashboard displays the following sections based on your role:

Each section uses card-style navigation with clear icons and chevron indicators.

Inviting Members

Only the group owner can invite new members. Coincert offers two invite flows with different security trade-offs.

Dual Invite Flow

When the owner taps Invite Members, a confirmation dialog presents two options:

Share Invite Link iPhone Mac

The share link flow works on both platforms but uses platform-native sharing UI:

• iOS: Opens UIActivityViewController (standard share sheet) with the CKShare URL.
• macOS: Opens NSSharingServicePicker or copies the link to the clipboard via a dedicated “Copy Link” button.

The share URL is a standard CloudKit share link. When a recipient taps it, Coincert’s handleShareURL method:

1. Fetches the share metadata from iCloud.
2. Accepts the share.
3. Reads the group ID and name from the root record.
4. Determines the member’s role from their CKShare participant permission (readWrite = Adult, readOnly = Minor).
5. Creates a local GroupMembership record.
6. Adds the shared zone to SharedSyncEngine and triggers an initial sync.

Secure Invite (iCloud) iPhone

The secure invite flow uses UICloudSharingController, which is iOS-only. This presents Apple’s native participant management UI where the owner can:

• Add specific iCloud accounts by name, email, or phone number.
• Set per-participant permissions (Read & Write or Read Only).
• View and manage existing participants.

This method does not upgrade the CKShare’s public permission, so even if the share URL leaks, unauthorized users cannot join.

Choose between a shareable link (convenient) or a secure iCloud invite (restrictive).

Participant Status

Each group member has a role (local to Coincert) and an acceptance status (from CloudKit).

Roles

Roles are displayed as colored capsule badges throughout the UI. The owner can change a member’s role between Adult and Minor via the role change sheet (accessible from the members list context menu or swipe actions).

Acceptance Status

Participant acceptance status is fetched live from the CKShare and displayed as status badges next to non-owner members:

The owner can view all participant statuses. On macOS, the group detail view shows an “Invite Status” section listing each participant with their acceptance badge.

Contact Linking

Group members appear by their iCloud display name or a custom display name by default. Contact Linking lets you associate a group member with one of your local Contacts, replacing their name and avatar with the contact’s information.

How It Works

1. Long-press (context menu) on a member in the Members list.
2. Select Link to Contact.
3. A privacy notice explains that the link is stored locally only — never shared with other members or synced to iCloud.
4. Tap Continue to open the contact picker.
5. Select a contact. Their name and thumbnail photo are now displayed for that member.

Members list with contact-linked photos, role badges, and acceptance status indicators.

Technical Details

• Contact linking uses CNContactPickerViewController, which grants per-contact access without prompting for full Contacts permission.
• The linked contact’s identifier (CNContact.identifier) is stored in GroupMembership.linkedContactID.
• ContactsLinkingService fetches display names and thumbnail photos on demand, with an in-memory NSCache (50 items, auto-evicts under memory pressure).
• Contact data is never synced to iCloud — the linkedContactID is a local-only field.
• Display name priority: Contact name > custom display name > iCloud name > “Member” fallback.

What You Can Do

• Owner: Can link any non-owner member to a contact, edit display names, and change roles.
• Any member: Can link themselves to a contact and edit their own display name.
• Swipe left on a member row to access quick actions (Edit Name, Remove).

Shared Budgets

Shared Budgets let the group track collective spending against a limit. Only the group owner can create shared budgets; all members can view them.

Creating a Shared Budget

1. Open a group and navigate to Shared Budgets.
2. Tap the + button (owner only).
3. Fill in the budget details:
   • Name: A descriptive name (e.g., “Groceries”, “Household Expenses”).
   • Spending Limit: The maximum amount for the budget period.
   • Period: Weekly, Monthly, or Yearly.
   • Categories: Select one or more expense categories to track. Only non-income categories are shown.
4. Tap Create.

Track group spending against shared budget limits with visual progress gauges.

Viewing Budget Progress

Each shared budget row shows:

• Budget name and period badge (Weekly / Monthly / Yearly).
• A circular gauge showing progress toward the limit.
• Spent amount vs. limit, with red highlighting when over budget.
• Drill into a budget to see individual expenses contributing to it.

Budget progress is calculated by SharedExpenseService, which aggregates all shared expenses in the group that match the budget’s category IDs.

Split Expenses

Split Expenses lets you divide costs among group members. You can split a new manual expense or tag an existing transaction from your accounts.

Split Methods

Creating a Split Expense

1. Open a group and tap Split Expense in the Shared Expenses section.
2. Enter the expense description and amount (or these are pre-filled if splitting an existing transaction).
3. Optionally select a category.
4. Choose a split method (Equal, Percentage, or Custom).
5. Adjust member shares if using Percentage or Custom.
6. Tap Split.

The expense is created as a SharedExpense record with individual splits tracking each member’s share and payment status.

Settlement

The Settlement view shows the net balance for each group member:

• Green (“is owed $X”): This member has paid more than their share.
• Orange (“owes $X”): This member still owes money.
• Settled: All debts are resolved.

Members can be marked as settled with the Settle Up button. A Send Reminder option is available to nudge members (reminders are in-app only).

Actual money transfers happen outside Coincert (via Venmo, cash, bank transfer, etc.). Coincert tracks the accounting, not the payment.

Joint Accounts

Joint Accounts let parents share an existing personal account with their partner within the family group. Both parents get visibility into the account’s balance and transactions.

Designating a Joint Account

1. From the Family Dashboard, find the Joint Accounts section (parent role required).
2. Tap the + button to open the designation flow.
3. Select one of your personal accounts from the list. Accounts already designated as joint are excluded.
4. Confirm sharing. The confirmation dialog explains that both you and your partner will have full read/write access, and that revoking joint access later requires mutual consent.
5. The account appears in the Joint Accounts section for both parents.

Joint Account Detail

Tap a joint account to view its details:

• Account name, type, and current balance.
• Permission level (Read Only or Read/Write).
• Grant date.
• Transaction list for the account.

Permissions

Mutual Consent

When requiresMutualConsent is enabled on a grant, both parents must agree before the joint access can be revoked. This prevents one partner from unilaterally removing access to shared finances.

Joint Account Sync

Joint account grants sync via CloudKit to the family group’s shared zone. When one parent designates a joint account, it appears on the other parent’s device after sync.

Child Oversight

Parents can supervise and guide children’s financial activities. The Child Oversight tools are available from the Children section of the Family Dashboard.

Child Overview

Tap a child member card on the dashboard to open their overview. The Child Overview screen shows:

• Header: Child’s display name and role badge.
• Accounts: Account access grants for this child.
• Spending: Current period spending total with active spending limits and progress gauges.
• Allowances: Configured allowance rules with amount and frequency.
• Coaching: Quick access to send coaching messages to this child.
• Role Promotion: If the child has requested a role change, it appears here for parent approval.

Three quick action buttons are available: Set Spending Limit, Set Up Allowance, and Grant Account Access.

Spending Limits

Parents can set spending limits for children to help them learn financial discipline.

Creating a spending limit:

1. From the Child Overview, tap Set Spending Limit.
2. Enter the limit amount (e.g., $200).
3. Select a period: Weekly, Biweekly, or Monthly.
4. Optionally select specific categories. If no categories are selected, the limit applies to all spending.
5. Configure alert thresholds:
   • 80% warning — notification when the child approaches the limit.
   • 100% reached — notification when the limit is hit.
   • Over budget — notification when spending exceeds the limit.
6. Tap Save.

The spending limit is created as a SharedBudget assigned to the child via assignedMemberID. If alerts are enabled and notification permission has not been granted, you will be prompted to allow notifications.

Alert behavior:

Each threshold fires only once per budget period. When the period resets, threshold tracking is cleared and alerts can fire again. Notifications use the CHILD_SPENDING_ALERT category.

• Title: “[Child] at [X]% of [Budget Name]”
• Body: “$XX.XX of $YY.YY spent”

Allowances

Parents can set up recurring allowances for children.

Creating an allowance:

1. From the Child Overview, tap Set Up Allowance.
2. Enter the allowance amount.
3. Select a frequency: Weekly, Biweekly, or Monthly.
4. Choose a delivery method:
   • Recurring Transaction: Creates a transaction in a selected account on each allowance date. You must choose which account receives the deposit.
   • Budget Allocation: Sets a spending cap for the child without creating transactions.
5. Add optional notes (e.g., “For school lunches”).
6. Tap Save.

Editing an allowance:

Tap an existing allowance in the Child Overview. The form is pre-populated with current values. The navigation title shows “Edit Allowance” instead of “Set Up Allowance.”

Validation:

• Amount must be greater than zero.
• For Recurring Transaction delivery, an account must be selected.

Account Access

Parents can grant children read-only access to specific accounts so they can view balances and transactions.

1. From the Child Overview, grant access to a checking or savings account.
2. Set the permission to Read Only.
3. The child can see the account in their view but cannot modify it.

Account access is tracked via ChildAccountAccess records that sync to the family group’s shared zone.

Coaching Messages

Parents can send encouraging financial guidance messages to family members. Coaching is designed to be supportive rather than punitive.

Sending a Coaching Message iPhone

1. From the Family Dashboard > Family Settings, tap Coaching.
2. Select a recipient from eligible group members.
3. Write your message in the text area.
4. On iOS 26+, the message is automatically softened using on-device AI (Foundation Models) to ensure a supportive tone. On earlier iOS versions, messages are sent with minimal softening and a banner explains that AI tone adjustment is unavailable.
5. Tap Send.

Coaching compose includes frequency guardrails — if you send too many messages in a short period, a nudge alert appears suggesting you space out your coaching.

Muting Coaching

Adult members can mute coaching from specific senders:

1. Navigate to your group settings.
2. Toggle coaching mute for any sender.
3. Messages from muted senders no longer appear.

The mute state is stored in the GroupMembership.coachingMuted field and persists across sessions.

Minor Coaching Restrictions

Parents can restrict who may send coaching to a minor child:

• Enable Restrict Minor Coaching in the child’s membership settings.
• When enabled, only the group owner can send coaching to that child.
• Other adult members’ coaching is blocked.

Managing Members

Editing Display Names

Any member can edit their own display name. The owner can edit any non-owner member’s name. Display names are visible to all group members and synced via Harmony Sync.

• Swipe left on a member row and tap Edit Name.
• Or long-press and select Edit Name from the context menu.

Changing Roles

The owner can change a member’s role between Adult and Minor:

1. Long-press the member and select Change Role.
2. Choose between Adult and Minor using the segmented control.
3. If changing to Minor, a transparency notice appears: the owner will be able to see the minor’s spending activity.
4. Tap Save.

Role changes update both the local GroupMembership and the CKShare participant permission (readWrite for Adult, readOnly for Minor).

Removing Members

The owner can remove any non-owner member:

1. Swipe left on the member and tap Remove, or long-press and select Remove Member.
2. Confirm the removal. The member loses access to the group.
3. Their shared expense history is preserved (soft delete — isActive = false).
4. The member is also removed from the CKShare in CloudKit.

Leaving a Group

Non-owner members can leave a group:

• iOS: Swipe left on the group in the group list and tap Leave.
• macOS: Open the group detail and click Leave Group, then confirm.

Leaving marks your membership as inactive and removes the shared zone from your sync engine. Your personal data is unaffected.

Archiving a Group (Owner Only)

Owners cannot “leave” — they can archive the group instead:

• iOS: Swipe left on the group in the group list and tap Archive.
• macOS: Click Archive Group in the group detail view and confirm.

Archiving hides the group from your list. Shared data remains accessible to other members. CloudKit ownership cannot be transferred — if a new owner is needed, a new group must be created.

Platform Differences

Family Groups is available on both iOS and macOS, with platform-specific presentation styles.

Most family features now work on both platforms. Coaching messages remain iOS-only due to reliance on Foundation Models (iOS 26+). The Secure iCloud invite flow is iOS-only due to UICloudSharingController.

Privacy & Security

Family Groups is designed with the same privacy-first philosophy as the rest of Coincert.

Data Isolation

• Personal data stays personal. Your accounts, transactions, balances, and categories are never shared with a group. Only data you explicitly create in the shared context (shared budgets, split expenses) enters the group’s CloudKit zone.
• Category sharing is opt-in. The Sharing Settings screen lets you toggle which spending categories are visible in shared budgets. Individual transactions within shared categories remain private — only aggregate spending is visible.

iCloud-Based Sharing

• All group data syncs through Apple’s CloudKit private database using CKShare.
• Each group has its own dedicated CloudKit zone (Group-<UUID>), isolated from your personal sync zone.
• Share references are stored as lightweight Codable structs (not NSKeyedArchiver, which corrupts encrypted values).
• The CKShare’s publicPermission defaults to .none. It is only upgraded to .readWrite if the owner explicitly chooses the Share Link invite flow.

Contact Linking Privacy

• Linked contact identifiers are stored locally only in GroupMembership.linkedContactID.
• Contact data (names, photos) is never synced to iCloud or shared with other group members.
• CNContactPickerViewController grants per-contact access without requiring full Contacts authorization.
• A privacy notice is shown before every contact linking action.

Encrypted Fields

Financial amounts, descriptions, and member names within shared CloudKit records use CloudKit’s encryptedValues container. UUIDs and booleans remain unencrypted to support server-side querying.

Soft Deletes

Removing a member or leaving a group uses soft deletion (isActive = false). No user data is hard-deleted, preserving audit trails and allowing potential restoration.

Minor Transparency

When a member is assigned the Minor role, the owner can view their spending activity. Minors are informed of this transparency when accepting the invitation. Adults in the group cannot access minor activity — only the owner can.

Privacy & Safety Settings

For users who need to manage or disconnect shared access, Coincert provides a Privacy & Safety screen in Settings. This screen uses intentionally generic language and provides:

• Account Privacy: Biometric lock and balance hiding options.
• Data Protection: End-to-end encryption status and transaction history CSV export.
• Shared Access: View joint accounts and disconnect shared access (one-sided separation). Disconnecting preserves your personal accounts and transaction history. The other party receives no notification about the disconnection.
• Resources: Confidential support hotline (1-800-799-7233), technology safety resources, and safety planning guides.

For complete details, see the Privacy & Safety section in Settings.

One-Sided Separation

The disconnection mechanism in Privacy & Safety is designed for safety:

• Separation is local-only — it is never synced to iCloud or shared with other members.
• The other party receives no notification and still sees the group (the separated member may show as inactive).
• Joint account grants are revoked and revert to personal accounts.
• Personal data (accounts, transactions, history) is fully preserved.
• The separation state is stored only on the separating user’s device.

Error Handling

Common errors and their resolutions: