How House is built

This page is for readers who want to know how House works underneath. You do not need it to use House. The task guides start at Getting started.

House is an orchestrator. It mounts the Vonkara, Heldaro and Kragara products under one shell, backed by one shared Postgres database (a schema per product) and one gateway. Each product also runs standalone outside House. Inside House it runs in house-mode: the same product, wired to your House account, your household and the gateway.

How households are kept separate

A household is the unit of data isolation in House. Every product’s data belongs to a household, and the platform guarantees you only ever see your own household’s rows.

Isolation is enforced in the database itself, not only in application code. The shared Postgres cluster uses row-level security (RLS) on every tenant table:

• Services connect as roles that cannot bypass RLS. Requests carry the household you resolved, set as a database session variable (app.household_id), and every policy filters on it.
• Tables fail closed: with no household set, a query returns zero rows, never everything.

This means a bug in a product’s query cannot leak another household’s data. The database refuses to return it.

Member-private surfaces

Within a household there can be several members. Some surfaces are member-private, for example things only you should see even inside your own household. These carry a second key (app.principal_id) so the database enforces per-member visibility on top of per-household isolation.

Which tables are member-private is declared per product. An automated test proves that two members of the same household cannot see each other’s private rows.

Backups

Backups are taken by a dedicated, offline database role. A role used to serve live traffic never takes them.

Suites and plans

A suite is a commercial grouping of product surface. A suite is a shape × vertical:

Suite	Shape	Plan ladder	Notes
vonkara	personal	Free, Starter, Pro	Vonkara’s per-room suite. Its Premium rung was retired in August 2026
heldaro	personal	Free, Starter, Pro, Premium	Heldaro’s per-room suite. Premium is not open yet
kragara	personal	Free, Starter, Pro, Premium	Kragara’s per-room suite. Premium is not open yet

Free is the absence of a paid subscription for that room.

Grant keys

Entitlements are stored as value-less keys:

• Capability keys - cap:<product>:<feature>, for example cap:vonkara:pack-flow, cap:kragara:pack-adaptive or cap:ai:use (the key that gates AI access). These answer “may I?”.
• Tier keys - tier:<suite>:<ordinal>, for example tier:vonkara:2 (Pro). These carry the billing ordinal for a suite.

A pack is a bundle of a room’s features, named by a cap:<product>:pack-* key. A product’s house-mode resolver turns a pack key into the internal feature flags it unlocks. Free-core features are the ones no pack claims.

How access is resolved

Entitlements are resolved from the database at request time, never trusted from a token claim:

1. The gateway strips every inbound identity header, then calls the identity service’s /_verify.
2. /_verify re-checks the live household and mints the identity and scope headers (X-House-Scopes, X-House-Suites, X-House-Principal and others) from current database state.
3. The gateway forwards those headers to the product.

If resolution fails, the request fails closed (401). A downgrade or cancellation strips the purchased grants. A grace hold keeps them for a defined window. This is why revoking access takes effect immediately: no long-lived entitlement is baked into a token.

How products receive your access

A product never reads your entitlements from a token. It reads the gateway-injected headers. They can be trusted because the gateway is the only thing allowed to set them, and it strips any that arrive from outside.

AI calls

Products never call a cloud AI provider directly. All AI calls go through one House chokepoint. It holds the provider credential, enforces a data boundary, meters usage per person, and requires the cap:ai:use capability. The same path powers Ask the docs.

One router, one bundle

The shell owns a single top-level router. Products mount through a defined seam instead of nesting their own router, which keeps navigation coherent across every mounted product.

The shell is a single bundle that includes each product’s front-end source, assembled at build time. The built assets are baked into the gateway image and served as static files: one pinned build promoted across environments. The docs site is baked the same way, under /docs.

Where to read more

The API reference lists the identity and billing endpoints. For help with using House, read Getting help.