Vona Source Reading Map

This page is a practical map for contributors and AI workflows that need to read Vona backend source code efficiently.

It does not try to teach every backend subsystem from scratch. Instead, it answers a narrower question:

when I need to understand one kind of Vona backend behavior, which files should I read first, and in what order?

Use this page together with:

• Backend Source Reading Roadmap
• Backend (Vona)
• Backend Foundation
• Backend CLI
• Backend Scripts
• Controller Guide
• Service Guide
• Model Guide
• Entity Guide
• Backend Directory Structure

Why this page exists

In a framework-sized backend codebase, source reading usually becomes slow for one reason:

• you can already find a relevant file
• but you do not yet know the shortest path to the next file

Vona especially benefits from a reading map because several layers cooperate at once:

• root scripts and CLI wrappers
• generated metadata surfaces
• controller / service / model / entity layering
• module and suite boundaries
• project-level backend hooks such as play or build helpers

This page gives a compact starting sequence for each common backend topic so readers can move from concept guide to source path without drifting.

How to use this page

For each topic below:

1. start with the concept guide to refresh the architectural intent
2. read the first source file to identify the public entry surface
3. continue into the next runtime file only if you still need the implementation detail
4. stop as soon as you have enough information for the task

The goal is not to read the entire backend tree every time. The goal is to choose the shortest accurate path.

1. CLI and backend startup entry path

Use this path when you are asking questions like:

• where does backend execution enter from the repo root?
• how does npm run vona reach the Vona CLI?
• where does play diverge from normal CLI startup?
• where does the backend build or verification hook surface begin?

Read the docs first

• Backend CLI
• Backend Scripts
• Backend (Vona)
• Backend Directory Structure

Then read source in this order

1. package.json
2. vona/packages-cli/cli/src/bin/vona.ts
3. vona/packages-cli/cli/src/start.ts
4. vona/src/backend/cli.ts
5. vona/src/backend/play/index.ts

What each file clarifies

• package.json shows the root vona script and the shared monorepo workflow entrypoint
• vona.ts shows how raw CLI argv is normalized, how play is treated specially, and where normal execution hands off to VonaCommand
• start.ts shows the CLI bootstrap class itself
• src/backend/cli.ts shows the project-level backend build hook surface
• src/backend/play/index.ts shows the backend playground-oriented verification entrypoint through mockCtx(...)

2. Representative backend resource and module CRUD path

Use this path when you are asking questions like:

• how is one backend module wired end-to-end?
• where do controller, service, model, and entity responsibilities separate?
• where do generated metadata and API path registrations live?

Read the docs first

• Controller Guide
• Service Guide
• Model Guide
• Entity Guide
• Backend Directory Structure

Then read source 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

What each file clarifies

• index.ts shows the module export surface and tells you that generated metadata is part of the public reading path
• .metadata/index.ts shows the generated registration surface for entity, model, service, controller, DTO, API path, and scope wiring
• controller/student.ts shows the resource-facing HTTP layer through @Controller('student'), @Resource(), and CRUD methods delegating to this.scope.service.student
• service/student.ts shows the orchestration layer delegating to this.scope.model.student
• model/student.ts shows the compact model binding from @Model(...) to EntityStudent
• entity/student.tsx shows the entity fields plus OpenAPI and Zova render metadata that drive the broader contract loop

When to continue into DTOs

If your next question becomes one of these:

• what is the request/response DTO shape for this resource?
• where do the select/view/create/update transport contracts live?

then continue into the module DTO files referenced from .metadata/index.ts.

If your next question is instead about generated registration, onion names, or API path typing, return to .metadata/index.ts before reading deeper.

If the next question becomes specifically about explicit DTOs, inferred DTO helpers, or how DTO choices surface in generated metadata, continue with DTO Infer and Generation.

If the next question becomes specifically about how those controller, DTO, and entity surfaces become emitted backend contract, continue with Backend Contract Emission Source Reading Map.

3. Controller request pipeline, onion configuration, and rate limiting

Use this path when you are asking questions like:

• what runs before route matching, after route matching, or after Passport authentication?
• should this concern be system/global/local middleware, guard, interceptor, pipe, or filter?
• why does a controller/action override preserve some global onion options?
• why does @Core.rateLimit(...) configure a global interceptor instead of adding a local one?

Read the docs first

• AOP Overview
• Controller AOP Guide
• Controller Guide
• Rate Limit Guide when the concern is request admission

Then read source in this order

1. vona/src/suite-vendor/a-vona/modules/a-web/src/main.ts
2. vona/src/suite-vendor/a-vona/modules/a-web/src/bean/bean.router.ts
3. vona/src/suite-vendor/a-vona/modules/a-web/src/lib/middleware/middlewareGuard.ts
4. vona/src/suite-vendor/a-vona/modules/a-web/src/lib/middleware/middlewareInterceptor.ts
5. vona/src/suite-vendor/a-vona/modules/a-web/src/lib/middleware/middlewarePipe.ts
6. vona/src/suite-vendor/a-vona/modules/a-onion/src/service/onion_.ts
7. vona/src/suite-vendor/a-vona/modules/a-aspect/src/lib/use/useOnionBase.ts
8. vona/src/suite-vendor/a-vona/modules/a-aspect/src/lib/use/useOnionGlobalBase.ts
9. vona/src/suite-vendor/a-vona/modules/a-ratelimit/src/bean/interceptor.rateLimit.ts when tracing rate-limit policy consumption

What each file clarifies

• main.ts proves that system middleware is composed before router lookup.
• bean.router.ts establishes the matched-route sequence: global middleware, guard, interceptor, pipe, local middleware, then action.
• The guard, interceptor, and pipe middleware files show the fixed middle stages independently.
• onion_.ts proves global/local onion composition and the effective deep merge of defaults, configuration, route metadata, and dynamic overrides.
• useOnionBase.ts shows how a local use decorator joins the local execution chain; useOnionGlobalBase.ts shows how a global use decorator writes route options for an already-global onion.
• interceptor.rateLimit.ts is the concrete post-Passport policy consumer and shows why rateLimit is owned by that interceptor’s options.

For exception behavior only, continue to a-error/src/config/config.ts and a-aspectutils/src/service/filter.ts. Do not treat filters as part of the normal successful request path.

Stop condition

Do not infer placement from an aspect/decorator name alone. Prove both the outer route stage in bean.router.ts and the inner global/local composition and option merge in onion_.ts before changing request-path behavior.

4. A compact reading strategy

When in doubt, use this order:

1. read the concept guide first
2. open the smallest source entrypoint that matches your question
3. read the generated metadata surface early when the topic spans multiple backend layers
4. only then descend into controller, service, model, or entity details

That order usually gets you to the answer faster than starting from the deepest backend runtime file first.

Where to read next

• If you now want a proof-oriented layer-by-layer backend validation workflow, continue with Backend Source Reading Verify Playbook.
• If something already looks wrong and you want symptom-first diagnosis, continue with Backend Source Reading Debug Checklist.

Final takeaway

The fastest way to read Vona accurately is not to memorize every file under vona/.

It is to recognize which question you are asking first:

• CLI and startup entry question
• resource and module wiring question
• DTO and generated-metadata question

Then start from the smallest public source surface that matches that question and only descend into deeper files as needed.