Operational Manual

ChurchScore Live
How-To Guide

A detailed reference for setup, daily operations, imports, sync, reporting, and troubleshooting — built directly from the app's current code behavior.

Contents
1App Overview & Concepts 2Members Tab 3Member Detail Screen 4Reports Tab 5Points Tab 6Settings 7Live Sync 8Import Guide 9Workflows 10Troubleshooting 11Admin Checklist
Section 1

App Overview & Core Concepts

ChurchScore is a SwiftUI iOS application for tracking church members, assigning them to classes, awarding points for activities, viewing individual member progress, importing data, and generating reports. The main app opens to a splash screen and then shows four tabs.

🏫
Classes
Group labels like Youth, Adults, Men, Women, Choir. Used in rosters, point-awarding, and reports.
👤
Members
Each member has a unique ID, name, class assignment, and an optional local profile photo.
⭐
Actions
Activities that earn points — Attendance, Bible verse, Inviting a guest. Each has a name and point value.
📋
Point Records
Created when points are awarded. Stores member ID, action ID, point value, and date awarded.
🏅
Tiers
Milestone labels like Bronze, Silver, Gold. Each tier has a point threshold. Members earn the highest tier they qualify for.

Startup Behavior

When the app launches, these steps happen in order:

  1. 1A splash screen appears for approximately 2.5 seconds.
  2. 2If Server Mode is enabled, the app attempts to connect to the configured sync server.
  3. 3If a server URL is configured, the app triggers a full sync pull from the server.
  4. 4The main tab view opens. A synced installation may refresh its local database shortly after launch.
Section 2

Members Tab

The Members tab is the roster view. It shows all members for the currently selected class with their lifetime point totals.

What You See

  • A class picker at the top
  • A list of members in the selected class
  • Each member's lifetime point total shown as X pts
  • Members are sorted alphabetically by name

How to Filter the Roster

  1. 1Open the Members tab.
  2. 2Tap the class picker at the top.
  3. 3Choose a class. The list refreshes immediately.
ℹ️
The roster filters by one exact class at a time. Lifetime points are calculated by summing all point records for that member across all time.
Section 3

Member Detail Screen

Tap any member in the roster to open that member's full detail page.

What the Detail Screen Shows

  • Member name and current tier
  • Profile photo (tap to change)
  • Current class and class change control
  • Last month attendance — unique days with point entries, not the number of records
  • Lifetime points — sum of all point records for this member

How Tier Is Determined

  1. 1The app loads all tiers and sorts them from highest threshold to lowest.
  2. 2It picks the first tier whose threshold is less than or equal to the member's lifetime points.
  3. 3If no threshold is met, the tier display shows "None".

How to Change a Member's Class

  1. 1Open the member detail page.
  2. 2Tap the Change Class To menu.
  3. 3Select a new class. The change is written locally and synced to the server.

How to Add or Change a Profile Photo

  1. 1Open the member detail page.
  2. 2Tap the circular profile image.
  3. 3Choose or capture an image. Editing is enabled in the picker.
  4. 4Close the picker. The app saves the image as a JPEG. If a server is connected, the photo syncs to the server and other iPads.
✅
Photo sync: When Server Mode is enabled, photos uploaded on one iPad are automatically broadcast to all other connected iPads and stored in the server's photos/ folder.
Section 4

Reports Tab

The Reports tab provides two modes: quick template reports and a fully custom report builder.

Quick Template Reports

Available templates with their date ranges (calculated from the current calendar year):

TemplateDate Range
MonthlyOne month ago through today
Q1January 1 – March 31
Q2April 1 – June 30
Q3July 1 – September 30
Q4October 1 – December 31

What a Generated Report Contains

Reports are grouped by member and show total points for the period plus dated activity lines. Example:

Jane Smith - 45 pts
  Apr 10, 2026 - Attendance: 10
  Apr 17, 2026 - Bible Verse: 15
  Apr 24, 2026 - Memory Verse: 20

Class Summary Report

Tap Quick Generate Class Summary to see total points grouped by class, sorted highest to lowest.

Class Summary Report

Youth   – 820 pts
Adults  – 675 pts
Choir   – 310 pts

Custom Report Builder

  1. 1Choose PDF or CSV export format.
  2. 2Set a start date and end date.
  3. 3Tap member chips to include only specific members, or leave all unselected for all members.
  4. 4Tap action chips to filter by specific actions, or leave all unselected.
  5. 5Tap Generate Custom Report. The iOS share sheet opens for AirDrop, email, or Files.
⚠️
CSV export note: The current CSV export writes the same text report to a .csv file. It is not a structured row-by-row spreadsheet. The content is identical to the on-screen text report.
Section 5

Points Tab

The Points tab is the primary data-entry screen used during or after a service. It provides a grid interface for awarding points to multiple members at once.

How to Award Points

  1. 1Open the Points tab.
  2. 2Select a class from the class picker. Members in that class appear as rows; actions appear as columns.
  3. 3Check the boxes for each member/action combination you want to award.
  4. 4Tap Submit. All checked combinations are recorded at once with today's date.
💡
No classes showing? You must add at least one class in Settings before the Points tab can display anything. See Settings: Classes below.

How Submitted Points Are Stored

For each checked member/action combination, the app creates one point record containing the member ID, action ID, the action's point value, and the current date and time. In Server Mode, each record is also emitted as a sync event to all connected iPads instantly.

Section 6

Settings

The Settings tab is where all administrative management happens. It is divided into sections: Sync Mode, Live Sync, Classes, Members, Actions, Tiers, and Import.

Sync Mode Toggle

At the top of Settings is a toggle between Local Only Mode and Server Mode.

ModeBehavior
Local OnlyAll data stays on this iPad. No network activity. No server required.
Server ModeAll writes sync to the server and broadcast to other iPads in real time. Switching on triggers a full sync.

Classes

  • View all classes in a scrollable list
  • Add a class: enter a name and tap Add Class
  • Edit a class name: tap Edit on the row, change the name, tap Save
  • Delete a class: swipe left on the row
ℹ️
Classes must be created before members can be added. Deleting a class does not delete its members — they remain in the database with their old class name.

Members

  • View all members with their class assignment
  • Add a member: enter a name, choose a class, tap Add Member
  • Edit a member's name: tap Edit, change the name, tap Save
  • Delete a member: swipe left
  • Move a member to a different class: open their detail page and use the class change menu

Actions

  • View all actions with their point values
  • Add an action: enter a name and point value, tap Add Action
  • Edit an action: tap Edit, change name or points, tap Save
  • Delete an action: swipe left

Tiers

  • View all tiers with their point thresholds
  • Add a tier: enter a name and minimum point threshold, tap Add Tier
  • Edit a tier: tap Edit, change name or threshold, tap Save
  • Delete a tier: swipe left
💡
Best practice: create tiers from lowest threshold to highest for easier review. The app internally sorts them when deciding a member's current tier.
Section 7

Live Sync

When Server Mode is enabled, ChurchScore connects to your self-hosted server over Tailscale and syncs changes in real time.

Connection States

StatusMeaningAction
ConnectedServer is reachable. Changes sync instantly.None needed
ConnectingApp is attempting to establish connection.Wait a moment
OfflineServer unreachable. Changes are queued locally.Check server / Tailscale
DisconnectedNot attempting to connect.Tap Connect or check URL

Offline Queue

If the app loses connection mid-session, all changes are saved locally and queued. When the connection is restored, the queue is automatically flushed in order. The Settings screen shows how many changes are pending.

Pull Full Sync from Server

Use this button in Settings → Live Sync when an iPad is missing data. It downloads the entire server database state and merges it with local data. Safe to run at any time — existing local data is not wiped.

How to Configure the Server URL

  1. 1Go to Settings and enable Server Mode.
  2. 2In the Live Sync section, tap Edit next to Server URL.
  3. 3Enter your server's Tailscale IP: ws://100.x.x.x:8080
  4. 4Tap Save. The app connects automatically.
Section 8

Import Guide

Settings → Import supports both .csv and .xlsx files. The importer detects what to load based on file structure and sheet names.

CSV Import Rules

CSV files are detected by their header row. The app checks which columns are present and treats the file accordingly.

Members CSV

Required headers: name and class

name,class
Jane Smith,Youth
Michael Brown,Adults
Sarah Jones,Choir

Actions CSV

Required headers: name and points

name,points
Attendance,10
Bible Verse,15
Invite a Guest,20

Tiers CSV

Required headers: name and threshold

name,threshold
Bronze,100
Silver,250
Gold,500

Excel Import Rules

Excel import is sheet-based. The app loops through all worksheets and checks each sheet name. The sheet name must contain one of the recognized keywords.

Sheet Name ContainsRequired HeadersWhat Gets Imported
membername, class, action, points, dateMembers + historical point records
actionname, pointsActions only
tiername, thresholdTiers only

Members Sheet Layout

Name | Class | Action | Points | Date
Jane Smith | Youth | Attendance | 10 | 2026-04-13T00:00:00Z
Jane Smith | Youth | Bible Verse | 15 | 2026-04-13T00:00:00Z
Michael Brown | Adults | Attendance | 10 | 04/13/2026

Supported date formats: ISO 8601 (e.g. 2026-04-13T00:00:00Z) and MM/dd/yyyy (e.g. 04/13/2026).

Critical Import Caveats

⚠️
Excel member import is a member + history import. There is no simple Excel member-only sheet. If you use Excel for members, the importer expects all five columns including action, points, and date.
⚠️
Repeated members create duplicates. The importer calls addMember for every row. If the same person appears on multiple rows, multiple member entries can be created with the same name.
⚠️
Imported Excel history uses new action IDs. Historical point records from Excel use a newly generated action ID instead of matching an existing action by name. Reports may not always resolve the action label for those historical entries.
⚠️
Unrecognized sheet names trigger a warning. Extra sheets in the workbook whose names do not contain member, action, or tier will cause the importer to display a warning message.

Best Practice Import Strategy

  1. 1Import or create actions first.
  2. 2Import or create tiers next.
  3. 3Use CSV for simple member imports when you do not need historical point rows.
  4. 4Use Excel only when you need all three recognized worksheet types with exact headers.
  5. 5Avoid repeated member names on Excel member-history sheets unless you plan to clean up duplicates.
  6. 6After any import, verify the roster in the Members tab immediately.
Section 9

Recommended Workflows

First-Time Setup Workflow

For a new installation, follow this order for the cleanest results:

  1. 1Open Settings. Configure Sync Mode and server URL if using multiple iPads.
  2. 2Add or import classes.
  3. 3Add or import actions with their point values.
  4. 4Add or import tiers with their thresholds.
  5. 5Add or import members assigned to classes.
  6. 6Open the Members tab and verify roster data by class.
  7. 7Award a few test points to confirm the grid is working.
  8. 8Check a member detail page for tier and stats accuracy.
  9. 9Generate a quick report to confirm records are appearing correctly.

Weekly Operating Workflow

  1. 1Open the app and confirm sync status is Connected.
  2. 2Go to the Points tab.
  3. 3Select the class for the current meeting.
  4. 4Check boxes for attendance and activity points earned.
  5. 5Tap Submit.
  6. 6Review a few members in the roster to confirm point totals updated.
  7. 7Generate a monthly or custom report as needed.
Section 10

Troubleshooting

Problem
No classes appear on the Points screen
Likely cause: no classes have been created yet.
Fix
  1. 1Open Settings.
  2. 2Add at least one class.
  3. 3Return to the Points tab.
Problem
Cannot add a member
Likely causes: member name is blank, no class is selected, or no classes exist yet.
Fix
  1. 1Add a class first if none exist.
  2. 2Select a class from the picker.
  3. 3Enter the member name and tap Add Member.
Problem
Imported workbook shows a warning
Likely causes: extra unrecognized sheet, missing required headers, numeric columns are not numeric, or invalid date format.
Fix
  • Use only the recognized sheet names: member, action, tier
  • Keep exact header names (lowercase, exact spelling)
  • Ensure points and thresholds are whole numbers
  • Use MM/DD/YYYY or ISO 8601 dates
Problem
Duplicate members after Excel import
Likely cause: repeated member rows in the Excel member-history sheet.
Fix
  1. 1Review imported members in Settings.
  2. 2Swipe to delete duplicates.
  3. 3Prefer CSV for simple member-only imports going forward.
Problem
Sync stays Offline or Disconnected
Likely causes: missing server URL, incorrect WebSocket URL format, Tailscale not connected, or server not running.
Fix
  1. 1Confirm Tailscale is running on both the server and the iPad.
  2. 2Check the server URL starts with ws:// and includes port 8080.
  3. 3Visit http://YOUR_IP:8080/health in a browser to confirm the server is running.
  4. 4Tap Connect then Pull Full Sync from Server after connection is restored.
Problem
Changes on one iPad not appearing on another
Likely causes: one or both iPads are in Local Only mode, or connection was lost and changes are queued.
Fix
  1. 1Verify both iPads show Connected in Settings → Live Sync.
  2. 2Confirm Server Mode is enabled on both devices.
  3. 3On the iPad missing data, tap Pull Full Sync from Server.
Section 11

Admin Checklist

Use after setup or after any large import to confirm the app is in a clean state.

  • Classes exist and are spelled correctly
  • Members appear in the expected class
  • Actions display correct point values
  • Tiers display correct thresholds
  • Award a small test action successfully
  • Open one member detail screen
  • Confirm lifetime points changed
  • Confirm tier display makes sense
  • Generate a quick report
  • Confirm report shows correct data
  • Sync status shows Connected (if using server)
  • Pull Full Sync on each new iPad
✅
Data quality tips: Standardize class names. Avoid near-duplicate action names. Keep one preferred spelling per member name. Verify imports in the roster immediately after loading data.