A household is the unit of tenancy in hdb.io. Almost every piece of data in the system belongs to exactly one household; every API request is scoped to one household at a time. This page explains the membership model and the roles inside it.

A user can belong to multiple households

The same user account can be a member of any number of households. Each membership is its own record, with its own role. A common shape:

• Their own household, where they are the owner.
• Their parents' household, where they are an adult.
• A rental property they manage, where they are an owner.
• A friend's place they help with, where they are a guest.

Switching between households is one click in the household switcher. The data, navigation, and permission set all change with the switch; there is no leakage between households at the database layer or the UI.

Roles are per membership, not per user

The role attaches to the membership, not to the user. The same person can be owner of household A and child of household B. The four roles:

The owner-vs-adult split is intentionally narrow. Most adult members can do almost everything an owner can. The two restrictions are protective: no accidental deletion of the household, no billing surprises.

Kids without logins are first-class

Not every member of a household needs a login. Person records (members without an attached user account) are first-class throughout the app:

• They appear in chore assignments.
• They have pocket-money balances.
• They show up on the kids dashboard.
• They are referenced in calendar events and lending records.

You can promote a person to a real login at any time by attaching a user account: invite them by email, they sign in, and the existing person record becomes their member identity. No data migration, no orphaned references.

The shared-device kids dashboard

The canonical kids interface is not "give every kid a login." It's a device token: a long-lived credential bound to a single physical device (typically a wall-mounted iPad or kitchen tablet) and a curated set of person records.

The token grants a read/limited-write kids UI: today's chores, the bin cycle, the menu, recent pocket-money credits. It does not grant access to the rest of the app. Tokens are issued from household settings and revoked the same way (useful when the iPad gets replaced or repurposed).

Per-device, per-household, per-set-of-people. No login screen, no password to forget, no security concerns about a kid bookmarking the parent's billing page.

Permission resolution

The middleware that gates every API call resolves permissions from the (user, household) tuple, not from the user alone. The flow:

1. Authenticated session → user id.
2. Active household (from session or x-household-id header) → household id.
3. Look up the membership row.
4. Check the role's permission set against the requested action.

If the membership doesn't exist, the call is rejected before the database sees it. There is no "guess the household" path.

Things to remember

• A user does not have a single role. They have a role per household.
• A household always has at least one owner.
• Removing the last owner is forbidden; you must promote another member first.
• Person records can be created, edited, or deleted without a user account.
• Device tokens are per device, not per kid. One iPad with one token serves all the kids in that household.