Martial Arts Belt Test Tracker — User Manual

1) First-Time Setup

Start in Control Panel. Set up the core lists first so student records, attendance, tests, and reports all use the same names.

1.1 Manage Belts

• Tap Manage Belts.
• Use Load Default Belts to start with the built-in belt list, or add your own belt names.
• Use the up/down buttons to adjust belt order.
• Tap a belt name to rename it.
• Use the color pickers to set belt background and text colors. Those colors are used anywhere belts are shown.
• Use X to remove a belt. The app warns when a deleted item is referenced elsewhere.

1.2 Manage Sessions

• Tap Manage Sessions.
• Add each class time, age group, or class type you want to track.
• Examples: Kids 4:30, Juniors 5:15, Adults 6:15, Private Session.
• Tap an existing session name to rename it. The app updates related student, attendance, and belt test records.

1.3 Manage Instructors

• Tap Manage Instructors.
• Add every instructor or staff member who teaches classes, records attendance, or participates in testing.
• Tap an instructor name to rename it. Existing attendance and belt test records are updated to match.

1.4 Default Billing and Eligibility Settings

• Billing reminder lead days controls how many days before a billing date the dashboard begins showing reminders.
• Update Default Fee changes the default monthly fee for new students and can optionally update existing student records.
• Sessions required before eligible controls how many attendance records are required in the selected eligibility window.

1.5 Check-in Settings

• Open Check-in Settings to configure the kiosk.
• Choose the default kiosk tab: Face or Student ID.
• Adjust liveness, match threshold, confirmation, auto-lock, and staff PIN settings.

1.6 Cloud Account and First Backup

After the basic lists are set up, connect the cloud account before entering a large amount of live student data. This gives the cloud server a first known backup from this device and records this device’s cloud identity for future sync checks.

1. Open Control Panel → Cloud Backup.
2. Enter the approved Account email.
3. Enter the account Passphrase.
4. Enter a clear Device name, such as “Front Desk Laptop”, “Office Desktop”, or “Instructor Tablet”.
5. Tap Connect Cloud Account. This connects the account and refreshes entitlements/student-cap limits.
6. Make sure Enable cloud backup / restore is checked.
7. Tap Backup Now to create the first cloud backup from this device.
8. After the first backup completes, use Check Cloud Sync if you want to confirm that the cloud and this device match.

2) Add & Manage Students

Use the Students tab to add, edit, search, view, and deactivate student records.

2.3 Student Table

• Click a student name to open a read-only detail view with profile, contact, billing, emergency, belt size, gi/dobok size, belt test history, attendance history, and notes.
• Use Edit to modify a record.
• Use Delete only when the student should be removed from the system. Deactivating is usually safer when a student may return.
• The camera icon opens face enrollment for that student. The dot indicator shows whether face data is enrolled. The trash icon removes face enrollment.

2.4 Student Filters

• Use the search box to find students by name, belt, belt size, gi/dobok size, instructor, or session.
• Use the Active, Eligible, and Family Plan filters to narrow the list.
• Clear Filters resets the student list back to the normal active-student view.

3) Dashboard

3.1 Belt Counts

The belt count chips show how many students are currently assigned to each belt. Chip colors follow the belt colors set in Manage Belts.

3.2 Birthdays

• Birthday reminders show today, upcoming, and recently past birthdays.
• Use Dismiss or Dismiss All after reminders have been handled.
• Dismissed birthday reminders can be restored later from Control Panel → Restore Notifications.
• Only active students are included in normal birthday reminders.

3.3 Billing — Upcoming & Due

• Billing reminders show upcoming, due today, and past-due student billing dates.
• Use Dismiss, Snooze, or Dismiss All to clear reminders you have handled.
• Family Plan students and inactive students are skipped by individual billing reminders.
• Dismissed billing reminders can be restored from Control Panel → Restore Notifications.

4) Class Attendance

4.1 Add Attendance Record

1. Open the Attendance tab.
2. Tap Add Attendance Record.
3. Choose the class Date and Session.
4. Select one or more Instructors.
5. Select the active students who attended. Selected names appear in the selected-students box.
6. Add notes if needed, then tap Save.

4.2 Attendance Table

• The attendance table shows class date, session, number of students present, notes, and actions.
• View Notes opens the full attendance record, including date, session, instructors, students present, and notes.
• Edit reopens the attendance record so you can change date, session, instructors, students, or notes.
• Delete removes the attendance record after confirmation.

4.3 Attendance Filters

The attendance page includes filters to make older records easier to find.

• From and To filter attendance by date range.
• Student Name finds attendance records containing a matching student.
• Instructor Name finds records taught by a matching instructor.
• Notes finds attendance records containing matching note text.
• Sessions uses a scrollable checkbox list so multiple sessions can be selected at the same time.
• The note preview beside View Notes shows a shortened version of each record’s notes without opening the full record.
• The summary shows how many records are currently visible out of the total records.
• Clear Filters resets the attendance table to all records.

4.4 Missed Attendance

• Missed Attendance shows active students with no attendance in the selected window.
• Use the default last-14-days view or choose a custom date range.
• Tap a student name to open contact information and optionally deactivate the student.

5) Belt Test Eligibility

• Open Check Belt Test Eligibility from the Attendance tab.
• Use the quick number-of-days field or choose From and To dates.
• The app counts attendance records for each active student in the selected window.
• Students are grouped into Eligible and Ineligible based on the threshold set in Control Panel.
• Tap a student to see the exact sessions counted.
• You can manually check or uncheck Eligible from the student detail window.

6) Belt Tests

6.1 Add or Edit a Belt Test

1. Open the Belts tab and tap Add Belt Test.
2. Choose the student. New belt tests normally show active students marked eligible.
3. Select instructor(s), test date, session, result, belt, and notes.
4. Tested records that the student tested but a pass/fail decision has not been finalized.
5. Pass prompts you to choose the belt the student advanced to, then updates the student’s current belt.
6. Fail records the failed result and keeps or sets the appropriate belt.
7. Optional Result Date can be used for pass/fail finalization date.

6.2 Belt Test Filters

• Use the search box to find tests by student, belt, instructor, session, result, or result date.
• Use the Tested, Pass, and Fail checkboxes to narrow results by status.
• Clear Filters resets the belt test list.

7) Reports

Open Tools → Reports to view and export focused report tables.

7.1 Students Report

• Search by name, belt, belt size, gi/dobok size, instructor, or session.
• Filter by active status, eligible status, Family Plan status, belt, belt size, gi/dobok size, session, fee, and cycle day.
• Choose how many rows are visible.

7.2 Billing Report

• Filter by student name or ID.
• Choose a from-month and to-month.
• Filter by upcoming, due today, past due, or paid status.
• Choose whether to include inactive students or Family Plan students.

7.3 Belt Tests Report

• Filter by test date range, target belt, and result.
• View student, current belt, target belt, test date, result date, instructors, session, result, and notes.

7.4 Export Reports

• Export CSV creates a spreadsheet-friendly file.
• Export JSON creates a structured data file.

8) Control Panel, Data, and Cloud Backup

8.1 Manage Core Lists

• Manage Belts controls belt names, order, and colors.
• Manage Instructors controls instructor names used by students, attendance, and tests.
• Manage Sessions controls class/session names used by students, attendance, and tests.

8.2 Data Import, Export, and Reset

• Export Data downloads a JSON backup of the app data, including student records, attendance, belt tests, settings, notification state, and face embeddings when enabled.
• Import Data loads a JSON backup into the app. The app attempts to normalize older attendance formats when imported.
• Reset Data clears app data after confirmation. Export first if you may need the data later.
• Restore Notifications lets you bring back dismissed birthday or billing reminders.

8.3 Auto-Export

• Enable Auto-Export allows the app to generate a local JSON export after detected data changes.
• Period controls the waiting time in minutes.
• Auto-export is separate from cloud backup.

8.4 Cloud Backup and Entitlements

Once a cloud account is connected, the app can use that connection for account entitlements and optional cloud backup/restore. Entitlements and student-cap limits can still refresh while backup/restore is turned off.

1. Enter the approved Account email.
2. Enter a Passphrase of at least 8 characters.
3. Enter a unique Device name such as “Front Desk Laptop” or “Shop Tablet”.
4. Tap Connect Cloud Account.
5. Use Enable cloud backup / restore to turn cloud backup, sync comparison, and restore features on or off for this device.

8.4.1 Cloud/Local Difference Review

If the cloud backup and this device do not match, the app shows a comparison table with one column for Cloud and one column for This Device. The table lists specific changed fields when possible, such as student names, belt size, eligibility threshold, billing lead days, attendance date/session/instructors/students/notes, and belt test differences.

8.5 What Cloud Backup Includes

• Students
• Belts, instructors, and sessions
• Attendance records, including notes
• Belt tests
• Settings and notification state
• Face embeddings when included in export data

9) Session Check-in Kiosk

The kiosk is opened from an attendance record so check-ins are attached to the selected date, session, and instructors.

9.1 Face Enrollment

• In the Students table, click the camera icon beside a student ID.
• Open the camera, capture clear face images, then save enrollment.
• Good lighting, a steady camera, and a straight-on face angle improve matching.
• The app stores numerical face embeddings for matching. It does not need to keep normal face photos for everyday matching.
• Use the trash icon to remove a student’s face enrollment.

9.2 Open Session Check-in

1. Create or edit an attendance record.
2. Select date, session, instructors, and any students already known present.
3. Tap Open Session Check-in (Kiosk).
4. Students can check in by face or by Student ID, depending on kiosk settings.
5. Confirmed check-ins are added to the attendance record for that session.

9.3 Kiosk Exit and Duplicate Handling

• Use Exit to leave kiosk mode.
• The staff PIN is required when the kiosk is locked or protected.
• The default PIN is 1234 until changed in Check-in Settings.
• Duplicate check-ins are blocked within the same kiosk session.

10) Working Rules

• Active students appear in normal attendance and eligibility workflows.
• Inactive students remain in saved records but are skipped in normal working lists.
• Family Plan students are skipped by individual billing reminders.
• When a student passes a belt test, their current belt is updated to the selected belt.
• After a belt test is saved, the student’s Eligible flag is cleared.
• Renaming belts, instructors, or sessions is safer than deleting them because the app can update related records.

11) Tips & Troubleshooting

11.1 Data Looks Missing

• Confirm you are using the same website address as before. Browser storage is tied to the exact site address.
• Check filters. A filter can hide records without deleting them.
• Use Clear Filters on Students, Attendance, or Belt Tests.
• If data was restored on a different device, use Restore Latest Cloud Backup or import the correct JSON file on this device.

11.2 Camera or Face Check-in Does Not Work

• Make sure the app is loaded over HTTPS.
• Allow camera permission in the browser.
• Use good lighting and keep the face centered.
• Re-enroll the student’s face if matches are inconsistent.

11.3 Cloud Backup Problems

• Confirm the account email is approved for cloud backup and entitlements.
• Use the same passphrase originally used for that email.
• Check internet access, then try Connect Cloud Account again.
• Make sure Enable cloud backup / restore is checked if you want the device to back up, restore, or compare cloud/local data.
• If backup/restore is turned off, the account can still remain connected for entitlements and student caps.
• Use Check Cloud Sync to compare local data with the latest cloud backup.
• If a cloud/local difference warning appears, review the comparison table. Choose Restore & Use Cloud Data to make the cloud copy win, or choose Back Up Local Data & Use This to make this device’s local copy win. Do not continue making edits until you have chosen the correct direction.

11.4 Best Practices

• Export a JSON backup before large edits, imports, or resets. Cloud restore also attempts an automatic local export before replacing local data.
• Use consistent session and instructor names.
• Deactivate students instead of deleting when you want to preserve history.
• Avoid actively editing the same cloud account from multiple devices at the same time. Let one device finish backing up before another device makes changes.

12) Glossary