Phase 2: Household/shared pantry — design and pricing model #5

New issue

Open

opened 2026-03-28 18:35:02 -07:00 by pyr0ball · 0 comments

pyr0ball commented

2026-03-28 18:35:02 -07:00

Owner

Overview

Kiwi needs a household (shared pantry) model for Premium tier. Multiple users should be able to share a single pantry DB. This issue captures the pricing model and technical design.

Pricing Model

Household subscription — Premium tier price covers the shared pantry (one license key for the household)
Member discount — users linked to a household get a reduced personal tier rate (e.g. Paid $5/mo -> $3/mo for household members)
Volume — household price is flat up to a base seat count (e.g. 4), then per-seat beyond that
Discount applied via Heimdall: member keys are linked to the household key; billing system checks membership at renewal

Technical Design Options

Option A: Household as first-class entity (preferred)

household has its own SQLite DB at CLOUD_DATA_ROOT/household_{id}/kiwi.db
household_members table in Heimdall (or Kiwi-side) links user_id -> household_id
CloudUser.db resolves to household DB when user has an active household membership
Invite flow: owner sends link -> new member joins -> Heimdall links keys

Option B: Owner delegation (simpler, faster to ship)

One user owns the household DB; others resolve to the owner's DB path
No separate household DB entity — just a pointer redirect in CloudUser

Option C: Personal + shared DBs

Users keep personal DB; household gets its own DB
Queries can target either or both
Allows private items alongside shared pantry, at the cost of more complex UI

Heimdall Changes Needed

Household license key type linking multiple user_ids
/admin/household/create, /admin/household/add-member, /admin/household/remove-member
Member discount applied at provisioning time
Household membership resolved in /validate response

Tier Gate

Feature flag: multi_household (already in tiers.py)
Gated at Premium tier

Open Questions

Flat household price (e.g. $10/mo up to 4 members) or per-seat from the start?
What happens to a member's personal inventory when they leave a household?
Should the household owner be able to set per-member permissions (read-only vs. full write)?

Milestone

Phase 2 / Beta

## Overview Kiwi needs a household (shared pantry) model for Premium tier. Multiple users should be able to share a single pantry DB. This issue captures the pricing model and technical design. ## Pricing Model - **Household subscription** — Premium tier price covers the shared pantry (one license key for the household) - **Member discount** — users linked to a household get a reduced personal tier rate (e.g. Paid $5/mo -> $3/mo for household members) - **Volume** — household price is flat up to a base seat count (e.g. 4), then per-seat beyond that - Discount applied via Heimdall: member keys are linked to the household key; billing system checks membership at renewal ## Technical Design Options ### Option A: Household as first-class entity (preferred) - `household` has its own SQLite DB at `CLOUD_DATA_ROOT/household_{id}/kiwi.db` - `household_members` table in Heimdall (or Kiwi-side) links `user_id -> household_id` - `CloudUser.db` resolves to household DB when user has an active household membership - Invite flow: owner sends link -> new member joins -> Heimdall links keys ### Option B: Owner delegation (simpler, faster to ship) - One user owns the household DB; others resolve to the owner's DB path - No separate household DB entity — just a pointer redirect in CloudUser ### Option C: Personal + shared DBs - Users keep personal DB; household gets its own DB - Queries can target either or both - Allows private items alongside shared pantry, at the cost of more complex UI ## Heimdall Changes Needed - Household license key type linking multiple user_ids - `/admin/household/create`, `/admin/household/add-member`, `/admin/household/remove-member` - Member discount applied at provisioning time - Household membership resolved in `/validate` response ## Tier Gate - Feature flag: `multi_household` (already in tiers.py) - Gated at Premium tier ## Open Questions - Flat household price (e.g. $10/mo up to 4 members) or per-seat from the start? - What happens to a member's personal inventory when they leave a household? - Should the household owner be able to set per-member permissions (read-only vs. full write)? ## Milestone Phase 2 / Beta