cabloy 5.1.61 → 5.1.63

package/cabloy-docs/backend/backend-resource-module-contract-chain.md

@@ -0,0 +1,323 @@
+# Backend Resource/Module Contract Chain
+
+This page is a focused deep dive into one narrow backend question:
+
+> how does one real Vona backend module become a working contract chain from generated metadata through controller, service, model, entity, and DTO layers?
+
+It uses the current `training-student` module as the specimen.
+
+Use this page together with:
+
+- [Backend Source Reading Roadmap](/backend/backend-source-reading-roadmap)
+- [Vona Source Reading Map](/backend/vona-source-reading-map)
+- [Controller Guide](/backend/controller-guide)
+- [Service Guide](/backend/service-guide)
+- [Model Guide](/backend/model-guide)
+- [Entity Guide](/backend/entity-guide)
+- [DTO Guide](/backend/dto-guide)
+- [OpenAPI Guide](/backend/openapi-guide)
+- [CRUD Workflow](/backend/crud-workflow)
+
+> [!TIP]
+> **Backend contract-reading path**
+>
+> 1. **[Backend Source Reading Roadmap](/backend/backend-source-reading-roadmap)** — choose the right backend reading cluster
+> 2. **[Vona Source Reading Map](/backend/vona-source-reading-map)** — find the shortest file-order path into source
+> 3. **[Backend Resource/Module Contract Chain](/backend/backend-resource-module-contract-chain)** — walk one concrete module through the whole contract chain
+>
+> **You are here:** step 3.
+> **Previous recommended pages:** [Backend Source Reading Roadmap](/backend/backend-source-reading-roadmap) and [Vona Source Reading Map](/backend/vona-source-reading-map).
+
+## Why this page exists
+
+The current backend docs already explain each layer well:
+
+- controllers define HTTP-facing contracts
+- services orchestrate business flow
+- models own persistence-facing behavior
+- entities shape the field contract
+- DTOs shape named request and response artifacts
+
+The new backend roadmap and source-reading map also help readers choose the right topic cluster and source-file order.
+
+What was still missing was one page that stays narrow and shows how those layers connect in one real module.
+
+This page fills that gap.
+
+It is not a replacement for the existing backend guides. It is a specimen page that shows how the handoffs connect in one concrete thread.
+
+## Shortest accurate mental model
+
+The `training-student` contract chain is easiest to read like this:
+
+1. `src/index.ts` exposes the module reading entry
+2. `src/.metadata/index.ts` is the generated contract-registration hub
+3. `controller/student.ts` defines the resource-facing HTTP actions
+4. `service/student.ts` orchestrates the business handoff
+5. `model/student.ts` binds persistence behavior to the entity
+6. `entity/student.tsx` defines the shared field contract
+7. `dto/*.tsx` defines the named transport artifacts around that contract
+
+The most important reading trick is this:
+
+> do not skip `.metadata/index.ts`.
+
+For this kind of backend source-reading task, the generated metadata file is part of the readable contract surface, not only an implementation detail.
+
+## Source-confirmed reading path
+
+Read the `training-student` module in this order:
+
+1. `vona/src/suite/a-training/modules/training-student/src/index.ts`
+2. `vona/src/suite/a-training/modules/training-student/src/.metadata/index.ts`
+3. `vona/src/suite/a-training/modules/training-student/src/controller/student.ts`
+4. `vona/src/suite/a-training/modules/training-student/src/service/student.ts`
+5. `vona/src/suite/a-training/modules/training-student/src/model/student.ts`
+6. `vona/src/suite/a-training/modules/training-student/src/entity/student.tsx`
+7. `vona/src/suite/a-training/modules/training-student/src/dto/studentCreate.tsx`
+8. `vona/src/suite/a-training/modules/training-student/src/dto/studentUpdate.tsx`
+9. `vona/src/suite/a-training/modules/training-student/src/dto/studentView.tsx`
+10. `vona/src/suite/a-training/modules/training-student/src/dto/studentSelectReq.tsx`
+11. `vona/src/suite/a-training/modules/training-student/src/dto/studentSelectResItem.tsx`
+12. `vona/src/suite/a-training/modules/training-student/src/dto/studentSelectRes.tsx`
+
+That order starts from the public module entry, foregrounds the generated registration hub early, then descends through the authored runtime layers and the named DTO artifacts.
+
+## Contract chain by layer
+
+### 1. `src/index.ts`: the public module entry
+
+`vona/src/suite/a-training/modules/training-student/src/index.ts` is intentionally small:
+
+- it re-exports `./.metadata/locales.ts`
+- it re-exports `./.metadata/index.ts`
+
+That tells you something important immediately.
+
+The generated metadata layer is not hidden away from the module’s reading path. It is part of the public module surface that other code and readers are expected to consume.
+
+For source reading, that means:
+
+- start at `index.ts` to confirm the module entry
+- then move into `.metadata/index.ts` before diving straight into controller/service/model files
+
+### 2. `src/.metadata/index.ts`: the generated contract-registration hub
+
+This is the key file for understanding the full chain.
+
+`vona/src/suite/a-training/modules/training-student/src/.metadata/index.ts` shows, in one generated surface, how the module is registered across several backend layers at once.
+
+Representative things it exposes include:
+
+- entity registrations such as `IEntityRecord` and `ITableRecord`
+- model registrations such as `IModelRecord` and `IModelClassRecord`
+- service registrations such as `IServiceRecord`
+- controller registrations such as `IControllerRecord`
+- DTO registrations such as `IDtoRecord`
+- meta registrations such as `IMetaRecord`
+- API path typings such as `IApiPathGetRecord`, `IApiPathPostRecord`, `IApiPathPatchRecord`, and `IApiPathDeleteRecord`
+- resource registration through `IResourceRecord`
+- scope wiring through `IBeanScopeRecord`, `IBeanScopeContainer`, and the module scope class
+
+This matters because the contract chain is not only a call stack.
+
+It is also a generated registration system that ties together:
+
+- bean names
+- onion names
+- typed scope access
+- route paths
+- resource ownership
+- DTO availability
+
+A practical reading takeaway is:
+
+> if you want to understand how the module is wired as a backend contract surface, `.metadata/index.ts` is the fastest summary file in the module.
+
+### 3. `controller/student.ts`: the HTTP and resource-facing entry layer
+
+`vona/src/suite/a-training/modules/training-student/src/controller/student.ts` is the HTTP-facing contract surface.
+
+Representative source facts from this file:
+
+- the class is decorated with `@Controller<IControllerOptionsStudent>('student')`
+- the class is also decorated with `@Resource()`
+- CRUD actions are declared with `@Web.post()`, `@Web.get()`, `@Web.get(':id')`, `@Web.patch(':id')`, and `@Web.delete(':id')`
+- request shapes use `@Arg.body(...)`, `@Arg.param(...)`, and `@Arg.filter(...)`
+- actions delegate to `this.scope.service.student`
+
+This is the layer where several concerns meet in one place:
+
+- route and action declaration
+- request extraction and typing
+- response contract exposure
+- handoff to service orchestration
+
+A good reading pattern here is:
+
+- read the action signatures first
+- note which DTOs or typed parameters they reference
+- then follow the delegation to the service layer
+
+### 4. `service/student.ts`: the orchestration handoff layer
+
+`vona/src/suite/a-training/modules/training-student/src/service/student.ts` is intentionally thin.
+
+Representative source facts:
+
+- the class is decorated with `@Service()`
+- `create(...)` delegates to `this.scope.model.student.insert(...)`
+- `select(...)` delegates to `this.scope.model.student.selectAndCount(...)`
+- `view(...)` delegates to `this.scope.model.student.getById(...)`
+- `update(...)` delegates to `this.scope.model.student.updateById(...)`
+- `delete(...)` delegates to `this.scope.model.student.deleteById(...)`
+
+That thinness is part of the point.
+
+This specimen makes the layer boundary very easy to see:
+
+- controller owns the HTTP-facing resource surface
+- service owns the business-oriented handoff
+- model owns the persistence-facing behavior
+
+So even though this particular service is small, it is still important for reading the chain correctly.
+
+### 5. `model/student.ts`: the persistence binding
+
+`vona/src/suite/a-training/modules/training-student/src/model/student.ts` is also compact.
+
+Representative source fact:
+
+- `@Model<IModelOptionsStudent>({ entity: EntityStudent })`
+
+This is the bridge from service-layer orchestration into entity-backed ORM behavior.
+
+The main point here is not complexity. It is ownership.
+
+The file shows that persistence behavior is not encoded in the controller and not declared ad hoc in the service. It is bound through the model/entity pairing.
+
+That is why this layer belongs in the contract chain even when the class body is short.
+
+### 6. `entity/student.tsx`: the shared field-contract surface
+
+`vona/src/suite/a-training/modules/training-student/src/entity/student.tsx` is where field structure, validation-facing metadata, OpenAPI-facing metadata, and UI-related render metadata meet.
+
+Representative source facts:
+
+- the entity is decorated with `@Entity<IEntityOptionsStudent>('trainingStudent', ...)`
+- base field metadata is configured in `fields`
+- domain fields such as `name`, `description`, and `level` use `@Api.field(...)`
+- `studentLevelSchema` and `studentLevelItems` define a concrete field-level contract for the `level` field
+- `ZovaRender.field(...)` and `ZovaRender.cell(...)` are attached directly to the field metadata
+
+This is a strong example of the Cabloy contract loop in practice.
+
+The same field surface participates in:
+
+- validation-oriented structure
+- OpenAPI metadata
+- named DTO derivation
+- downstream UI/render metadata
+
+A practical reading takeaway is:
+
+> the entity is not only a persistence record. It is one of the main shared contract surfaces in the backend thread.
+
+### 7. `dto/*.tsx`: the named transport artifacts
+
+The DTO files turn the shared field contract into named request and response artifacts for specific operations.
+
+A useful way to read the `training-student` DTO family is by operation type.
+
+#### Create / update / view DTOs
+
+These files are the clearest operation-facing transport artifacts:
+
+- `dto/studentCreate.tsx`
+- `dto/studentUpdate.tsx`
+- `dto/studentView.tsx`
+
+Representative source facts:
+
+- `DtoStudentCreate` extends `$Dto.create(() => ModelStudent)`
+- `DtoStudentUpdate` extends `$Dto.update(() => ModelStudent)`
+- `DtoStudentView` extends `$Dto.get(() => ModelStudent)`
+
+These files show that named DTO artifacts do not have to restate every field manually when the framework can derive the contract shape from the model/entity thread.
+
+#### Query and list-response DTOs
+
+For the read/list side, these files are especially important:
+
+- `dto/studentSelectReq.tsx`
+- `dto/studentSelectResItem.tsx`
+- `dto/studentSelectRes.tsx`
+
+`studentSelectReq.tsx` is a strong specimen because it shows query/filter contract shaping that is more than a bare type alias.
+
+Representative source facts:
+
+- it uses `@Dto({ openapi: { filter: { table: 'trainingStudent' } }, fields: { ... } })`
+- it extends `$Dto.queryPage(EntityStudent, ['name', 'level', 'createdAt'])`
+- `level` uses a preprocess step so string query input can be normalized before schema validation
+- `createdAt` uses `v.filterTransform('a-web:dateRange')`
+
+That makes it a useful example of how request/filter contracts can:
+
+- stay tied to entity-derived structure
+- still add operation-specific filter shaping and transform behavior
+
+`studentSelectResItem.tsx` is useful for a different reason.
+
+It shows that a list-row response DTO can still participate in the broader contract loop through response-facing metadata such as:
+
+- block metadata
+- table action metadata
+- row action render hints
+
+Finally, `studentSelectRes.tsx` shows the aggregate response wrapper for the list result:
+
+- `DtoStudentSelectRes` extends `$Dto.listAndCount(DtoStudentSelectResItem)`
+
+So the list-response chain is not one file only. It is:
+
+1. one query/filter request DTO
+2. one row-item DTO
+3. one list-and-count response DTO
+
+## What this page does not re-explain
+
+This page deliberately does **not** re-teach the full semantics of each layer.
+
+For the broader explanations, continue with:
+
+- [Controller Guide](/backend/controller-guide) for controller decorators and route behavior
+- [Service Guide](/backend/service-guide) for service access patterns and orchestration styles
+- [Model Guide](/backend/model-guide) for persistence behavior and ORM-facing semantics
+- [Entity Guide](/backend/entity-guide) for field metadata and entity design rules
+- [DTO Guide](/backend/dto-guide) for DTO design, mapped-class tools, and inference choices
+- [OpenAPI Guide](/backend/openapi-guide) for contract emission and downstream consumption
+- [CRUD Workflow](/backend/crud-workflow) for generator-first creation of the backend thread
+
+This page only owns the specimen-level question:
+
+- how the layers connect
+- where the generated metadata hub fits
+- which file should you open next in one real module
+
+## Where to read next
+
+- If you need the broader chooser page first, return to [Backend Source Reading Roadmap](/backend/backend-source-reading-roadmap).
+- If you need more backend file-order reading paths, continue with [Vona Source Reading Map](/backend/vona-source-reading-map).
+- If your next question is about DTO mechanics or derivation, continue with [DTO Guide](/backend/dto-guide) and [DTO Infer and Generation](/backend/dto-infer-generation).
+- If your next question is about generator-created backend threads, continue with [CRUD Workflow](/backend/crud-workflow).
+- If you want a proof-oriented or symptom-first companion for the backend source-reading path itself, continue with [Backend Source Reading Verify Playbook](/backend/backend-source-reading-verify-playbook) and [Backend Source Reading Debug Checklist](/backend/backend-source-reading-debug-checklist).
+- If your next question is about downstream contract emission, continue with [Backend Contract Emission Source Reading Map](/backend/backend-contract-emission-source-reading-map), [OpenAPI Guide](/backend/openapi-guide), and [Backend OpenAPI to Frontend SDK](/fullstack/openapi-to-sdk).
+
+## Final takeaway
+
+The fastest way to understand one Vona backend module accurately is not to jump straight from controller to ORM details.
+
+Start from the public module entry, read the generated metadata hub early, then descend through controller -> service -> model -> entity -> DTO.
+
+That reading order makes the contract chain visible as one connected backend surface instead of a set of isolated files.

package/cabloy-docs/backend/backend-source-reading-debug-checklist.md

@@ -0,0 +1,173 @@
+# Backend Source Reading Debug Checklist
+
+This page is a symptom-first diagnostic companion for one narrow backend question:
+
+> something in the backend source-reading path looks wrong; which backend layer is the first failure?
+
+Use this page together with:
+
+- [Backend Source Reading Roadmap](/backend/backend-source-reading-roadmap)
+- [Vona Source Reading Map](/backend/vona-source-reading-map)
+- [Backend Resource/Module Contract Chain](/backend/backend-resource-module-contract-chain)
+- [Backend Contract Emission Specimen](/backend/backend-contract-emission-specimen)
+- [Backend Contract Emission Source Reading Map](/backend/backend-contract-emission-source-reading-map)
+- [Backend Contract Emission Output Inspection](/backend/backend-contract-emission-output-inspection)
+- [Backend Source Reading Verify Playbook](/backend/backend-source-reading-verify-playbook)
+
+> [!TIP]
+> **Backend source-reading diagnosis path**
+>
+> 1. **[Backend Source Reading Roadmap](/backend/backend-source-reading-roadmap)** — choose the backend source-reading branch
+> 2. **[Backend Source Reading Verify Playbook](/backend/backend-source-reading-verify-playbook)** — use first when you want to prove the path layer by layer
+> 3. **[Backend Source Reading Debug Checklist](/backend/backend-source-reading-debug-checklist)** — use this when something already looks wrong and you need the first failing layer
+>
+> **You are here:** step 3.
+> **Previous recommended pages:** [Backend Source Reading Roadmap](/backend/backend-source-reading-roadmap) and [Backend Source Reading Verify Playbook](/backend/backend-source-reading-verify-playbook).
+
+## Why this page exists
+
+The current backend source-reading family already gives you:
+
+- a chooser page
+- a broad file-order map
+- a module-wiring specimen
+- an emission family
+- a proof-oriented verify playbook
+
+What was still missing was one symptom-first page.
+
+This page fills that gap.
+
+It is not another concept page and not another source-order map. It is the checklist for isolating the first failing backend source-reading layer.
+
+## Shared symptom: generated/module surface missing or stale
+
+Start here when the problem looks earlier than either the module-wiring branch or the emission branch.
+
+Primary anchors:
+
+- `vona/src/suite/a-training/modules/training-student/src/index.ts`
+- `vona/src/suite/a-training/modules/training-student/src/.metadata/index.ts`
+
+What to inspect first:
+
+- does the module entry still re-export the generated surfaces you expect?
+- does `.metadata/index.ts` still expose the expected generated registration surface at all?
+- is the problem really in generated/module surface visibility rather than in authored controller/service/model/entity/DTO code?
+
+If this layer is already wrong, do not continue into the branch-specific diagnosis yet.
+
+## Module-wiring branch symptoms
+
+Only enter this branch when the issue is clearly about how one backend module is wired.
+
+Primary anchors:
+
+- `vona/src/suite/a-training/modules/training-student/src/controller/student.ts`
+- `vona/src/suite/a-training/modules/training-student/src/service/student.ts`
+- `vona/src/suite/a-training/modules/training-student/src/model/student.ts`
+- `vona/src/suite/a-training/modules/training-student/src/entity/student.tsx`
+- `vona/src/suite/a-training/modules/training-student/src/dto/*.tsx`
+
+Typical failures to classify:
+
+### A. Controller/service/model/entity responsibilities no longer line up
+
+Check:
+
+- whether the controller still delegates through the expected service/model path
+- whether the entity and DTO source truth still match the intended resource/module chain
+- whether the module-wiring specimen page still reflects the actual code path
+
+### B. Generated registration no longer reflects the expected module/resource chain
+
+Check:
+
+- whether `.metadata/index.ts` still exposes the expected controller/model/service/entity/DTO registrations together
+- whether the backend source-reading family is now out of sync with the actual generated module surface
+
+If this branch remains unclear, return to [Backend Resource/Module Contract Chain](/backend/backend-resource-module-contract-chain) before escalating further.
+
+## Emission branch symptoms
+
+Only enter this branch when the issue is clearly about emitted backend contract truth.
+
+Primary anchors:
+
+- `vona/src/suite/a-training/modules/training-student/src/controller/student.ts`
+- `vona/src/suite/a-training/modules/training-student/src/dto/studentSummary.tsx`
+- `vona/src/suite/a-training/modules/training-student/src/.metadata/index.ts`
+- emitted output surface already used in docs:
+  - `http://localhost:7102/swagger/json?version=V31`
+
+Typical failures to classify:
+
+### A. Emitted path missing or stale
+
+Check:
+
+- whether the controller still declares the intended action path
+- whether `.metadata/index.ts` still exposes the expected generated route record
+- whether the emitted output still includes the expected path
+
+### B. Emitted DTO shape no longer matches expectation
+
+Check:
+
+- whether the named DTO still matches the intended response shape
+- whether the emitted schema still reflects that DTO truth
+
+### C. Metadata record and emitted output no longer agree
+
+Check:
+
+- whether the generated registry and the emitted output diverged
+- whether the issue is still backend-side and should not yet escalate to frontend bridge debugging
+
+If this branch remains unclear, return to [Backend Contract Emission Specimen](/backend/backend-contract-emission-specimen) and [Backend Contract Emission Output Inspection](/backend/backend-contract-emission-output-inspection) before escalating further.
+
+## Classify the failure last
+
+Only after the branch-local checks should you classify the problem as:
+
+- shared generated/module surface issue
+- module-wiring issue
+- emission issue
+- downstream bridge/generation issue
+
+A practical rule is:
+
+> do not jump into fullstack forward-bridge or frontend debugging until the backend source-reading path itself already looks correct.
+
+## What this page does not re-explain
+
+This page deliberately does **not** re-teach:
+
+- the conceptual backend overview -> see [Backend (Vona)](/backend/introduction)
+- the broad chooser and broad file-order map -> see [Backend Source Reading Roadmap](/backend/backend-source-reading-roadmap) and [Vona Source Reading Map](/backend/vona-source-reading-map)
+- the module-wiring specimen -> see [Backend Resource/Module Contract Chain](/backend/backend-resource-module-contract-chain)
+- the emission concept/specimen/map/output-inspection family
+- the fullstack forward bridge -> see [Backend OpenAPI to Frontend SDK](/fullstack/openapi-to-sdk)
+
+Its job is only to help you isolate the first failing backend source-reading layer.
+
+## Where to read next
+
+- If you need the chooser page first, return to [Backend Source Reading Roadmap](/backend/backend-source-reading-roadmap).
+- If you need the broad file-order map first, continue with [Vona Source Reading Map](/backend/vona-source-reading-map).
+- If you want the proof-oriented layer-by-layer workflow first, continue with [Backend Source Reading Verify Playbook](/backend/backend-source-reading-verify-playbook).
+- If the backend path now looks correct and you want the downstream bridge, hand off to [Backend OpenAPI to Frontend SDK](/fullstack/openapi-to-sdk).
+- If the backend path now looks correct but the real issue is one mixed Student row-action chain, hand off to [Backend Metadata to Frontend Table Actions](/fullstack/backend-metadata-to-frontend-table-actions).
+- If you are still unsure which contract direction or drift type actually applies, return to [Contract Loop Playbook](/fullstack/contract-loop-playbook).
+
+## Final takeaway
+
+The cleanest way to debug a backend source-reading path is not to jump immediately into fullstack or frontend consumer debugging.
+
+First isolate:
+
+- whether the generated/module surface itself is present
+- whether the failure belongs to the module-wiring branch or the emission branch
+- whether the emitted output is wrong before it ever leaves the backend side
+
+Only then hand off to the downstream bridge if you still need it.

package/cabloy-docs/backend/backend-source-reading-roadmap.md

@@ -0,0 +1,129 @@
+# Backend Source Reading Roadmap
+
+This page is a lightweight roadmap for reading the Cabloy Basic backend source.
+
+Use it when your question is not yet “which exact source file should I open next?” but:
+
+- where should I start reading Vona backend source?
+- which backend topic cluster matches my question?
+- should I begin with a concept guide or a source-reading map?
+
+## Why this page exists
+
+The backend docs already explain the main Vona concepts well:
+
+- backend architecture
+- CLI and scripts
+- controller / service / model / entity responsibilities
+- runtime and distributed infrastructure
+
+That is good for conceptual understanding, but it still leaves a common follow-up question:
+
+> which backend page should I read next before I start opening framework or module source files?
+
+This page solves that problem.
+
+It is a chooser, not another backend runtime deep dive.
+
+## How to use this page
+
+Use this rule of thumb:
+
+- if you are new to the topic, start with the **concept guide** first
+- if you already know the concept and want the shortest path into source, go to the **source-reading map**
+- if you only need one backend specimen, choose the smallest topic cluster below and stop as soon as you have enough context
+
+## Architecture spine: start here first
+
+If you need the shortest path into the backend mental model, start with these pages:
+
+- [Backend (Vona)](/backend/introduction)
+- [Backend Foundation](/backend/foundation)
+- [Backend Essentials](/backend/backend-essentials)
+- [Backend CLI](/backend/cli)
+- [Backend Directory Structure](/reference/backend-directory-structure)
+
+A practical reading order is:
+
+1. Backend (Vona)
+2. Backend Foundation
+3. Backend Essentials
+4. Backend CLI
+5. Backend Directory Structure
+
+Then move to [Vona Source Reading Map](/backend/vona-source-reading-map) when you want the shortest file-order path into current source.
+
+If your next question becomes “how do I prove or diagnose the backend source-reading path itself?”, continue with [Backend Source Reading Verify Playbook](/backend/backend-source-reading-verify-playbook) and [Backend Source Reading Debug Checklist](/backend/backend-source-reading-debug-checklist).
+
+## Topic cluster: startup and CLI entry
+
+Start here when your question is about:
+
+- root backend entrypoints
+- `npm run vona`
+- CLI command families
+- backend build or play entry surfaces
+
+### Concept pages first
+
+- [Backend (Vona)](/backend/introduction)
+- [Backend CLI](/backend/cli)
+- [Backend Scripts](/backend/scripts)
+- [Backend Directory Structure](/reference/backend-directory-structure)
+
+### Best next step
+
+- if the question is “which root script enters the backend CLI?” -> read [Backend CLI](/backend/cli)
+- if the question is “which scripts drive normal backend dev/build/start/test workflows?” -> read [Backend Scripts](/backend/scripts)
+- if the question is “which source files should I open first?” -> read [Vona Source Reading Map](/backend/vona-source-reading-map)
+
+## Topic cluster: resource and module CRUD chain
+
+Start here when your question is about:
+
+- how one backend module is wired
+- how controller, service, model, and entity responsibilities separate
+- where generated metadata and API path registration live
+
+### Concept pages first
+
+- [Controller Guide](/backend/controller-guide)
+- [Service Guide](/backend/service-guide)
+- [Model Guide](/backend/model-guide)
+- [Entity Guide](/backend/entity-guide)
+- [Backend Directory Structure](/reference/backend-directory-structure)
+
+### Best next step
+
+- if the question is “what does each backend layer own?” -> read the concept guides above first
+- if the question is “which concrete source files should I read in order?” -> read [Vona Source Reading Map](/backend/vona-source-reading-map)
+- if the question becomes “how should I choose between explicit DTOs, inferred DTOs, and wrapped DTO helpers?” -> read [DTO Infer and Generation](/backend/dto-infer-generation)
+- if the question becomes “how do controller, DTO, and entity metadata become emitted OpenAPI contract?” -> read [Backend Contract Emission Specimen](/backend/backend-contract-emission-specimen), then [Backend Contract Emission Source Reading Map](/backend/backend-contract-emission-source-reading-map)
+- if the question becomes “what was actually emitted on the output side?” -> continue with [Backend Contract Emission Output Inspection](/backend/backend-contract-emission-output-inspection)
+
+## What this roadmap intentionally does not cover yet
+
+This first backend source-reading roadmap is intentionally narrow.
+
+It does **not** try to become the new entry page for every backend subsystem such as:
+
+- workers
+- queues
+- websockets
+- auth
+- cache
+- distributed runtime internals
+
+Those topics already have their own concept docs. This roadmap is only the first navigation layer for common source-reading tasks.
+
+## Final rule
+
+When in doubt:
+
+1. start with the backend concept guide that matches your question
+2. use this roadmap to choose the right cluster
+3. only then move to [Vona Source Reading Map](/backend/vona-source-reading-map)
+
+This roadmap is the chooser.
+
+The detailed file-order reading path belongs to the source-reading map.