Tutorial 1: Create Your First Module

Basic

In this tutorial, one prompt lets AI create the first backend and frontend module skeleton for the Student Training Center story through a CLI-first workflow.

Goal

By the end of this tutorial, you will understand:

• when to use Vona and when to use Zova
• how to inspect the CLI before creating files
• how a Cabloy business capability starts as a module on both sides of the stack

AI Prompt

Give AI a prompt like this:

I'm building a Student Training Center project. Please create a demo-student module for both the backend and frontend.

Why this step matters

This is the right first step because Cabloy treats the module as the unit that owns business code, metadata, generated assets, and docs.

If AI jumps directly into CRUD, contracts, or rendering before the module boundary exists, the work loses its natural owner. This step keeps the rest of the Student Training Center story aligned from the start.

CLI commands to inspect/use

Work from the repo root, not from vona/ or zova/ directly.

Inspect the CLI surface first:

npm run vona :
npm run zova :

npm run vona :create
npm run zova :create

Representative module-generation commands:

npm run vona :create:module demo-student -- --suite=
npm run zova :create:module demo-student -- --suite=

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
• rerun npm run dev after module creation so the local workflow picks up the new modules cleanly

Generated or affected files

After both generators run, inspect the generated module roots before editing anything else.

Typical paths in this repo are:

• backend module root: vona/src/module/<module>/
• frontend module root without suite placement: zova/src/module/<module>/
• frontend module root with suite placement: zova/src/suite/<suite>/modules/<module>/

In this series, the target module roots are:

• vona/src/module/demo-student/
• zova/src/module/demo-student/

A minimal frontend module usually starts with files like:

• zova/src/module/demo-student/package.json
• zova/src/module/demo-student/src/index.ts
• zova/src/module/demo-student/src/.metadata/index.ts

What those files mean in the business thread

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.

Verification

1. make sure the local dev workflow is running:

npm run dev

2. confirm that both module roots now exist
3. inspect the generated files before editing them
4. confirm that the generated module roots match the target paths for this series:
   • vona/src/module/demo-student/
   • zova/src/module/demo-student/

Read more

• Fullstack CLI
• CLI Reference
• Backend Quickstart
• Frontend Quickstart

Next step

Continue to Tutorial 2: Create Your First CRUD.