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 | Two referents: (1) the whole framework; (2) the CLI (packages/crouton-cli, bin crouton) that generates collections. (The umbrella Nuxt module that used to live in packages/crouton was removed in #2290 — apps extend @fyit/crouton-core + addons instead) |
| 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:
- Package layer —
packages/ holds the crouton-* packages (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-devtools is a Nuxt module ("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).
- 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-devtools'], // the only crouton entry in `modules` (optional)
extends: [
'@fyit/crouton-core', '@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.
extends is the only package switch. An app turns a crouton package on by listing it in extends (hand-listed, kept in sync by the CLI's syncFrameworkPackages); crouton.config.js features is generation input, not a switch (#2286). The former umbrella Nuxt module (packages/crouton, listed under modules, with an extends-builder helper) was removed in #2290 — a Nuxt module can't add layers at runtime, so it never did more than wire runtimeConfig and warn.
2. The two-halves rule (pointer)
Canonical: this section (it lived in the meta package's CLAUDE.md until #2290 removed it). 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. Changing (#2278): a package with ownsCollections: true in its manifest ships both halves itself (sales first — packages/crouton-sales/collections/*); the CLI refuses to generate those collections into an app. Bookings, pages and assets still follow the two-halves rule until their slices land.
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 CLI's scaffold/doctor as "core already provides it"), 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, two consumers (CLI, MCP) | 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 |
packages/crouton-core/CLAUDE.md is partly stale — 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 -rn "modules: \[" apps/*/nuxt.config.ts fixtures/*/nuxt.config.ts pocs/*/nuxt.config.ts # only '@fyit/crouton-devtools' may appear as a crouton entry (umbrella module gone, #2290)
grep -n "extends" apps/velo/nuxt.config.ts # extends chain still hand-listed?
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?