Crouton Architecture Contract

The load-bearing mental model of crouton: definitions, design decisions with their WHY, the invariants that must hold, and the honestly-stated weak points. This is theory + contract; the how-to lives in sibling skills.

When to use / when NOT to use

You want	Go to
The mental model, invariants, "why is it like this"	this skill
Generate a collection (workflow, MCP tools, gates)	crouton skill (.claude/skills/crouton.md)
Schema JSON format, field-type tables, artifact list	sibling crouton-generation-reference
Layout engine theory (LayoutTree, viability, placer)	sibling crouton-layout-reference; authoring a block → block-authoring skill
Symptom → root cause lookup	sibling crouton-diagnostics-index
Cold-start env setup, dist/install traps	sibling crouton-build-and-env
Which docs are stale vs canonical (full list)	sibling crouton-docs-trust-map
Which gate fires on a change	sibling crouton-change-control

Trust order when sources conflict: see sibling crouton-docs-trust-map §1 (it owns the ranked chain; code beats prose for runtime behaviour).

Glossary (repo jargon, first-contact)

Term	Meaning here
crouton	Three referents: (1) the whole framework; (2) the CLI (packages/crouton-cli, bin crouton) that generates collections; (3) @fyit/crouton, the umbrella Nuxt module
collection	The unit crouton generates: one entity/table, defined by a schema JSON, generated into a self-contained layer dir. Always team-scoped
layer	A Nuxt Layer (a Nuxt app consumed via extends). Two meanings in this repo — see §1
fieldsFile	The per-collection field-definition JSON (schemas/<name>.json) referenced by crouton.config.js
team	The multi-tenancy unit = a better-auth organization. Every generated API lives under /api/teams/[id]/…
fixture	A throwaway generated app in fixtures/ booted by the Playwright harness in e2e/ to smoke boot/auth/CRUD (see fixtures/CLAUDE.md)
POC	A real crouton app in pocs/ incubating a future package; safe-to-fail, no required gates
graduation	The deliberate spec-driven rebuild of a proven POC into real package(s) + app (/graduate skill, epics #916/#992)
gate	A hold point where a human signs off before the expensive step (Schema #314 / UI #307 / Test #774 / code review). Resume signal is an lgtm/approve comment only (#572)
stage	Where code lives in the lifecycle, declared in harness.config.mjs (poc/app/package/unstaged). Resolve with node scripts/harness-stages.mjs <path>
manifest	A package's crouton.manifest.ts — declares its field types, bundled-ness, reserved names, contributions (§5)

1. "Layer" means two different things

Newcomer trap #1. Both are Nuxt Layers technically, but they play different roles:

1. Package layer — packages/ holds the crouton-* packages plus the crouton meta package (count: re-verify block). Most are publishable Nuxt Layers consumed as source: packages/crouton-core/package.json has "main": "./nuxt.config.ts" (no build step for the layer itself; dist/ exists only for specific subpath exports — install traps: sibling crouton-build-and-env). Exceptions (check each package.json): crouton and crouton-devtools are Nuxt modules ("main": "./dist/module.mjs"), crouton-cli is the bin CLI, crouton-mcp is the MCP server, crouton-themes has no main at all (subpath-export theme layers only).
2. Generated per-collection layer — inside a consuming app, layers/<layer>/collections/<collection>/ is itself a nested Nuxt layer with its own nuxt.config.ts. Real tree (fixtures/minimal/layers/main/collections/items/):

layers/main/collections/items/
├── app/components/{_Form.vue, List.vue}
├── app/composables/useMainItems.ts
├── server/api/teams/[id]/main-items/{index.get,index.post,[itemId].patch,[itemId].delete}.ts
├── server/database/{schema.ts, queries.ts}
├── types.ts  nuxt.config.ts  README.md

(Newer generations add tests, seed.json, and app-root aggregates — the full artifact list is crouton-generation-reference's job.)

The extends chain, in a real launched app (apps/velo/nuxt.config.ts):

modules: ['@fyit/crouton'],
extends: [
  '@fyit/crouton-core', '@fyit/crouton-layout', '@fyit/crouton-i18n',
  '@fyit/crouton-assets', '@fyit/crouton-pages', '@fyit/crouton-bookings',
  '@fyit/crouton-email',
  './layers/bookings', './layers/pages',       // ← generated layers
  '@fyit/crouton-maps', './layers/crouton'
]

And @fyit/crouton-core itself extends ['@fyit/crouton-i18n', '@fyit/crouton-auth', '@fyit/crouton-admin'] (its nuxt.config.ts; "Order matters: i18n provides translation system that auth/admin consume") — so auth/admin/i18n arrive through core ("bundled"). Velo lists crouton-i18n explicitly anyway; see invariant 5 for why that pattern is dangerous with auth/admin.

The @fyit/crouton meta-package is a Nuxt MODULE, not a layer ("main": "./dist/module.mjs"), consumed via modules: ['@fyit/crouton'] across apps/fixtures/pocs (count: re-verify block). At runtime it cannot add layers (comment in packages/crouton/src/module.ts: layers must be in extends before modules load) — it only wires runtimeConfig and warns. Its exported getCroutonLayers() extends-builder has zero in-repo callers; apps hand-list extends, kept in sync by the CLI's syncFrameworkPackages. Treat getCroutonLayers() as aspirational (§7).

2. The two-halves rule (pointer)

Canonical: packages/crouton/CLAUDE.md § "Packages vs Generated Layers (IMPORTANT)". In one line: a crouton feature = a package (UI, admin pages, nav, composables, i18n — via extends) + a generated layer (Drizzle schema, API endpoints, configs, types — via the CLI), and they need each other: package without layer → no tables/endpoints (404/500); layer without package → a generic "Collections" sidebar with no dedicated UI. When something "is installed but doesn't work", check which half is missing first.

3. The three registries (all app.config, defu-merged across layers)

Registry	Who writes it	Who reads it
croutonCollections	The generator upserts one entry per collection into the app's app/app.config.ts	Core's shared CRUD components (CroutonCollection, forms, lists) resolve a collection by registry key
croutonApps	Each addon package self-registers in its own app/app.config.ts (e.g. crouton-bookings)	Sidebar/nav via useCroutonApps(), and presence detection via hasApp(id)
croutonLayoutBlocks	Each package contributes placeable layout blocks (defaults in crouton-layout; bookings adds calendar blocks)	The layout engine — sibling crouton-layout-reference

Stub-priority pattern — mechanics + code are owned by root CLAUDE.md § "Optional Cross-Package Components (Stub Pattern)". The WHY this skill adds: optional packages (editor, maps, assets, collab) may or may not be in the extends chain, and Vue has no clean "is this component available?" check (resolveComponent() warns unconditionally when absent; vueApp._context.components is private API). So core ships no-op stubs (packages/crouton-core/app/components/stubs/) at priority: -1; the real addon component at default priority silently wins when present — preventing warning spam + broken renders in apps without the addon. Behavior branching uses hasApp('assets'). Addons registering routes use a parentApp key (type in crouton-core/app/types/app.ts) so defu array-merging doesn't collide nav entries.

4. Team-scoped multi-tenancy

better-auth with the organization plugin; team = organization (canonical package: packages/crouton-auth). The resolver is resolveTeamAndCheckMembership(event) in packages/crouton-auth/server/utils/team.ts — mode-aware per its JSDoc (multi-tenant / single-tenant / personal), returns { team, user, membership }, throws 401/403/404. Every generated endpoint lives at /api/teams/[id]/<layer>-<plural>/ and starts:

import { resolveTeamAndCheckMembership } from '@fyit/crouton-auth/server/utils/team'
const { team } = await resolveTeamAndCheckMembership(event)
// every query takes team.id

Client side: useTeamContext() (packages/crouton-core/app/composables/useTeamContext.ts) reads the [team] route param. There is no opt-out — the generator hardcodes the auth import and passes team.id to every query (invariant 3). Core also wires a #crouton/team-auth nitro alias as a compat path; generated code uses the direct import.

5. Manifest-driven field types

Field types are not hardcoded in the CLI. Each package declares a crouton.manifest.ts (defineCroutonManifest from @fyit/crouton-core/shared/manifest); the CLI's manifest loader merges them into the type mapping. Core's manifest declares the base types (string, text, number, … — exact list in the file) with db/drizzle/zod/tsType/defaultValue/component, plus aliases (integer→number, datetime→date) that resolve to canonical before generators run — the #285 incident is why (datetime once leaked through: raw <UInput> + a text column). The manifest also owns autoGeneratedFields (id, teamId, owner, createdAt, … — never declare these), reserved field/collection names, bundled (read by the meta module), and detects patterns for addon generator contributions. Full tables: sibling crouton-generation-reference. Adding a field type = a manifest change, not a CLI patch.

6. Invariants (compressed to pointers — read the canonical source, don't re-derive)

#	Invariant	Canonical source	Incident / why
1	Dep direction crouton-layout → crouton-core, never reverse (shared layout types live in core so feature packages contribute blocks dep-free)	packages/crouton-layout/CLAUDE.md ("HARD RULE")	reverse = cycle
2	Optional components via stub-priority, never resolveComponent()	root CLAUDE.md § Critical Gotchas	why: §3
3	Every collection team-scoped, no opt-out (§4)	the generated handlers themselves	tenancy leaks; API tests go red if teamId dropped (#791)
4	packages/ is edit-guarded (HARD GATE)	root CLAUDE.md § Packages Boundary; hook gate-package-edits.sh; flow → crouton-change-control	every consumer inherits the change
5	Never re-extend bundled auth/admin alongside core	packages/crouton-cli/CLAUDE.md	duplicate layers → SSR $setup.t is not a function
6	hub: { db: 'sqlite' }, never hub: { database: true }; NuxtHub = storage only, never deploy	root CLAUDE.md § Critical Gotchas	breaks schema.entry resolution + local migrations
7	Translatable fields required: false at the root column (real value in translations.{locale}.field; root is cache/fallback)	packages/crouton-cli/CLAUDE.md ("Why this matters")	NOT NULL root fails translation-only inserts
8	Layout is data (a LayoutTree in team-scoped layout_configs), not generated .vue	crouton-layout/server/database/schema/layoutConfigs.ts (code)	runtime-editable + diffable for the agent⇄human loop
9	Field types / capabilities are manifest-declared (§5) — one source, three consumers (CLI, MCP, meta module)	crouton.manifest.ts per package	hardcoded tables drift per consumer (#285)
10	Core's ensure-hub-blob module loads before @nuxthub/core; don't reorder core's modules	comment in packages/crouton-core/nuxt.config.ts	db: 'sqlite'-only apps still get blob

(Install/postinstall/typecheck invariants → sibling crouton-build-and-env; deploy invariants → crouton-ci-and-deploy-map.)

7. Known-weak points (plainly)

Weak point	Evidence	Status
Production-SSR 500 on collection pages — an internal data-fetch loses the auth cookie under nuxt preview, so the entire e2e harness runs against nuxt dev (source of its huge timeouts)	e2e/CLAUDE.md; tracked as #246 (per the e2e-smoke skill)	unresolved, load-bearing
getCroutonLayers() has zero in-repo callers — the meta module IS consumed, but its headline extends-assembly API is unexercised; apps hand-list extends (CLI-synced)	grep in re-verify block	open question — aspirational or deprecation candidate (owner call)
packages/crouton-core/CLAUDE.md is stale — title claims @fyit/crouton (the meta package), references dead names (nuxt-crouton-i18n, @crouton/auth)	the file itself	don't trust its import examples; full stale list → crouton-docs-trust-map
ISR routeRules contradiction — root CLAUDE.md recommends a wildcard /api/teams/*/... ISR rule that live code comments mark BROKEN	owner: crouton-diagnostics-index § "The ISR routeRules contradiction"	don't add such wildcard rules
CLI mirrors block sizing contracts by hand — crouton-cli/lib/compose-layout.ts "keep in sync" comment (whose own target list has drifted; live default registry is in crouton-layout/app/app.config.ts)	the file's comment	silent-drift hazard on minWidth/defaultSize changes
packages/crouton-layout/CLAUDE.md self-contradicts — marks server-side extraction pending while layout_configs schema + API exist on disk	files exist	trust the code

Provenance and maintenance

verified: 2026-07-03

Facts checked against the working tree (velo/core/crouton/auth/layout/cli configs + CLAUDE.mds, fixtures/minimal generated tree, e2e/CLAUDE.md). Issue numbers cited from discovery-report summaries — check the issue if load-bearing. Volatile facts live below, not in the prose:

ls packages | wc -l                                                             # package count (31 at verification)
grep -rln "modules: \['@fyit/crouton'\]" apps fixtures pocs 2>/dev/null | wc -l # meta-module consumers (15 at verification)
grep -n "extends" apps/velo/nuxt.config.ts                                      # extends chain still hand-listed?
grep -rn "getCroutonLayers" apps/*/nuxt.config.ts fixtures/*/nuxt.config.ts pocs/*/nuxt.config.ts  # still 0 callers?
ls packages/crouton-core/app/components/stubs/                                  # stub list (7 at verification)
grep -n "priority" packages/crouton-core/nuxt.config.ts                         # stubs still -1?
grep -n "500 under production SSR" e2e/CLAUDE.md                                # #246 still unresolved?
grep -n "Keep in sync" packages/crouton-cli/lib/compose-layout.ts               # CLI sizing-mirror comment still there?
node scripts/harness-stages.mjs packages/crouton-core                           # packages still edit-guarded/test-first?