Skip to content

technology

· · 6 min read

Family Is Not an Afterthought

Most identity systems treat organisations as primary and families as an edge case. We reversed that. Every Nyuchi user belongs to a family entity by default.

By Bryan Fawcett

The identity layer of most software platforms has one core assumption: users belong to organisations. Your Slack has a workspace. Your Notion has a team. The entire B2B SaaS identity model is built around the premise that the most important grouping of people is a company.

This assumption is wrong for most of the world.

The problem with org-first identity

In much of Africa, the primary unit of digital life is not a company. It's a family. A mother manages finances for her household. A father shares a phone with his children. Grandparents need access to health information managed on their behalf. The family unit is where trust is highest, where devices are shared, and where economic decisions actually get made.

When your identity system only has "organisation" as a grouping concept, families become an afterthought — hacked in through shared passwords, secondary email addresses, or "family plan" pricing tiers that are just discounted org seats with a different label.

We decided to fix this at the schema level.

identity.entity

When we moved our authentication layer to WorkOS, we took the opportunity to rethink how entities work in our system. The result is identity.entity — a single table that represents every grouping a person can belong to.

The table has an entity_type column (organization or family) and an additional_type column that carries the schema.org-inspired qualifier: bundu:Family, bundu:Corporation, bundu:NGO, bundu:NewsMediaOrganization, and so on. This two-level typing gives us the broad grouping for access control and the specific subtype for product logic.

When a new user signs up for any Nyuchi product or Mukoko mini-app, two things happen:

  1. An identity.person record is created.
  2. A family entity with additional_type: bundu:Family is created, and the person is set as founder_person_id.

Every person has a family. Always. By default. Before they join any organisation, before they subscribe to any product — they have a family entity that belongs to them.

The real schema

This isn't a concept diagram. This is the live table in our platform database, with 97 entities in production today — 2 families and 95 organisations:

identity.entity
├── id                      uuid (UUIDv7 — time-ordered)
├── entity_type             text ('organization' | 'family')
├── additional_type         text ('bundu:Family' | 'bundu:Corporation' | ...)
├── name                    text
├── slug                    text
├── workos_org_id           text (nullable — links to WorkOS)
├── founder_person_id       uuid → identity.person
├── verification_status     text (default: 'unverified')
├── verification_tier_level integer (default: 0)
├── ubuntu_score            numeric (default: 0)
├── member_count            integer (default: 1)
├── ceramic_did             text (nullable — sovereign Web3 identity)
├── country_id / province_id / city_id / place_id  (geo references)
├── metadata                jsonb
└── created_at / updated_at  timestamptz

A few things worth noting:

UUIDv7 for IDs. Time-ordered UUIDs mean entities sort chronologically by creation — useful for feeds, admin dashboards, and audit trails without a separate index.

workos_org_id bridges to WorkOS for authentication. WorkOS handles SSO, directory sync, MFA, and session management. We own the identity graph. WorkOS confirms that Bryan is Bryan. Our system knows that Bryan belongs to the Fawcett family and to Nyuchi Africa, and what each of those memberships means.

ubuntu_score is a numeric reputation metric that accrues across the entity's lifetime — community contribution, verification level, platform participation. Named after the philosophy, not the operating system.

ceramic_did is the entity's decentralised identifier for the sovereign data layer. Personal data that belongs to the family — preferences, engagement history, Digital Twin memory — lives in a Web3 pod bound to this DID, not in our database.

The architecture philosophy behind it

The entity model isn't an isolated design decision. It's an expression of five architectural principles that govern everything we build, documented in the Nyuchi Design Portal at design.nyuchi.com:

Ubuntu: I am because we are. Every architectural decision flows from communal benefit. The platform exists to serve communities, not extract from them. Family-as-entity is the structural expression of this — the smallest community is the household.

Local-first. The device is the primary source of truth. The cloud is a synchronisation layer, not a dependency. Family identity data syncs to devices so that a shared phone in a village with no connectivity still knows who its family members are.

Open source and sovereign. Every technology assessed for sovereignty risk. Apache-licensed and public-domain technologies preferred. All core infrastructure is self-hostable and forkable. We removed MongoDB for SSPL license concerns. We chose WorkOS not because it's open source (it isn't) but because our identity graph is ours — WorkOS handles auth, we own the data. If we ever need to move, the entity table comes with us.

Open data. Platform-level, anonymised, aggregate data is Mukoko's gift to the continent, not its moat. But personal data — family membership, relationships, health records, financial state — is private, protected, and belongs to the user.

Data ownership tiers. The architecture recognises four ownership levels:

  • Personal (strict consistency, Supabase/Postgres) — identity, wallets, transactions. Two conflicting versions are never acceptable.
  • Community (eventual consistency, ScyllaDB) — content, messages, listings. A few seconds of propagation delay is fine.
  • Personal-sovereign (user-controlled, Web3 pod) — preferences, Digital Twin memory, AI context. Cryptographically bound to your keys. The platform cannot read it.
  • Platform-open (aggregate, Apache Doris) — anonymised intelligence. Public API for researchers, journalists, governments.

Family entities sit in the personal tier — strict consistency, ACID guarantees, RLS on every table. Who is in your family, and what role they hold, is never eventually consistent.

What a family entity does

Shared identity context. Family members can see each other's presence, share calendar events, split payments, and manage shared subscriptions. A parent can add a child to the family and manage their permissions.

Device trust. When a phone is shared within a family, the family entity is the trust boundary. Account switching between family members has lower re-authentication friction than switching to a non-family account.

Delegation. Let a sibling manage a BushTrade listing, a parent view health reminders, a child use transport with location sharing back to the family. Delegation is scoped to the entity and respects the relationships within it.

Economic unit. The family wallet holds shared funds. Subscriptions are family-level. When Mukoko introduces family plans, they'll be a natural expression of the entity that was already there, not a marketing construct.

What this changes about product design

Onboarding. A new user lands in a family — even if it's a family of one. The first prompt isn't "invite your team." It's "who's in your household?"

Billing. A family of four sharing Mukoko doesn't need four subscriptions. The family entity has its own billing relationship.

Privacy. Within a family, certain data is shared by default. Between a person's family and their organisation, nothing is shared. The entity boundary is the privacy boundary.

Permissions. A guardian can manage a child's account. A parent can set content filters. These are family roles with culturally appropriate capabilities, not org-chart admin permissions.

The Ubuntu connection

In Shona philosophy, the family is the irreducible unit of society. The proverb "Rume rimwe harikombi churu" (one man does not surround an anthill) speaks to the idea that meaningful work requires a collective, and the first collective is the family.

When we say our engineering doctrine is grounded in Ubuntu, we mean it structurally. The identity layer treats family as foundational because that's what Ubuntu demands: the individual exists within their family, the family within their community, the community within the wider world. If your data model skips the family and jumps straight from individual to organisation, you've skipped the most important layer.

Bryan Fawcett is the founder and CEO of Nyuchi Africa, building frontier infrastructure for African markets. The architecture principles and design system are documented at design.nyuchi.com.

Back to blog