cabloy 5.1.60 → 5.1.62

package/cabloy-docs/fullstack/openapi-to-sdk.md

@@ -1,10 +1,14 @@
 # Backend OpenAPI to Frontend SDK
 
-This page turns one of Cabloy’s most important fullstack collaboration paths into an explicit guide.
+This page is the **forward chain** deep dive for Cabloy’s bidirectional contract loop.
 
 ## Why this path matters
 
-Cabloy’s fullstack productivity depends heavily on a contract loop:
+In the bidirectional [Contract Loop Playbook](/fullstack/contract-loop-playbook), this page covers the **forward chain**:
+
+> [!NOTE]
+> The fullstack tutorial series intentionally uses a standalone `demo-student` sandbox so readers can experiment without colliding with the repo's real suite-owned `a-training/training-student` implementation.
+> This guide focuses on the current repo implementation as its forward-chain specimen.
 
 1. Vona emits backend API metadata through Swagger/OpenAPI
 2. Zova consumes that metadata to generate frontend SDKs and schema-aware helpers
@@ -12,7 +16,7 @@ Cabloy’s fullstack productivity depends heavily on a contract loop:
 
 This is one of the strongest AI-leverage paths in the repo because it reduces duplicated type work and keeps backend/frontend coordination closer to source truth.
 
-## The contract loop in practical terms
+## The forward chain in practical terms
 
 A useful split is:
 
@@ -20,7 +24,11 @@ A useful split is:
 - fullstack docs define the bridge from emitted contract to generated SDK
 - frontend docs define the consumption side of the generated contract
 
-That means this page is the fullstack contract-bridge page, not the backend authoring page and not the frontend usage page.
+That means this page is the forward-chain bridge page, not the backend authoring page and not the frontend usage page.
+
+If the changed source is actually a frontend-owned resource that backend consumers later depend on, switch to the reverse-chain guide: [Frontend Metadata Back to Backend](/fullstack/frontend-metadata-to-backend).
+
+If your real question is how one backend-owned row action becomes a visible frontend table action through metadata, page blocks, `tableCell` resources, and optionally generated API/model layers, continue with [Backend Metadata to Frontend Table Actions](/fullstack/backend-metadata-to-frontend-table-actions).
 
 ## Backend side: Vona emits the contract
 
@@ -37,6 +45,7 @@ For the deeper backend perspective, see:
 - [OpenAPI Guide](/backend/openapi-guide)
 - [Validation Guide](/backend/validation-guide)
 - [DTO Infer and Generation](/backend/dto-infer-generation)
+- [Backend Resource/Module Contract Chain](/backend/backend-resource-module-contract-chain)
 
 ## Frontend side: Zova consumes the contract
 
@@ -54,6 +63,65 @@ For the deeper frontend perspective, see:
 - [API Schema Guide](/frontend/api-schema-guide)
 - [SDK Guide](/frontend/sdk-guide)
 
+## Source-to-consumer chain
+
+If you want the shortest accurate mental model, use this forward chain:
+
+1. backend controller signatures define request and response entry surfaces
+2. backend DTO and entity fields shape named and shared contract structure
+3. validation rules and `v` helpers refine the machine-readable contract
+4. Vona emits OpenAPI output from those backend declarations
+5. Zova OpenAPI config decides which generated contract slice belongs to which frontend module
+6. frontend generation produces SDK and rest/schema-related contract output
+7. frontend code consumes the generated contract through:
+   - generated SDK methods
+   - schema-driven helpers
+   - `$sdk` and `$apiSchema`-adjacent runtime surfaces
+   - thin model facades and existing resource-owner consumers when the API belongs to an existing resource
+
+That means this bridge is not only “generate the SDK.”
+
+It is the whole path that moves backend-authored truth into frontend-usable contract material.
+
+## Which page owns which question?
+
+Use this split to avoid reading the wrong layer too deeply.
+
+### Backend authoring semantics
+
+Use these when the real question is how the backend contract is authored:
+
+- [Controller Guide](/backend/controller-guide)
+- [DTO Guide](/backend/dto-guide)
+- [DTO Infer and Generation](/backend/dto-infer-generation)
+- [OpenAPI Guide](/backend/openapi-guide)
+- [Backend Resource/Module Contract Chain](/backend/backend-resource-module-contract-chain)
+
+### Forward-chain bridge and regeneration workflow
+
+Use **this page** when the real question is:
+
+- how backend-authored truth crosses the stack boundary
+- which generation steps to run
+- where module ownership and regeneration decisions belong
+- how to keep frontend follow-up thin after regeneration
+
+### Frontend generation and usage setup
+
+Use these when the generated contract has already crossed the boundary and you are configuring or consuming it in Zova:
+
+- [OpenAPI SDK Guide](/frontend/openapi-sdk-guide)
+- [API Schema Guide](/frontend/api-schema-guide)
+- [SDK Guide](/frontend/sdk-guide)
+
+### Frontend runtime and deeper consumption internals
+
+Use these when the real question is how generated contract material is consumed inside Zova runtime layers:
+
+- [A-OpenAPI Under the Hood](/frontend/a-openapi-under-the-hood)
+- [ModelResource Internals Deep Dive](/frontend/model-resource-internals-deep-dive)
+- [Rest Resource Source Reading Map](/frontend/rest-resource-source-reading-map)
+
 ## Cabloy Basic workflow
 
 In the current public monorepo, Basic-specific Zova flavors include:
@@ -64,29 +132,74 @@ In the current public monorepo, Basic-specific Zova flavors include:
 Representative frontend-side contract-generation commands include:
 
 ```bash
-npm run zova :openapi:config demo-student
-npm run zova :openapi:generate demo-student
+npm run zova :openapi:config training-student
+npm run zova :openapi:generate training-student
 cd zova && npm run build:rest:cabloyBasicAdmin
 cd zova && npm run build:rest:cabloyBasicWeb
 ```
 
-A practical contract-loop sequence is:
+A practical forward-chain sequence is:
 
 1. author or change the backend contract
 2. emit or inspect backend OpenAPI output
-3. configure frontend module ownership if needed
-4. generate module-level OpenAPI SDK output
-5. run the rest build for the active Basic flavor when needed
-6. consume the generated contract from frontend code instead of re-declaring it manually
+3. if the frontend generator reads from a local Swagger endpoint, start the backend service first so the endpoint is reachable — in this repo, `npm run dev` is the normal path and exposes Swagger at `http://localhost:7102/swagger/json?version=V31`
+4. configure frontend module ownership if needed
+5. generate module-level OpenAPI SDK output
+6. run the rest build for the active flavor when needed
+7. consume the generated contract from frontend code instead of re-declaring it manually
+8. keep frontend follow-up thin by wrapping generated consumers with semantic facades instead of re-declaring the contract
+9. when the custom API still belongs to an existing resource, reuse the existing resource-owner instead of creating a competing cache owner
 
 A practical responsibility split is:
 
 - project-level OpenAPI config decides where the backend Swagger/OpenAPI source comes from
 - module-level OpenAPI config decides which generated contract slice belongs to which frontend module
+- module-level ownership should be declared explicitly with `operations.match` or `operations.ignore`
+
+If both `operations.match` and `operations.ignore` are empty, frontend SDK generation should fail fast instead of generating a large unrelated contract surface for the module. That fail-fast behavior helps both developers and AI agents notice the missing ownership boundary immediately and repair the config before the wrong SDK slice is generated.
 
 A practical regeneration rule is:
 
 - if the backend contract changed, prefer regenerating the SDK/rest layer before hand-editing frontend request code
+- if `npm run zova :openapi:generate ...` fails because the local Swagger source is unavailable, first start the backend service and confirm `http://localhost:7102/swagger/json?version=V31` is reachable before treating generation as broken
+- if the generated consumer path is already correct, but frontend behavior still looks stale, stop patching generated files and diagnose consumer drift or local dependency drift instead
+
+## `training-student` as a compact forward-chain specimen
+
+A compact specimen helps make the bridge more concrete.
+
+A practical `training-student` forward chain looks like this:
+
+1. backend contract truth changes in places such as:
+   - `controller/student.ts`
+   - `entity/student.tsx`
+   - `dto/studentCreate.tsx`
+   - `dto/studentUpdate.tsx`
+   - `dto/studentView.tsx`
+   - `dto/studentSelectReq.tsx`
+2. backend OpenAPI output changes because those controller/DTO/entity/validation surfaces changed
+3. frontend OpenAPI generation refreshes the module-owned consumer slice
+4. flavor-specific rest output is rebuilt when the workflow depends on generated rest output
+5. frontend code consumes the generated result through module-owned SDK/schema surfaces, then keeps follow-up thin with semantic wrappers or existing resource owners
+
+This is the main point of the forward chain:
+
+> backend contract truth moves first, generated handoff moves second, frontend consumers stay thin and downstream.
+
+## Thin frontend follow-up after generation
+
+After the generated contract crosses the boundary, the best frontend move is usually **not** to recreate the contract by hand.
+
+A practical split is:
+
+- use generated SDKs when the module already follows the OpenAPI-generated API-service path
+- use schema-driven helpers when the workflow is contract/schema oriented
+- use thin model facades when the UI needs business semantics over generated APIs
+- reuse the existing resource-owner when the custom API still belongs to the same resource
+
+That last point matters especially for resource-driven pages.
+
+If the endpoint still belongs to an existing business resource, prefer keeping `ModelResource` or the existing resource-owner story as the stable state owner rather than introducing a competing second owner.
 
 ## Cabloy Start workflow
 
@@ -103,6 +216,17 @@ Before documenting or automating this path for Start, confirm:
 2. the Start repo’s `package.json`
 3. the exact frontend flavor names and generated output paths
 
+## Where to read next
+
+- If your next question is still on the backend authoring side, continue with [OpenAPI Guide](/backend/openapi-guide), [Backend Contract Emission Specimen](/backend/backend-contract-emission-specimen), [Backend Contract Emission Output Inspection](/backend/backend-contract-emission-output-inspection), [DTO Guide](/backend/dto-guide), [DTO Infer and Generation](/backend/dto-infer-generation), and [Backend Resource/Module Contract Chain](/backend/backend-resource-module-contract-chain).
+- If your next question is about frontend SDK setup and module ownership, continue with [OpenAPI SDK Guide](/frontend/openapi-sdk-guide).
+- If your next question is about what generated contract consumption looks like in one practical frontend path, continue with [Generated Contract Consumption Specimen](/frontend/generated-contract-consumption-specimen), then choose [Generated Contract Consumption: List Branch](/frontend/generated-contract-consumption-list-branch) or [Generated Contract Consumption: Entry Branch](/frontend/generated-contract-consumption-entry-branch) as needed.
+- If your next question becomes one mixed Student row-action thread spanning backend metadata, generated contract follow-up, and frontend action resources, continue with [Backend Metadata to Frontend Table Actions Source Reading Map](/fullstack/backend-metadata-to-frontend-table-actions-source-reading-map).
+- If your next question is about schema-driven frontend consumption, continue with [API Schema Guide](/frontend/api-schema-guide).
+- If your next question is about the lower-level frontend runtime under generated OpenAPI/schema usage, continue with [A-OpenAPI Under the Hood](/frontend/a-openapi-under-the-hood).
+- If your next question is about resource-owner or model-level consumption after regeneration, continue with [ModelResource Internals Deep Dive](/frontend/model-resource-internals-deep-dive) and [Rest Resource Source Reading Map](/frontend/rest-resource-source-reading-map).
+- If the problem is actually about deciding which direction the contract loop is moving, return to [Contract Loop Playbook](/fullstack/contract-loop-playbook).
+
 ## Implementation checks for backend-to-frontend contract changes
 
 When changing a backend API contract, ask:

package/cabloy-docs/fullstack/suites-and-modules.md

@@ -0,0 +1,333 @@
+# Suites and Modules
+
+This guide explains how to think about suites and modules in the current Cabloy monorepo.
+
+Use it when you need to answer these questions clearly:
+
+1. what a suite is
+2. when to create a suite instead of only a module
+3. how suite naming works
+4. where suite-owned modules should live
+5. which CLI workflows should create the structure
+
+## Why suites exist
+
+As a project evolves, business capabilities do not usually grow as one isolated feature at a time.
+
+In real business scenarios, one business domain often requires multiple related modules that evolve together. A training domain, for example, may later grow into modules for:
+
+- training-student
+- training-course
+- training-record
+- training-attendance
+- training-certificate
+
+Because of that, the default architectural decision should usually start from a **suite** rather than from an isolated standalone module.
+
+A suite is the business-level composition boundary for a domain. A module is the feature-level implementation boundary inside that domain.
+
+A practical mental model is:
+
+- use a **suite** for the business domain
+- use **modules** for the concrete capabilities inside that domain
+
+## Suite and module roles
+
+The two units serve different jobs.
+
+### Suite
+
+A suite groups related modules into one larger business scenario or architectural area.
+
+That grouping matters because it gives the domain:
+
+- a stable ownership boundary
+- a clear place for future module growth
+- consistent source-tree organization
+- a shared naming anchor across backend and frontend
+
+### Module
+
+A module is the concrete implementation unit for one feature area.
+
+That usually means a module owns the code for things such as:
+
+- backend controllers, services, entities, DTOs, and models
+- frontend pages, components, APIs, models, and metadata
+- module-local config, locale, and other scoped resources
+
+A useful rule is:
+
+- the **suite** answers "which business domain does this belong to?"
+- the **module** answers "which capability inside that domain owns this work?"
+
+## Recommended decision path
+
+In the current Cabloy monorepo, the preferred decision path is:
+
+1. identify the business domain
+2. create a suite for that domain
+3. create one or more modules inside the suite
+4. continue feature growth inside those suite-owned modules
+
+In other words, for real business work, **suite-first** is usually the best choice.
+
+### When suite-first is the default
+
+Create a suite first when:
+
+- the work belongs to a real business domain
+- the domain is expected to grow beyond one small feature
+- backend and frontend will both evolve around the same domain
+- you want to avoid later structural migration from standalone modules into a domain boundary
+
+In practice, this is the normal path for long-lived product work.
+
+### When a standalone module is still acceptable
+
+A standalone module can still be acceptable for cases such as:
+
+- very small experiments
+- disposable demos
+- isolated utilities that are intentionally not the start of a larger domain
+- short tutorials where introducing a domain suite would add noise
+
+But this should be the exception, not the default path for real business architecture.
+
+## Naming
+
+Suite naming follows the same high-level model on both sides:
+
+```text
+Vona: FullName  = vona-suite-{providerId}-{suiteName}
+Zova: FullName  = zova-suite-{providerId}-{suiteName}
+ShortName      = {providerId}-{suiteName}
+```
+
+### Important suiteName rule
+
+In this repository, `suiteName` must follow this rule:
+
+- `suiteName` must use lowercase English letters only
+- `suiteName` must not contain another `-`
+
+This rule matters because the `-` already separates `{providerId}` and `{suiteName}` in the short name.
+
+So the supported shape is:
+
+```text
+{providerId}-{suiteName}
+```
+
+not:
+
+```text
+{providerId}-{part1-part2}
+```
+
+### Examples
+
+Representative examples from the current repo include:
+
+- `a-home`
+- `a-demo`
+- `cabloy-basic`
+
+These can be read as:
+
+- `a-home` -> providerId: `a`, suiteName: `home`
+- `a-demo` -> providerId: `a`, suiteName: `demo`
+- `cabloy-basic` -> providerId: `cabloy`, suiteName: `basic`
+
+For a training-oriented suite, the valid short name is:
+
+- `a-training`
+
+where:
+
+- providerId: `a`
+- suiteName: `training`
+
+A practical rule is:
+
+- keep `suiteName` simple, lowercase, and single-segment
+- do not add another `-` inside `suiteName`
+- if you need more semantic detail, express it through module names inside the suite rather than by making the suite name longer
+
+## Supported directory pattern
+
+To keep the code style consistent and reduce cognitive overhead, this repository supports only one suite layout for normal authoring work:
+
+- **suite-contained modules**
+
+That means when a suite exists, its modules belong under that suite.
+
+### Backend pattern
+
+```text
+vona/src/suite/<suite>/modules/<module>/
+```
+
+### Frontend pattern
+
+```text
+zova/src/suite/<suite>/modules/<module>/
+```
+
+### Example
+
+```text
+vona/src/suite/a-training/
+├── modules/
+│  ├── training-student/
+│  ├── training-course/
+│  └── training-record/
+└── package.json
+```
+
+```text
+zova/src/suite/a-training/
+├── modules/
+│  ├── training-student/
+│  ├── training-course/
+│  └── training-record/
+└── package.json
+```
+
+## Unsupported pattern for normal project authoring
+
+For consistency, do not treat a suite as a loose composition package that only depends on standalone modules located elsewhere.
+
+In other words, do not use a suite as a separate conceptual wrapper while keeping its real modules outside the suite tree.
+
+Use the suite as the real ownership boundary, and keep the suite-owned modules physically inside:
+
+- `vona/src/suite/<suite>/modules/`
+- `zova/src/suite/<suite>/modules/`
+
+This keeps the source tree easier to read and avoids extra mental branching about whether a module is only logically related to a suite or actually owned by it.
+
+## CLI-first workflow
+
+Do not scaffold suite/module structure manually when the CLI already supports it.
+
+Use the framework CLI first, then make only the minimal follow-up edits that the task still needs.
+
+### Create a backend suite
+
+```bash
+npm run vona :create:suite suiteName
+```
+
+### Create a frontend suite
+
+```bash
+npm run zova :create:suite suiteName
+```
+
+### Create a backend module inside a suite
+
+```bash
+npm run vona :create:module moduleName -- --suite=suiteName
+```
+
+### Create a frontend module inside a suite
+
+```bash
+npm run zova :create:module moduleName -- --suite=suiteName
+```
+
+A practical fullstack rule is:
+
+- use `npm run vona` to create the backend side of the domain
+- use `npm run zova` to create the frontend side of the domain
+- for a real business domain, create the suite first on both sides, then create the suite-owned modules
+
+## Recommended workflow for real business domains
+
+A practical suite-first workflow is:
+
+1. decide the domain boundary
+2. choose a valid suite short name
+3. create the suite in Vona
+4. create the suite in Zova
+5. create the first backend and frontend modules inside that suite
+6. continue all later domain growth inside the same suite
+
+For example, for a training domain:
+
+```bash
+npm run vona :create:suite a-training
+npm run zova :create:suite a-training
+
+npm run vona :create:module training-student -- --suite=a-training
+npm run zova :create:module training-student -- --suite=a-training
+```
+
+Later domain growth can continue with modules such as:
+
+- training-course
+- training-record
+- training-attendance
+
+This keeps the domain boundary stable while the capabilities inside it expand.
+
+## How to choose between a suite and only a module
+
+Use this rule:
+
+### Choose a suite first when
+
+- the work belongs to a real domain
+- more related modules are likely
+- the feature will grow across backend and frontend
+- you want the structure to remain stable as the domain expands
+
+### Choose only a standalone module when
+
+- the work is intentionally isolated
+- the scope is very small
+- the code is exploratory or disposable
+- creating a domain suite would add more ceremony than value
+
+For most real business scenarios, the correct answer is to create the suite first.
+
+## Relationship to repo structure
+
+This guide should be read together with:
+
+- [Package Map](/reference/package-map)
+- [Backend Directory Structure](/reference/backend-directory-structure)
+- [Frontend Directory Structure](/reference/frontend-directory-structure)
+- [Backend CLI](/backend/cli)
+- [Frontend CLI](/frontend/cli)
+- [Fullstack CLI](/fullstack/cli)
+
+A practical split is:
+
+- this page explains the decision model for suites and modules
+- the reference pages explain where those units live in the repo
+- the CLI pages explain how to generate them correctly
+
+## Verification
+
+After creating or restructuring suites and modules, verify with the narrowest useful checks first.
+
+Typical checks include:
+
+```bash
+npm run vona :
+npm run zova :
+
+npm run deps:vona
+npm run deps:zova
+
+npm run tsc
+```
+
+If the change affects broader cross-stack output, also use the relevant build flow from the repo root.
+
+The key rule is:
+
+- verify that the suite and module were created in the intended structural location
+- verify that later commands and dependency refresh flows still recognize that structure

package/cabloy-docs/fullstack/tutorial-1-first-module.md

@@ -52,6 +52,8 @@ Usage notes:
 - use `npm run vona :create:module` for the backend module boundary
 - use `npm run zova :create:module` for the frontend module boundary
 - use an empty `--suite=` when you want an independent module rather than a suite-owned module
+- this tutorial intentionally uses a standalone `demo-student` sandbox so readers can experiment without colliding with the repo's real `a-training/training-student` example
+- for the normal suite-first domain decision path, see [Suites and Modules](/fullstack/suites-and-modules)
 - rerun `npm run dev` after module creation so the local workflow picks up the new modules cleanly
 
 ## Generated or affected files
@@ -82,6 +84,7 @@ At this stage, the key idea is ownership, not business logic yet.
 - the backend module root is where the Student resource, entity, DTOs, controller, tests, and backend metadata will live later
 - the frontend module root is where generated OpenAPI output, model helpers, render resources, and frontend metadata will live later
 - the frontend `.metadata` entrypoint is part of how the module exposes its local registration surface
+- because this tutorial path is intentionally standalone, you can compare its generated result against the repo's real suite-owned `a-training/training-student` implementation without overwriting it
 
 A good beginner rule is: do not rush into editing business logic until you can explain which module roots were created and why they will own the next tutorials.
 

package/cabloy-docs/fullstack/tutorial-2-first-crud.md

@@ -27,6 +27,10 @@ Once the module exists, this is the next useful step because the prompt can driv
 
 That keeps the conversation focused on the generated business thread rather than on repetitive scaffolding details.
 
+> [!NOTE]
+> This tutorial continues the standalone `demo-student` sandbox from Tutorial 1.
+> That sandbox is intentional: it lets you run the full tutorial flow without colliding with the repo's real suite-owned `a-training/training-student` implementation.
+
 ## CLI commands to inspect/use
 
 Inspect the CRUD family first:

package/cabloy-docs/fullstack/tutorial-3-frontend-metadata-sharing.md

@@ -2,10 +2,14 @@
 
 <Badge type="info" text="Basic" />
 
-In this tutorial, one prompt lets AI show the reverse direction of Cabloy’s fullstack contract loop: backend field metadata can reference frontend render resources.
+In this tutorial, one prompt lets AI show the **reverse chain** of Cabloy’s fullstack contract loop: backend field metadata can reference frontend render resources.
 
 You start with the simplest path first: reuse the existing built-in rendering resources for the `level` field.
 
+> [!NOTE]
+> This tutorial still uses the standalone `demo-student` sandbox introduced in Tutorial 1.
+> Keep that sandbox separate from the repo's real suite-owned `a-training/training-student` example so you can experiment and compare the two paths side by side.
+
 ## Goal
 
 By the end of this tutorial, you will understand:
@@ -19,7 +23,7 @@ By the end of this tutorial, you will understand:
 Give AI a prompt like this:
 
 ```text
-Please add a level field to the Student resource. It should be a number field with these enum values:
+Please add a level field to the Student resource. It should be a required number field with these enum values:
 
 - 1: beginner
 - 2: intermediate