Cross-tenant reads

One app that hosts several sites keeps each site's content apart, yet a few of its pages must read all of them: a search box over every site, a feed of what's new anywhere. Let those pages read any site directly and the separation is gone; copy each site's fields into them and the copies drift. The fix is to let each site offer named parts of its content, and give readers one way in that sees only what was offered.

Know this pattern already? Skip to In Terrarium.

In Terrarium

Each TenantOne site inside Terrarium, with its own components and content model, built as a Nuxt layer.GLOSSARY.md keeps its content in tables of its own (Multi-tenant isolation). The shared shapes are the Collection kindsA named, shared shape a Collection can opt into so code in other Tenants can read it. Its contract is a minimum; the Collection adds its own fields on top.GLOSSARY.md in shared/kinds.ts. The page kind adds optional fields to Nuxt Content's own page fields, and the session kind's contract is the whole session-log schema:

50export const KINDS = {
51  page: {
52    type: 'page',
53    contract: z.object({
54      /** Publish instant — what the Commons Timeline orders dated pages by. */
55      publishedAt: utcTimestamp.optional(),
56      /** One-line headline (e.g. a Journal digest's day-summary) an aggregator
57       *  prefers over the title. */
58      summary: z.string().optional(),
59    }),
60  },
⋯  // …
65  session: { type: 'data', contract: sessionSchema },
66} satisfies Record<string, KindDef>

A CollectionOne type of content inside a Space, such as its pages. Each Tenant, Space and Collection together get their own table.GLOSSARY.md opts in with kind: 'page' or kind: 'session' in its Tenant's manifestThe one small file, tenant.config.ts, in which a Tenant states what it holds. It names the Tenant, its Spaces, and its Collections with their types and schemas, and code builds everything else from it. (Content collections). The Journal's manifest, layers/journal/tenant.config.ts, names both kinds:

141    pages: {
142      type: 'page',
143      kind: 'page', // opt into the cross-Tenant #catalog (ADR-0025)
⋯    // …
180    sessions: { type: 'data', kind: 'session', source: '**/*.yml' },

The manifest check refuses an unknown kind, or a kind whose type doesn't match the Collection's. expand() in shared/expand.ts gives the Collection the contract's fields plus its own, so pnpm validate:content checks the contract in every Document that opts in. catalogFrom() in the same file lists every Collection that names a kind, grouped by kind, and modules/catalog.ts writes that list at build time as the #catalog module: the CatalogThe list, built with the site, of every Collection that opted into a shared shape, so code in other Tenants can read it. A Collection that doesn't opt in stays hidden from them.GLOSSARY.md.

The read function is queryAcrossTenants in app/composables/catalog.ts. It runs Nuxt Content's queryCollection on each Collection the Catalog lists for a kind, one query per Collection, lets the caller's project pick the fields it needs, and tags each row with its Tenant, Space and Collection:

46export async function queryAcrossTenants<T>(
47  kind: KindName,
48  project: (item: CatalogItem) => T,
49): Promise<Array<T & CatalogProvenance>> {
50  const perCollection = await Promise.all(
51    catalogByKind(kind).map(async (entry) => {
⋯      // …
55      const items = await queryCollection(entry.key as keyof Collections).all()
56      return items.map((item) => ({
57        ...project(item as unknown as CatalogItem),
58        tenant: entry.tenant,
59        space: entry.space,
60        collection: entry.collection,
61      }))
62    }),
63  )
64  return perCollection.flat()
65}

queryPages() in the same file reads the page kind and adds each page's own URL. The Commons, the Tenant that holds the AggregatorA view whose job is to read across Tenants, such as a search or an activity feed. It reads only the Catalog and writes nothing; views made just for this are Spaces of the Commons Tenant.GLOSSARY.md views, builds its Search and Timeline on these two functions, and a Blog post finds the Journal digest of the day it was published through queryPages(). The Commons's own pages name no kind in layers/commons/tenant.config.ts. One page reads other Tenants without the Catalog: the Platform home page, app/pages/index.vue, which features hand-picked Tenants.

tests/unit/expand.spec.ts checks that a Collection without a kind stays out of the Catalog and that an opted-in one gets the contract's fields; tests/unit/kinds.spec.ts checks the contracts.

Where next

• LessonMulti-tenant isolation
• LessonContent collections
• LessonProtected paths
• LessonContent validation
• JournalArchitecture & Deployment