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
• Vona Source Reading Map
• Backend Resource/Module Contract Chain
• Backend Contract Emission Specimen
• Backend Contract Emission Source Reading Map
• Backend Contract Emission Output Inspection
• Backend Source Reading Verify Playbook

TIP

Backend source-reading diagnosis path

1. Backend Source Reading Roadmap — choose the backend source-reading branch
2. Backend Source Reading Verify Playbook — use first when you want to prove the path layer by layer
3. 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 and 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 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 and 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)
• the broad chooser and broad file-order map -> see Backend Source Reading Roadmap and Vona Source Reading Map
• the module-wiring specimen -> see Backend Resource/Module Contract Chain
• the emission concept/specimen/map/output-inspection family
• the fullstack forward bridge -> see Backend OpenAPI to Frontend 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.
• If you need the broad file-order map first, continue with Vona Source Reading Map.
• If you want the proof-oriented layer-by-layer workflow first, continue with 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.
• 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.
• If you are still unsure which contract direction or drift type actually applies, return to 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.