> For the complete documentation index, see [llms.txt](https://spice.docs.medtroniclabs.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://spice.docs.medtroniclabs.org/user-guide/household-and-member-registration.md).

# Household & Member Registration

## Feature Overview

Household and member registration is how community health workers build and maintain the list of families they serve. Each household is registered once, together with its head, and further members can be added at any time. Every registered member can then receive services (screening, assessments, follow-up) from the household or member list.

The app also supports **external members**: people who are registered without belonging to a household (for example, people who live outside the worker's catchment area).

Registration works **offline**. Households and members are saved on the device first and are uploaded automatically in the background when a connection is available.

## Household List

From the Home screen, open **Households** to see every household available on your device.

* **Search:** type in the search box to find a household by household name or number, member name, ID number or phone number. Results update as you type.
* **Filter:** tap **Filter** to narrow the list by the community health worker responsible for the household and by village. The button shows the number of active filters, for example **Filter (2)**. Tap **Cancel** in the filter sheet to clear the filters.
* **Sort:** tap **Sort** and choose **Household No**, **Last Visit Date** or **Last Member Registration Date**. Tap **Reset** to return to the default order.
* The list header shows how many households match your search and filters. If nothing matches, the screen shows "No Household found."
* Tap a household to open its summary.

## Registering a Household

1. On the **Households** screen, tap **Add Household**.
2. Read the **Terms and Conditions** (consent) page. The text is shown in the language configured for the app and includes your name as the person recording the consent. Tap **Accept** to continue.
3. Complete the **Household Registration** form. The form is configured for your programme, but it generally captures:
   * **Location:** the village or other administrative level where the household lives, and the community health worker responsible for it. If only one option is available it is selected for you.
   * **Household number:** generated automatically once the village is chosen, based on the households already registered there.
   * **Household details:** household type, income range, total number of members, number of members with a disability, and the occupation of the household head.
4. Tap **Next**. Nothing is saved yet: the household is created together with its head in the next step.
5. Complete the **Household Head Registration** form (see [Registering a Member](#registering-a-member)). The head's name becomes the household name, for example "Jane's Family". The household head must meet a minimum age (14 years).
6. Tap **Submit**. The household and its head are saved on the device.
7. The **Household Summary** opens. Add more members now (**Add New Member**) or tap **Finish Registration**. A confirmation message, "Household registration completed successfully," is shown.

> If you leave a registration screen before submitting, the app warns you: "If you leave this screen, your entered data will not be saved."

The device location is recorded with each registration. The app asks for location permission and continues even if you decline it.

## Household Summary

The summary page shows:

* **Household Details:** household number, village, the responsible community health worker and the last visit date.
* **Household Members:** one card per member with name, age, gender, patient ID and the most recent service received. Deceased members are marked "(Deceased)".

Tap a member to open the member summary. Use the **⋮** menu (top right) for:

| Option              | What it does                                                                                  |
| ------------------- | --------------------------------------------------------------------------------------------- |
| **Edit Member**     | Choose an active member from a list and open their registration form to change details.       |
| **Add New Member**  | Open the member registration form for this household.                                         |
| **Member Deceased** | Choose a member and record the reason for death. See [Recording a Death](#recording-a-death). |

## Registering a Member

The same **Member Registration** form is used for the household head, for additional members and for editing. It is configured per programme, but generally captures:

* **Name**
* **Date of birth or age**
* **Gender**
* **Phone number and phone number category** (for example personal, household head, family or friend). For the household head the "household head" category is not offered. For other members, choosing it fills in the head's phone number automatically.
* **ID type and ID number**
* **Relationship to the household head** (not asked for the head)
* **Marital status** (shown only for members aged 14 or over)
* **Disability**
* **Guardian** (shown for members aged 2 or under when adding or editing a member after the household exists). Pick an existing household member, or choose **+ Add Guardian** to register the guardian first. The app warns that unsaved data on the current form will be lost.
* **QR code** (optional, if your programme links a QR card to the member): scan the code to link it.

To add a member to an existing household:

1. Open the household and tap **Add New Member** (button or **⋮** menu).
2. Fill in the form.
3. Tap **Submit** to save and return to the household summary, or tap **Services** to save and go straight to the services menu for this member. The confirmation message is "Member registration completed successfully."

### Validation Rules

* Required fields are marked and must be completed before you can submit.
* The date of birth cannot be left blank. If only the age is known, enter the age and the app calculates a date of birth.
* If the ID type is a national ID, the number must be unique: the app checks the IDs stored on the device and shows "National ID is already assigned to another member" for a duplicate. The number must also match the expected length.
* A QR code can be linked to only one person. If it is already linked, the app shows "Invalid QR Code. The scanned QR Code is already associated with a different individual."
* Once saved, gender and date of birth cannot be changed when editing a member.

## Recording a Death

1. On the household summary, tap **⋮** and choose **Member Deceased**.
2. Select the member.
3. Depending on the member's age and recent delivery history, the app asks for a type of death and the related causes, or for a free-text reason.
4. Submit. The member is marked as deceased in the household list and can no longer be edited.

## External Members

External members are registered without a household.

1. Open the member list (or the service recipient list) and tap **Add External Member** (or **Add Member**, depending on your role).
2. Complete the **External Member Registration** form. It is similar to the member form but also asks for the member's location (village level), because there is no household to take it from.
3. Tap **Submit** to save or **Services** to continue directly to services for this member.

External members appear in the member list under the **External member list** category. To change their details, open the member summary and tap **Edit**.

## Finding Members

Depending on your role, members are found through the **Service Recipient List** or the **My Patients** list.

* **Search** by member name, ID number or phone number. You can also tap the QR icon and scan a member's QR code.
* Use the drop-down at the top to switch between predefined lists, such as all members, expectant mothers, young children, external members and members who have had a particular service. Each entry shows the number of members.
* Tap **Filter** to narrow by location. The number of active filters is shown on the button.
* Results combine members stored on the device with matching members held on the server. Selecting a member who is not yet on the device downloads their record, so a connection is required; if you are offline the app opens the copy stored on your device when there is one.

Tap a member to open the **Member Summary**: registration details (registration date, patient ID, family, phone number, last visit, services provided) and a timeline of past services you can step through by date. Tap the **Services** button to start a screening or assessment for this member.

## Duplicate Records

* Registration checks ID numbers and QR codes against records on the device, as described under [Validation Rules](#validation-rules).
* When a patient is enrolled for treatment, the app also checks the server for an existing patient with the same details and warns before creating a second record. See [Enrollment](https://spice.docs.medtroniclabs.org/user-guide/enrollment.md).

## Working Offline

* The household list, member lists, registration forms and edits all work without a connection, using data already downloaded to the device.
* New and edited households and members are saved on the device and uploaded in the background as soon as a connection is available.
* A connection is needed to download members that are not on the device and to complete patient enrollment. See [Offline & Sync](https://spice.docs.medtroniclabs.org/user-guide/offline-and-sync.md) for details on how and when data is uploaded.
