DEV Community: Uncle Pushui

Is There a CabloyJS Equivalent in the React/Next.js Ecosystem?

Uncle Pushui — Mon, 02 Nov 2026 03:32:53 +0000

In the Node.js fullstack world, CabloyJS has always occupied a rather specific position. It is not a "frontend framework with some API routes on the side," but an enterprise fullstack architecture with module boundaries, built-in IoC (inversion of control / dependency injection), native RBAC and Workflow, and a metadata contract shared by frontend and backend.

So a familiar question comes up: if a team's stack is React/Next.js, is there something "close enough"?

The short answer: there is no exact equivalent to CabloyJS. What the React/Next.js ecosystem offers are four partially overlapping approaches. Each one hits some of CabloyJS's capabilities; none covers all of them.

To see this clearly, we first need to break CabloyJS apart.

1. Split CabloyJS into five comparable capability layers

Calling something a "fullstack framework" makes comparison meaningless. CabloyJS's value actually lives on five independent layers:

Modularity and scaffolding — business capabilities are organized as modules that can be installed, composed, and removed, with a CLI that generates the standard structure.
Backend IoC/DI — services, controllers, and beans collaborate through dependency injection instead of layered imports and manual wiring.
Frontend-backend integration — one framework constrains both sides, so routing, permissions, validation, and error handling follow the same conventions.
RBAC and Workflow — the permission model and workflow engine are built into the framework, not "install a library and wire it up."
Metadata-driven design — data structures, forms, lists, and permission points are described by metadata, and both sides start from the same definition.

Now hold these five layers against the candidates.

2. Why Next.js itself is not the counterpart

Next.js defines itself as a React meta-framework. It solves rendering modes (SSR/CSR/RSC), routing, builds, deployment, and edge runtimes — extending the frontend all the way into the server.

Its Route Handlers and Server Actions are enough to write endpoints, but they do not provide enterprise backend architecture constraints: no dependency injection container, no module lifecycle, no built-in permission model, and no workflow engine. In Next.js, all of that belongs to the "choose your own stack and assemble it yourself" category.

So the question should not be "is there a CabloyJS replacement inside Next.js," but rather: within the React/Next.js ecosystem, which combination fills in those CabloyJS layers?

3. Path one: fullstack conventions — RedwoodJS and Blitz.js

If what appeals to you is "one framework owns both sides and tells you, with strong conventions, where business logic belongs," these two frameworks come closest.

RedwoodJS

RedwoodJS is one of the most opinionated fullstack frameworks in the React ecosystem. In its classic form, it puts the React frontend, GraphQL API, Prisma data layer, and directory conventions into a single monorepo.

Scaffolding: generate commands produce pages, Cells, Services, and GraphQL SDL in one pass, turning "where should this capability live" into a fixed answer.
Clear boundaries: the frontend handles presentation and interaction, data access is confined to the service layer, and server-side validation and tests have a defined home.
One caveat: Redwood has spent the past couple of years evolving toward RedwoodSDK, with changes to both its technical foundation and deployment model. When choosing it, confirm which generation you are actually adopting rather than relying on older docs describing the GraphQL + Prisma setup.

Blitz.js

Blitz.js is built directly on top of Next.js, with the explicit goal of erasing the frontend-backend boundary.

Zero-API data layer: the frontend can import backend queries and mutations directly; Blitz compiles them into RPC endpoints and client calls at build time. This removes the hand-written API glue layer and is where it most resembles CabloyJS's "one integrated stack."
Built-in auth and sessions: authentication and session management work out of the box, with ready-made hooks for authorization checks.
Boundary: it provides authentication and access-control infrastructure, not a full RBAC permission-point system or workflow engine. Organization-level permission models still need to be modeled by you.

Who it fits: teams that want to stay entirely inside the Next.js ecosystem while getting "write the backend, call it from the frontend, with login state included." For that need, Blitz.js is the first choice. If you are not tied to Next.js but want an opinionated fullstack framework in React, look at RedwoodJS.

4. Path two: admin panels and metadata-driven design — Refine

CabloyJS is often used to build complex enterprise admin systems quickly. If your core need is permissions, auto-generated CRUD, and direct access to a database or existing API, you do not need to replace Next.js — just bring in Refine.

Refine is an open-source meta-framework for React admin panels that runs seamlessly on Next.js, Remix, or Vite.

Provider-based metadata thinking: dataProvider connects a data source (REST, GraphQL, Supabase, Prisma, etc.), authProvider handles login state, and accessControlProvider carries ACL/RBAC decisions. You define how to fetch and how to authorize; Refine wires up CRUD pages, forms, lists, and i18n.
UI-agnostic: it does not bind to a component library, so you keep Next.js's navigation and rendering modes without being locked in.
Boundary: Refine is a frontend-side meta-framework and does not provide a backend runtime. Authorization must ultimately be enforced by your API or database, and workflows are out of its scope entirely.

Who it fits: teams that already have a backend (or plan to use Supabase or their own API) and whose main pain is repeated admin-panel and permission work.

5. Path three: backend IoC — NestJS + Next.js

CabloyJS's backend offers Spring-like dependency injection. If your team values backend architectural rigor more than the convenience of a single all-in-one framework, the common answer is a combo plus a monorepo:

Manage the repo with Nx or Turborepo;
Let Next.js handle SSR, SEO, and the BFF layer;
Let NestJS own the real enterprise business backend.

NestJS is the most mature IoC/DI backend framework in Node.js today: Module, Provider, Guard, Interceptor, and Pipe form a complete set of architectural constraints, with clear module boundaries and test isolation.

The cost: frontend and backend are no longer governed by one framework, so routing, permissions, DTO validation, and error codes must be explicitly aligned across two systems. In other words, the consistency CabloyJS gets from "one shared metadata contract" has to be recovered here through engineering conventions and shared packages.

Who it fits: large commercial projects that need to evolve for years and cannot compromise on backend architecture. This combination is not weaker than CabloyJS in rigor or modularity — but it is not "batteries included," it is "architecture included."

6. How the four options compare

Requirement	CabloyJS capability	React/Next.js option	Recommendation
Integration and automation	Modules, CLI generation, unified frontend/backend	Blitz.js / RedwoodJS	Choose these to skip auth and API glue work
Fast admin panels and permissions	Built-in RBAC, Workflow, auto CRUD	Refine (embeddable in Next.js)	Choose it when the core is admin, forms, and access control
Top-tier backend architecture (IoC)	Dependency injection and modularity via Egg/Vona	NestJS + Turborepo/Nx	Choose it for large, long-lived systems where backend rigor comes first
Workflow engine	Built-in Workflow	No direct counterpart; build or integrate one	Evaluate separately for process-heavy systems
Shared frontend/backend metadata	One metadata source drives both sides	Partial overlap (Refine providers, Redwood conventions)	No complete equivalent; fill the gap with conventions

7. Selection advice

Staying fully inside Next.js, valuing "write the backend, use it in the frontend, login included": Blitz.js first.
Not tied to Next.js but wanting an opinionated React fullstack framework: RedwoodJS first — but confirm its current form and deployment model.
Mainly enterprise admin panels, forms, and permissions: Refine has the best return on effort, with no backend replacement required.
Backend rigor first, system expected to live for many years: the NestJS + Next.js monorepo is the safer bet.

One honest closing note: all four options can reproduce most of the day-to-day CabloyJS experience, but none fully replicates its five-layer structure of modules + IoC + RBAC + Workflow + metadata. The React/Next.js ecosystem wins on freedom of choice and an enormous supply of components and training material; CabloyJS wins by building enterprise constraints in advance and reducing how much architectural freedom a team has to improvise.

These are not substitutes for each other. They are a trade-off between free composition and built-in conventions. Decide which cost you fear more, and the answer follows.

AI Vibe Coding in Practice, Part 2: Product Decisions and a Revised SMS Suite Plan

Uncle Pushui — Mon, 02 Nov 2026 01:41:42 +0000

In the previous article, I shared my prompt and Claude Code's development plan for an SMS suite—shared infrastructure, verification codes, and authentication—for the CabloyJS fullstack framework. At the end of that plan, Claude Code asked me to confirm three groups of product decisions: registration behavior, phone-number scope, and rollout scope.

I had a question about “automatically register on SMS login”: if users do not enter a username, how should userName be determined? I sent that question back to Claude Code along with the other two decisions so it could refine the plan. Here is the next part of the conversation for reference.

Here is the prompt:

Registration: should SMS login automatically register a new user? I am unsure. If registration is automatic, how is userName determined?

Phone-number scope: mainland China only initially, or international numbers too? Support international numbers.

Rollout:

Enable SMS login on both Web/Admin.

Deliver the complete Mock flow in the initial release and integrate real vendors as well:

Mainland China: Alibaba Cloud / Tencent Cloud.

International numbers: please recommend one or two of the most popular services.

Here is the development plan returned by Claude Code:

These clarifications let us narrow the plan further. First, the username question: automatic registration is possible, but explicit registration fits the current account model more naturally. I recommend separating SMS registration from SMS login for the initial release, without automatic registration by default.

For international SMS, I recommend Twilio and Vonage. Integrate Twilio initially and keep Vonage as the second choice, rather than requiring both in the first release.

1. Registration: prefer explicit registration with a user-chosen `userName`

1. Why not generate a username automatically?

After checking the source further, the current user.name is more than an internal technical identifier:

Registration writes it from profile.username.
It is used for user display.
Existing password login looks up users by this field.
Profile editing currently allows users to change it.

It cannot simply be treated as an automatically generated, immutable internal ID. There is also no separate persisted nickname field for display names.

Source references:

User profile mapping: vona/src/suite/a-home/modules/home-user/src/service/userAdapter.ts:13.
User registration: vona/src/suite-vendor/a-vona/modules/a-user/src/bean/bean.user.ts:27.
Password login lookup: vona/src/suite-vendor/a-auth/modules/auth-simple/src/bean/authProvider.simple.ts:58.

Automatic registration could generate a username such as sms_<random identifier>, but that raises further product questions: can it be changed, what gets displayed, and which name is used if the user later sets a password? Implementing SMS login does not require redesigning the account naming model in the initial release.

2. Recommended registration and login contracts

Operation	Input	Behavior
SMS registration	International phone number, username, SMS code	Verify the number, create the user and SMS identity mapping, then sign in
SMS login	International phone number, SMS code	Sign in only through an existing SMS identity; never create a new user

The initial registration flow does not require a password or email, and must not create fake password credentials.

Recommended username rules:

Reuse and complete the existing username validation.
Trim surrounding whitespace and apply consistent case-equivalence rules when checking names.
Require uniqueness within the current instance.
Reject reserved system names such as admin.
Return a field error when a name is taken, rather than silently appending a random suffix.
Preserve uniqueness when the same phone number or username is registered concurrently.

One more detail matters: the current profile editor's “Display name” changes the same user.name, without the duplicate-name checks used for registration. Registration and renaming should share the necessary username constraints. Otherwise, renaming can introduce conflicts after registration has enforced uniqueness.

3. Separate phone identity from username

Keep three concepts distinct:

Field/concept	Purpose
`user.id`	Internal user identifier
`user.name`	Account name chosen by the user
SMS identity mapping	Association between a verified, normalized phone number and `userId`

Consequently:

Renaming a user does not affect phone login.
A phone number must not become the default username, which could expose the full number wherever the user is displayed.
A username matching an old account does not trigger automatic association.
A phone number matching an old account's mobile field does not claim that account either.

The existing authentication chain's automatic registration behavior also needs to be explicitly disabled. The framework can currently create users for both login and register, so passing intention: 'login' alone does not make an operation login-only.

For a missing SMS identity, prompt the user to register after verifying ownership of the phone number. The send-code endpoint itself must not disclose whether an account exists.

2. Phone-number scope: support international numbers and normalize to E.164

Use an explicit international-number contract on both frontend and backend:

Provide a country/region selector on the frontend.
Use a mature server-side number parser, such as a libphonenumber-based implementation.
Normalize numbers to E.164 for storage, comparison, and sending, for example +86138… or +447….
Use the same normalization logic for sending and verification.
Do not use a simple regular expression to validate numbers from every country.
Do not infer the recipient's country from the UI language, browser locale, or IP address.

Routing rules

Destination	Default sending channel
Mainland China	Alibaba Cloud or Tencent Cloud
Hong Kong, Macao, Taiwan, and other international destinations	Twilio, or Vonage if configured
Explicit development/test configuration	sms-mock

Do not route Hong Kong, Macao, or Taiwan through the mainland China SMS channel, or choose a vendor based on page language.

Supporting international numbers does not mean enabling worldwide sending by default. Configure allowed countries/regions, quotas, and spending limits. Destinations may have different Sender ID, number registration, template, or use-case requirements, so enable and verify them individually.

3. International vendors: Twilio and Vonage

Both are mature, widely used international communications API vendors. This is an engineering recommendation, not a claim that they rank first and second in verifiable global market share.

Vendor	Recommended role	Integration
Twilio	First choice for international SMS in the initial release	Programmable Messaging
Vonage, formerly Nexmo	Second choice or a later alternative channel	SMS API

1. Twilio: recommended for the initial release

It fits the proposed architecture because it provides:

A general-purpose SMS sending API.
E.164 recipient numbers.
A sending number or Messaging Service for sender configuration.
Extensive documentation on destination permissions and country requirements.

2. Vonage: a second choice

Vonage SMS API provides general-purpose recipient, sender, and message-body parameters. It can support another SMS Provider following the same contract.

For specific target countries, the final choice should still consider:

Sending identities that can actually be provisioned.
Delivery rate and latency tests.
Unit prices and message-segment billing.
Account entity and local compliance requirements.

3. Do not default to managed Verify products for this plan

Both Twilio and Vonage offer managed verification products. For this suite, use:

Twilio Programmable Messaging.
Vonage SMS API.

The plan does not default to their Verify products because sms-captcha is already intended to manage:

Code generation.
Expiry.
Phone-number and purpose binding.
Attempt limits.
Single consumption.

Keeping vendors responsible for transport lets Mock, Alibaba Cloud, Tencent Cloud, and international Providers share the same verification semantics.

4. The infrastructure must support two vendor sending models

With international vendors included, the unified SMS interface cannot require a vendor template ID for every request. Their APIs differ:

Provider	Typical sending model
Alibaba Cloud	Signature + template ID + named parameters as JSON
Tencent Cloud	Signature + template ID + ordered parameter array
Twilio	Sender/Messaging Service + message body
Vonage	Sender + message body

Keep the business call consistent:

// Proposed interface
await this.bean.sms.send({
  scene: 'sms-auth:signup',
  recipient: normalizedPhone,
  params: {
    code,
    minutes: 5,
  },
});

Server-side Scene configuration and Provider adapters handle the differences:

Alibaba Cloud: convert { code, minutes } to template parameter JSON.
Tencent Cloud: convert parameters to an array in an explicitly configured order.
Twilio/Vonage: render the body from localized text templates maintained on the server.

Parameter order must not depend on object enumeration. Public requests must not freely supply message bodies, vendor templates, or senders.

Also distinguish:

Recipient region: determines requirements and available channels.
Message language: determined by the business language policy.
Vendor account region: determined by Client configuration.

Do not combine all three into one region field.

5. Module structure: retain four core modules and extend real Providers independently

Since the initial scope explicitly includes multiple real vendors, retain the four core modules and create separate vendor modules:

Module	Initial recommendation
cabloy-sms	Required: transport infrastructure
sms-captcha	Required: verification codes
sms-auth	Required: registration and login
sms-mock	Required: development and testing
sms-aliyun	Required: mainland China Provider
sms-tencent	Required: mainland China Provider
sms-twilio	Recommended for the initial release: international Provider
sms-vonage	Alternative; include when two international channels are needed

All belong to the cabloy-sms suite. Separate modules isolate SDKs, credential types, and vendor changes, so consumers do not have to load every SDK.

If retaining exactly four modules is essential, real Providers could live in cabloy-sms. With multiple real vendor consumers now confirmed, separate Provider modules are a better fit.

Default routing selects one vendor for each send. For example:

Mainland China defaults to Alibaba Cloud, with Tencent Cloud selectable through configuration.
International destinations default to Twilio.
Never send through multiple Providers simultaneously.
Do not automatically resend through another vendor when a timeout leaves the result uncertain.

6. What enabling both Web/Admin means

Both can offer SMS registration and login while sharing:

Users.
SMS identity mappings.
The Provider configuration mechanism.
Passport and session handling.

Registering through Web or Admin must not create separate users for the same phone number.

Opening a login entry point and granting business permissions are separate decisions:

SMS registration grants only ordinary registered-user permissions.
Registering from an Admin page does not grant administrative permissions.

7. Updated initial delivery recommendation

Set the initial scope to:

Infrastructure + Mock: establish a working unified sending contract.
Alibaba Cloud, Tencent Cloud, and Twilio Providers: integrate with that contract.
SMS verification: international numbers, purpose binding, rate limits and cooldowns, single consumption, and Mock autofill.
Explicit SMS registration and login restricted to existing SMS identities.
Web/Admin entry points and permission regression checks.

For real Providers, distinguish:

Code integration complete: request mapping, response parsing, and error handling have been verified.
Real SMS acceptance complete: accounts, signatures/templates/sending identities have been approved, and authorized test numbers have actually received messages.

The former cannot replace the latter, and a complete Mock flow cannot replace real vendor acceptance.

My final recommendation is explicit registration to establish userName, E.164 normalization for international numbers, and initial integration with Alibaba Cloud, Tencent Cloud, and Twilio, with Vonage as the second international option. This covers the requested initial business scope without also taking on account-name redesign, worldwide channel activation, and automatic failover.

Sources

No code was changed in this round. Vendor information was checked against search results from official documentation; full-page retrieval was restricted by network access. No commitments were made about availability in specific countries, pricing, or actual delivery rates.

After this exchange, Claude Code had more concrete recommendations for registration, international numbers, and real vendor integration, along with clearer boundaries for shared Web/Admin identities and permissions. I will leave it here for now to keep the article manageable. If you would like to see the implementation that follows, leave a comment and I will continue putting the material together.

AI Vibe Coding in Practice: An SMS Suite Prompt and Development Plan

Uncle Pushui — Thu, 29 Oct 2026 02:55:41 +0000

While developing an SMS suite for the CabloyJS fullstack framework—shared infrastructure, verification codes, and authentication—I found both my prompt and Claude Code's development plan representative of a real AI coding workflow. I have put them together here for reference.

Here is the prompt:

Please carefully analyze the following development task and propose a reasonable plan:

Goal: implement shared SMS infrastructure first, then build multiple business capabilities on top of it.

Infrastructure: SMS provider / clients / scene.

Business capabilities:

sms captcha: SMS verification codes.

sms auth: user registration and login.

Suite / module structure:

Suite: cabloy-sms.

Modules:

cabloy-sms: shared SMS infrastructure.

sms-captcha: SMS verification codes.

sms-auth: user registration and login.

sms-mock: a Mock SMS Provider that prints verification codes to the console and sends them to the frontend so it can fill the code input automatically.

Here is the development plan returned by Claude Code:

1. Overall recommendation

Keep the proposed cabloy-sms suite and its four modules, with these layers:

cabloy-sms: SMS transport infrastructure, responsible for which provider account and template to use when sending a message.
sms-captcha: SMS verification, responsible for the recipient, the intended operation, and secure verification.
sms-auth: phone-based authentication, responsible for which account to sign in to after verification and whether to create a new account.
sms-mock: an SMS Provider for development and testing. It replaces real transport while retaining the verification and authentication flows.

The most important design principle is:

Infrastructure does not depend on verification codes; verification codes do not depend on user authentication; Mock does not change the real business flow.

The current repository is Cabloy Basic. Based on the existing source, reuse Vona's provider/client/scene extension pattern, the a-captcha verification system, and the a-auth authentication chain. There is no need to build another SMS code cache or session system.

However, a-captcha currently lacks safeguards required for SMS login, including phone-number binding and atomic consumption. It needs a bounded set of backward-compatible extensions.

2. Suite and module structure

The proposed names follow the current naming rules and can remain unchanged.

Layer	Name	Description
Suite	cabloy-sms	providerId=cabloy, suiteName=sms
Module	cabloy-sms	Shared SMS infrastructure
Module	sms-captcha	SMS verification codes
Module	sms-auth	SMS registration and login
Module	sms-mock	Mock SMS Provider

A Suite and one of its Modules can share a name. Their full package names are vona-suite-cabloy-sms and vona-module-cabloy-sms, so they remain distinct.

Place backend modules under:

vona/src/suite/cabloy-sms/modules/

Place corresponding frontend modules that actually contain frontend code under:

zova/src/suite/cabloy-sms/modules/

There is no requirement to create four empty frontend counterparts. The initial frontend work mainly belongs to sms-captcha for verification interactions and sms-auth for login forms. Mock autofill does not require a separate frontend Mock system.

Dependency direction

sms-captcha depends on the SMS infrastructure and the existing verification system.
sms-auth depends on SMS verification and the existing authentication system.
sms-mock only needs the SMS infrastructure.
The infrastructure, verification, and authentication modules must not have a hard dependency on sms-mock.

Whether Mock participates at runtime should be determined by application composition and server configuration, rather than being enabled unconditionally by business modules.

3. cabloy-sms: defining provider / clients / scene

1. Provider: implementation of a vendor protocol

A Provider implements a sending protocol, for example:

sms-mock:mock.
A future Alibaba Cloud SMS Provider.
A future Tencent Cloud SMS Provider.

The Provider is responsible for:

Converting a unified send request into the vendor's request.
Calling the SDK or HTTP API.
Converting the vendor's response into a unified result.
Hiding vendor errors and sensitive information.

It does not generate verification codes, decide between registration and login, or look up users.

Introduce smsProvider and smsScene extension types using the existing decorators, type registration, onion metadata, and CLI templates. There is no need for a separate plugin manager.

Existing reference:

vona/src/suite-vendor/a-pay/modules/a-pay/src/types/payProvider.ts:6

2. Client: named account configuration under a Provider

A Client is named configuration under a Provider. It is not a new business service and does not need its own bean scene.

For example, one real Provider can have:

default: the default account.
marketing: another vendor account or dedicated sending configuration.

A Client holds:

Credentials.
Region and endpoint.
Necessary vendor defaults.
Settings such as whether it is enabled.

Use base + clients under each Provider, retaining the type association between Provider and Client.

The initial release does not need vendor account tables, a credential management console, or a persistent Client registry. Configuration is sufficient for the current consumers.

3. Scene: a business sending scenario

A Scene represents a stable business intent for sending, such as:

sms-auth:signin.
Future order or delivery notifications.

A Scene configures:

Which Provider and Client to use.
SMS signature and vendor template.
Template parameter constraints.
Any necessary server-side routing rules.

The server-side call could look like this:

// Proposed interface, not an existing API
await this.bean.sms.send({
  scene: 'sms-auth:signin',
  recipient: normalizedPhone,
  params: {
    code,
    minutes: 5,
  },
});

The caller supplies business parameters; the infrastructure resolves transport configuration. Public requests must not directly specify the Provider, Client, template ID, signature, or credentials.

Also distinguish these concepts:

Concept	Purpose
SMS Scene	Selects the transport channel, account, and template
Captcha Scene	Defines which business operation the verification code can authorize

The same business module may declare and associate both, but they are not interchangeable. A third registry for “SMS verification scenarios” is unnecessary.

4. Instance isolation and send results

Providers and Scenes must resolve effective configuration for the current instance. Never cache the first request's credentials, phone number, or scene configuration in shared bean fields.

The existing onion configuration merge includes instance configuration. Reading static beanOptions.options directly is not equivalent:

vona/src/suite-vendor/a-vona/modules/a-onion/src/service/onion_.ts:252

Keep sending synchronous for the initial release and distinguish:

Accepted by the vendor.
Explicitly rejected.
An uncertain result, such as a timeout.

“Accepted by the vendor” does not mean “received by the phone.” Defer message queues, delivery receipts, automatic failover, and automatic retries. In particular, do not blindly resend after a timeout.

4. sms-captcha: reuse verification infrastructure and add SMS semantics

1. Existing capabilities and gaps

a-captcha already provides:

A challenge ID.
Provider and Scene.
Redis storage and TTL.
Verification DTOs.
Form validation integration.

However, its cache currently stores only scene/provider/token/token2, without the recipient phone number. Successful verification uses separate read, compare, and delete operations, allowing multiple concurrent attempts to succeed.

Reference:

vona/src/suite-vendor/a-captcha/modules/a-captcha/src/bean/bean.captcha.ts:19, :79

Adding a CaptchaProvider that sends SMS is therefore not enough to complete SMS verification.

2. Recommended responsibilities

Add generic, optional capabilities to a-captcha:

Accept trusted context at creation time.
Store verification binding information.
Compare it with the expected binding computed by the server at consumption time.
Use atomic state transitions to guarantee single consumption.
Let Provider/Scene declare policies for controlled issuance, refresh, and token exposure.
Remove plaintext tokens from generic verification logs.

sms-captcha owns the SMS-specific rules:

Phone-number normalization and format validation.
Allowed purposes and scene mapping.
Cryptographically secure code generation.
Binding to the phone number, purpose, and any necessary subject.
Sending cooldowns, quotas, and failed verification attempt limits.
Calling the SMS infrastructure.
SMS-specific form interactions.

This reuses the OTP system while keeping phone-number rules out of the generic verification module.

3. Recommended verification rules

For the initial release:

Item	Recommendation
Code	Six digits, handled as a string and generated securely
Validity	Five minutes, configurable
Resend cooldown	60 seconds, configurable
Failed attempts	An explicit limit, such as five
Expiry	Lookups and incorrect attempts never extend the original expiry
Resend	A new challenge replaces the old one; the old proof becomes invalid
Consumption	A correct code can succeed at most once
Binding	Current instance + normalized phone number + purpose; add subject binding as required
Abuse prevention	Phone cooldowns/quotas + IP rate limits + verification attempt limits

The phone number cannot be just a send parameter. A code sent to phone A must never authorize login for phone B, even when the code itself is correct.

The initial release can continue using the existing Redis storage for short-lived secrets, without building another cache just for hashed storage. It must have a short TTL, access isolation, no plaintext logs, and no persistent verification-code history. If hashed storage becomes a requirement, explicitly separate stored verification material from the value returned for Mock autofill; the current interface does not inherently support that distinction.

4. Prevent bypasses through generic endpoints

The existing generic captcha creation, refresh, and immediate-verification endpoints are public:

vona/src/suite-vendor/a-captcha/modules/a-captcha/src/controller/captcha.ts:15

Security rules must therefore live at the shared service boundary, rather than only in a new SMS Controller.

For the initial release:

Generic create(scene) must not create an SMS challenge without trusted context.
Generic refresh(id, scene) must not resend while bypassing the SMS cooldown.
Refreshing an expired or missing ID must not fall back to unrestricted sending.
SMS scenes should initially disable verifyImmediate → token2, avoiding another replayable proof.
SMS verification must fail when the expected phone/purpose binding is absent.

5. sms-mock: simulate transport while preserving business validation

1. Correct runtime behavior

Mock should follow the same chain as real SMS:

sms-captcha generates a code and establishes its binding.
The SMS infrastructure resolves the sms-mock Provider.
Mock makes no external vendor calls.
It prints the code to the development console with the phone number masked.
The verification layer returns the code to the frontend only when permitted.
Submission still enforces expiry, attempt limits, binding, and single consumption.

Never use a fixed universal code or make Mock login return success directly.

2. Autofill can reuse the existing response field

The captcha response already supports an optional token, and the current form writes it into the input:

zova/src/suite/cabloy-basic/modules/basic-captcha/src/component/formFieldCaptcha/controller.tsx:96

There is no need for a second verification-response protocol.

However, showToken currently defaults to enabled in all non-production environments. Real SMS must not inherit that behavior:

vona/src/suite-vendor/a-captcha/modules/a-captcha/src/config/config.ts:3

Returning an SMS code requires all three conditions:

The actual Provider used for this request is sms-mock.
The environment is non-production.
Development autofill is explicitly enabled.

Real SMS must never return the code because of the global showToken setting, even in dev/test. Selecting Mock in production must fail at startup or sending time, rather than silently falling back.

3. The frontend needs SMS-specific interactions

The existing image-captcha component automatically creates a challenge on initialization, refreshes it after a failed submission, and renders the payload as an image. It cannot be used unchanged for paid SMS.

The SMS component should provide:

A phone-number input.
An explicit “Send code” button.
A cooldown based on server time.
Autofill after a successful Mock send.
Clearing the challenge and code when the phone number changes.
No automatic retry after a send failure.
No automatic sending on page initialization or ordinary form errors.

Keep the code only in the current interaction state. Do not put it in localStorage, SSR HTML, or persistent user state.

6. sms-auth: reuse authentication and establish a trusted phone identity

1. Recommended product behavior

For the initial release, I recommend:

Sign in after successful phone verification; automatically register if that SMS identity does not exist.

One form can handle both registration and login, matching the basic behavior of the existing generic authentication chain. This remains a product decision requiring confirmation. If registration and login must be strictly separate, define how each operation handles existing and missing identities.

2. Authentication flow

Add a non-OAuth SMS AuthProvider and reuse this chain:

Verify and consume OTP → obtain or create identity and user → existing Passport signin

The framework already supports provider.verify → issuePassport → passport.signin:

vona/src/suite-vendor/a-auth/modules/a-auth/src/service/auth.ts:27

Key requirements:

Consume the OTP at the Provider's verification boundary, rather than only in a new Controller.
Keep Provider, Client, and intention under server control.
Do not merge the entire request into authentication configuration.
Do not create a separate JWT, Cookie, or session storage system.

3. Never claim an account automatically through an old mobile field

The existing homeUser.mobile is only an optional string. It does not mean “verified phone number”:

vona/src/suite/a-home/modules/home-user/src/entity/user.ts:24

Use the existing authentication identity mapping:

SMS identity namespace + normalized phone number → auth mapping → userId

This means:

A trusted SMS mapping exists: sign in to its associated user.
No mapping exists: register or reject according to the confirmed policy.
An old account has the same mobile value: never automatically associate, merge, or take over that account.
A mapping exists but its user is missing: return an error; do not silently recreate the account.

Defer phone binding, phone changes, recovery, and account merging. Explicitly reject associate/migrate inside the Provider so generic entry points cannot trigger them.

4. Handle concurrent first registrations separately

Atomic consumption of one code does not guarantee identity uniqueness: a single phone number may have two independent, valid verification requests.

Serialize by current instance and SMS identity, then recheck and atomically complete these writes within a transaction:

User creation.
Normal role relationships.
The auth mapping.
Any necessary projection into the mobile profile field.

Enter the existing signin flow after commit. A transaction alone, or a lock on a row that does not exist, is insufficient to prevent duplicate creation. Do not add business uniqueness constraints spanning tenants.

Prefer reusing the existing identity mapping without a new identity table. If a persisted field such as mobileVerifiedAt is necessary, confirm the owning module's fileVersion strategy before implementation.

5. Frontend login integration

sms-auth provides the SMS login form and business wrapper.
Keep integration with the existing Home Login page minimal.
Reuse Passport's post-login handling instead of copying token writes and returnTo logic.
Web/Admin share authentication identities; a different page or vendor Client must not create duplicate users.
New users follow an explicit ordinary-user role policy. Successful SMS registration does not grant administrative permissions.

7. Recommended delivery order and acceptance

Stage	Deliverables	Exit criteria
1. Infrastructure + Mock	Provider/Client/Scene, send facade, Mock	Ordinary template messages can be sent through Mock; instance configuration is isolated; failure semantics are explicit
2. SMS verification	Required captcha extensions, issuance/resend, abuse prevention, SMS component	Autofill works; phone/purpose binding and atomic consumption are enforced; generic endpoints cannot bypass them
3. SMS registration and login	SMS AuthProvider, identity creation boundary, login entry	Registration and subsequent login work; old mobile values are not claimed; concurrent requests do not create duplicate accounts; sessions are reused
4. First real Provider	Integration with the selected vendor	Mock and real transport follow the same contract; real SMS never returns or logs codes

Although Mock is fourth in the module list, implement it with the infrastructure so verification and authentication have a runnable consumer chain from the beginning.

Acceptance need not become an enormous matrix, but it must cover:

Verification fails across phone numbers, purposes, and instances, and for expired or replayed codes.
At most one concurrent consumption of the same challenge succeeds.
Two independent valid OTPs used concurrently for first login produce exactly one user and identity mapping.
Generic captcha and authentication entry points cannot bypass security rules.
Changing the phone number clears the old proof.
Real SMS never exposes codes in any environment.
Mock prints and autofills codes only behind explicit development gates.
Disabled users cannot sign in, and existing password/GitHub login does not regress.
Sending timeouts never trigger blind retries.

8. Initial scope and decisions to confirm

Keep out of the initial release: vendor management screens, sending-history screens, bulk marketing, queues, receipts, automatic retries/failover, phone-number changes, recovery, and account merging.

Only three groups of product decisions need confirmation:

Registration: should SMS login automatically register a new user? Recommended.
Phone-number scope: mainland China only initially, or international numbers too? Either way, require an explicit calling code and normalize consistently. Never prepend +86 to every input by default.
Rollout: Web first, or Admin at the same time? Should the initial release deliver only the complete Mock flow and defer real vendors?

The names are already reasonable and need no change. Branding or naming preferences can still be accommodated under the same rules.

After confirmation, create the infrastructure and Mock using the existing CLI rather than building directories manually, for example:

npm run vona :create:suite cabloy-sms
npm run vona :create:module cabloy-sms -- --suite=cabloy-sms
npm run vona :create:module sms-mock -- --suite=cabloy-sms

Then generate the remaining modules in stages, run focused backend tests, and verify critical E2E flows. Backend contract changes should generate frontend consumers first. For frontend reverse dependencies, build the affected Web/Admin flavors before running npm run deps:vona.

This round only completed analysis and made no file changes. The CLI command implementations were confirmed in source, but attempts to run npm run vona and npm run zova both failed because @cabloy/cli was missing. Node was v24.8.0, below the repository requirement of >=24.11.0. Prepare the runtime and dependencies before implementation. No dependencies were installed, and no builds or tests were run in this round.

Closing note

Claude Code asked me to confirm three groups of product decisions—registration behavior, phone-number scope, and rollout scope—before developing the plan further. I will leave it here for now to keep the article manageable. If you would like to see what comes next, leave a comment and I will continue putting the material together.

Functional vs Object-Oriented: Two Cost Curves for Frontend Architecture

Uncle Pushui — Thu, 22 Oct 2026 11:52:11 +0000

Abstract: People habitually carve the React/Vue and Zova camps into "functional vs object-oriented." But React's Fiber nodes and Vue's component instances reveal a fact: beneath that so-called functional style, an object system is always hiding. The real dividing line is not syntax — it is who owns state identity, scope, and lifecycle: the closure, or a container-managed bean. This article re-reads the paradigm debate through two cost curves: the functional style pays "architectural entropy" afterwards, the object style pays "ceremony" up front. It then lists three hard requirements only containerization solves cleanly (SSR request scope, interceptable call sites, cross-module contracts), and three costs an object style must honestly face. The final criterion boils down to one sentence: if something needs to be found, replaced, shared, or disposed, make it an object; otherwise, let it be a function.

1. Tearing down a false dichotomy first

When people discuss the difference between Vue/React and Zova, the most common framing is "functional vs object-oriented." It's a convenient label, but it conflates three distinct things:

Syntactic form: writing functions or classes
State host: closure variables or object properties
Architectural ownership: who manages identity, scope, and lifecycle

Take one step into the source code, and the classification "React is functional, Vue is functional, Zova is object-oriented" collapses.

React's "functions" are merely the expression form of rendering. Hooks depend on a fixed call order — which means every function component must have a persistent Fiber node behind it holding the hooks linked list. Pure functions need no identity; React components have identity, scheduling phases, and effect-cleanup queues. React hides an object system beneath function syntax.

Vue's setup() is a function, but every component instance is an object. The reactive host is a Proxy object, ref is a box with getter/setter, reactive is a proxied object graph. Vue never pretended to be purely functional.

So the real watershed is not "whether to use functions" — it is:

Who owns identity, scope, and lifecycle — the closure, or a container-managed bean?

That is the actual boundary between Zova's default mental model and Vue/React's.

2. Each model's "default answer"

The same counter, written two ways — the difference looks like mere syntax:

// Vue 3 default mental model: explicit reactive primitives
const count = ref(0);
const count2 = computed(() => `=== ${count.value} ===`);
function increment() {
  count.value++;
}

// Zova: a framework-managed reactive object
export class Counter {
  count: number = 0;
  count2: string;

  protected async __init__() {
    this.count2 = this.$computed(() => `=== ${this.count} ===`);
  }

  increment() {
    this.count++;
  }

  protected render() {
    return (
      <div>
        <div>{this.count2}</div>
        <button onClick={() => this.increment()}>Increment</button>
      </div>
    );
  }
}

The difference is not that we saved a few .value keystrokes. In the first snippet, state's host is the setup() closure, lifecycle hangs off the component instance, and sharing requires hunting for another mechanism. In the second, state's host is a bean instance that inherently belongs to a container, to a scope.

This single distinction will reveal itself over and over as a system grows.

3. Cost curves: pre-paid and post-paid

The real divergence between the two models is where the cost shows up.

Functional style: architectural entropy, paid after

A single component costs almost nothing extra — write a function, declare a few refs, done. But Vue officially ships four mutually orthogonal sharing mechanisms:

props / emits
composables
provide / inject
store layer (Pinia, etc.)

When a system grows to dozens of modules and multiple teams, all four mechanisms coexist in one codebase. Which state should use which? There is no enforced answer, only team conventions. Convention density grows linearly with headcount, while execution drift grows exponentially. That is architectural entropy — it never shows up on day one, but it never fails to show up.

Object style: ceremony, paid up front

In Zova, every bean must declare its role, scope, and lifecycle. Even a state that only serves a single component's internals has to answer first: "which bean are you, and which container do you live in?" That is the up-front ceremony.

What it buys in return is the convergence of sharing into one mechanism:

class ControllerPage {
  @Use()
  $$localCounterState: CounterState;          // ctx container: component-instance scope

  @Use({ injectionScope: 'host' })
  $$hostCounterState: CounterState;           // hierarchical lookup: parent–child sharing

  @Use({ injectionScope: 'app' })
  $$appCounterState: CounterState;            // app container: app / request scope

  @Use({ injectionScope: 'sys' })
  $$sysCounterState: CounterState;            // sys container: system scope
}

Component-internal, between-components, app-global, system-global — four sharing scopes, one IoC semantics. provide/inject stops being an independent subsystem and becomes the natural corollary of host / skipSelf injection scopes.

So "which is better" is a pseudo-question. The right question is: where does your system's complexity primarily land? If it lands on "rendering composition," the functional style's flexibility is pure gain. If it lands on "domain ownership, modularity, long-term evolution," the object style's uniformity pays back.

4. Three things only containerization does cleanly

Some questions are not "style choices" — they are "does this mechanism exist?" questions.

1. SSR request scope

SSR has a hard constraint: state must be isolated across requests; module-level singletons leak user data.

In the functional model, there is no addressable container called "the request." You only have two choices: module-level singletons (leak) or rebuilding the entire module graph per request (expensive and error-prone). Zova's app container is natively the request boundary, and the sys container is natively cross-request — this is not syntax sugar; it is a first-class SSR requirement modeled directly into the architecture.

2. Interceptable call sites

AOP, permission injection, logging, behavior extension — all of these require "call sites" to have stable identity. Pure function calls have no identity; to intercept you have to wrap functions in layers, and the wrapper layers themselves are anonymous and unaddressable. A bean's method call naturally passes through the container, and the container is naturally the interception point.

3. Cross-module contracts

class ControllerLayout {
  @Use('a-routertabs.model.tabs')
  $$modelTabs: ModelTabs;
}

Bean identifiers let consumers depend on a contract name, not the provider's file path. Modules can be reorganized, relocated, have their implementations replaced — and consumers do not move.

Functional cross-module sharing eventually converges onto some global store key or context key — essentially a string contract too, except no container is managing its registration, resolution, and lifecycle for you. Anyone can reinvent the mechanism; the difference is whether it is part of the architecture or part of the scaffolding.

5. Honestly listing three costs of the object style

If you only see the benefits, that is marketing, not architecture. The object style carries three real costs:

1. Decorators + metadata = runtime magic. Behind @Use() is a conspiracy of build-time transforms and runtime resolution. Static readability drops, call stacks go deeper, and debugging means piercing one extra layer of framework.

2. Granularity gets forced coarser. When "everything should be a bean" becomes a habit, you end up with an input box that still needs a role and a scope — over-modeling. The object style needs discipline to fight its own ceremony.

3. Structural conflict with React's evolution direction. RSC and concurrent rendering push state toward serializable pure data, while a bean is a non-serializable live object graph. Zova can only grow on Vue, not on React — and this is not an aesthetic choice, it is determined by the runtime substrate: Vue's component instance is already an object with a reactive scope, naturally suited to host beans; React's Fiber substrate is heading in the opposite direction.

6. Convergence: objects own identity, functions own expression

The interesting thing is that both camps are moving into each other's core territory.

Zova itself is a hybrid: underneath runs Vue reactivity, and $computed and $watch are thoroughly functional APIs. Objects only carry identity, scope, and lifecycle — not computation.

The React ecosystem is also moving toward identity: the signals revival, external state containers like QueryClient, stores like Zustand that "pull state out of the closure" — all essentially admitting that pure closures cannot carry all state, and that an addressable host is needed.

From this we get an actionable judgment criterion:

If something needs to be "found, replaced, shared across scopes, disposed with a lifecycle," it is an object; otherwise it should be a function.

Wrapping a pure function in an object is over-design; using a closure to carry something that needs identity is architectural debt.

7. Conclusion: a debate not on the same abstraction layer

Let us return to the comparison in the title.

The functional style solves "how to compose rendering." The object style solves "how to organize a long-lived system." The former is a programming paradigm; the latter is an architectural paradigm — they are not on the same abstraction layer. Comparing their elegance directly often leads to "FP is more advanced," but that conclusion is wrong: React's hooks are precisely effectful closures with order constraints, side effects, and Fiber scheduling — they are no closer to pure functions than classes are.

The questions worth asking are always:

In my system, who does state identity belong to?
Is the state-sharing mechanism one set or four?
Is the SSR request boundary modeled?
When a newcomer takes over an unfamiliar module and needs to change some stateful behavior: do they have to rummage through composables, stores, and provide/inject one by one to find the state's host, or do they just ask "which bean is this?"

Zova chooses to pay ceremony up front and reap order later. Whether that choice is right depends not on how elegant the syntax is, but on how long your system plans to live and how big it plans to grow.

CabloyJS’s AI Moment: From a TypeScript Fullstack Framework to AI-Spec-Driven Development

Uncle Pushui — Fri, 16 Oct 2026 00:52:11 +0000

AI coding assistants have turned "having AI write code" into a mainstream conversation over the past two years. From Cursor's tab completion, to Claude Code's agent mode, to the more radical "Vibe Coding" — describing an idea in natural language and letting AI turn it into a running app.

But the real difficulty appears when a Vibe Coding project outgrows "hello world" and becomes an actual business system.

AI "hallucinates." It modifies modules you didn't ask it to touch, assumes interfaces and data structures that don't exist, and turns an entire repository into a mess. This is not about prompts being imprecise enough — it is a deeper problem: AI lacks explicit, machine-readable global constraints. It can only guess from context what the correct boundaries are, and once that guess drifts outside the business scope, the cost of repair grows exponentially.

The series of pivotal iterations CabloyJS made in the second half of 2026 is a systematic answer to exactly this pain point. No longer satisfied with being a TypeScript fullstack framework that helps developers scaffolding CRUD faster, CabloyJS has been proactively restructuring itself into an AI Spec-Driven Development (AI-SDD) framework purpose-built for AI Vibe Coding.

This evolution can be organized into three clear threads.

Thread One: Turn "having AI write code" into "having AI deliver against a specification"

Most AI coding assistants follow this model: give a description, AI generates a chunk of code based on context. This model works well for local tasks, but inside complex systems that span multiple modules and both frontend and backend, AI faces a fundamental dilemma — it does not know where its boundaries are.

CabloyJS's answer is a set of built-in Claude Code Skills that splits the development workflow into two strict phases.

Phase One: Establish "specification authority" inside the repository

The first Skill, cabloy-spec-generation, does not write code. Its job is to establish explicit specification files inside the repository so that both AI and humans read the same source of truth. A typical output is a set of mutually referencing Spec files covering product requirements, technical contracts, delivery plans, acceptance criteria, and architecture decision records.

The key is not merely "having a pile of documents on disk." It is separated authority: each file owns one kind of fact, and other files refer to it through stable IDs. Product requirements do not prescribe table names; technical contracts do not redefine business rules; delivery plans do not rewrite upstream authority. AI never has to guess "what is the boundary of this module?" — it goes and reads the Spec that is already there.

Phase Two: Let AI execute bounded increments

Only after the specification is in place does the second Skill, cabloy-spec-execution, start touching code. It does not "look at a prompt and change things randomly." It follows a strict execution chain:

Read specs → confirm boundaries → generate execution dossier → make source changes → run verification → save evidence → update progress

Every step has a confirmation gate. AI does not automatically expand the task scope, does not skip verification steps, and does not pretend "it's done" when verification fails. The final deliverable is not just a chunk of code — it is source changes plus an auditable Evidence record plus updated progress state.

Putting these two phases together, CabloyJS is doing something deliberately simple: it prevents AI from jumping straight from a vague prompt to writing code. Instead, it inserts a Spec-based middle layer that gives AI clear behavioral boundaries within that layer.

What distinguishes this from traditional "spec-driven development" is that in the traditional model, specs are documents written for humans. In CabloyJS, specs are machine-readable authority written for both AI and humans. AI does not merely "consult" the Spec — its entire execution flow is driven by it.

Thread Two: A side effect of AI-SDD — charts are automatically derived from Specs

When every AI operation is constrained by the Specs and updating the same progress file, a natural question emerges: can we directly derive agile visualization charts from this structured data?

The answer is yes. CabloyJS's Spec system ships with a small toolchain that automatically derives two charts from the WBS (Work Breakdown Structure) and progress files:

Gantt: shows delivery phases, task order, dependencies, and current status
Burndown: shows the approved scope task counts and remaining items

These charts are not hand-drawn pictures — they are direct visualizations of the Spec data. When AI finishes a WBS task and updates the progress file, running the generation script once more updates the charts automatically.

On the surface this looks like a "cool small feature," but in the AI-SDD context its significance is completely different. It means: while AI is writing business code, it is also automatically maintaining the agile progress visualization of the entire project.

You ask AI to build a CRM system. AI is not just helping you write the customer-management CRUD — it is simultaneously updating task dependencies on the Gantt chart and marking completed work items on the Burndown. The entire development pipeline becomes one continuous flow instead of the split state where "AI writes code, humans manually update Trello/Jira."

One sober expectation is worth keeping: auto-generated charts are structural views, not calendar schedules or velocity forecasts. They tell you what delivery packages exist, their approximate ordering, and which ones have been verified — but they will not tell you whether everything can ship by next Wednesday. That is intentional. AI should not be held responsible for calendar commitments until it truly has business understanding. Until then, treating the charts as "real-time snapshots of structure and state" is the more pragmatic choice.

Thread Three: Dual-Engine Architecture — why Cabloy's Vona + Zova is naturally suited for AI-SDD

The foundation of CabloyJS is two independently evolving engines: Vona for the backend and Zova for the frontend. They are not "a backend folder and a frontend folder inside one big project." Each has its own IoC containers, Bean systems, and CLI. They mesh together through build artifacts and a bidirectional contract loop.

This architecture gives CabloyJS a tremendous natural advantage in AI-SDD: backend truth and frontend truth are separate, so AI cannot randomly mess with both sides at once.

Backend truth: Vona's OpenAPI contract

Vona's Controllers, DTOs, and Zod schemas automatically produce an OpenAPI document through decorator metadata. That OpenAPI document is the single source of truth for frontend SDK generation. When changing a backend interface, the correct order is always:

Change Vona's DTO/Controller/Zod → emit new OpenAPI → regenerate Zova's $api SDK and $apiSchema helper

AI will not "invent" a backend interface on the frontend, because it knows the contract truth lives on the Vona side — the frontend is only a consumer.

Frontend truth: Zova's routes, components, and metadata

Conversely, Zova's routes, components, icons, and type definitions are the frontend truth. After building, this metadata flows back into Vona's tooling through a reverse chain, giving the backend tooling perfect IDE type hints. The correct order here is likewise enforced:

Change Zova's routes/components → build Zova (emit rest artifacts) → run deps:vona to sync into Vona

The repository itself wires a contract-loop-gate into git hooks, which automatically checks whether this chain has been broken at commit time. That means "bidirectional contract" is not a documentation slogan — it is an engineering guardrail.

Why this matters for AI

When AI knows that backend truth lives in Vona and frontend truth lives in Zova, and that syncing them has explicit commands and guardrails, it will not freely add fields on both sides, guess interface names, or copy-paste schema definitions. AI only needs to answer three questions:

Is this capability backend or frontend?
Which side's truth do I need to change?
Which command do I run to propagate the change to the other side?

All three answers are defined by the framework. AI does not have to guess.

A new edition split: two MIT baselines

Another important change in 2026 is that CabloyJS's open-source editions have been formally split into two V5+ architecture MIT baselines.

Cabloy Basic (reference edition)

UI layer: DaisyUI + Tailwind CSS, a modern lightweight frontend
Built-in demo: A complete e-commerce suite (a-commerce) including Admin back-office, Web storefront, shopping cart, and payment flows
Positioning: Learn the fullstack pattern, build prototypes, or start projects that need a lightweight UI layer
License: MIT

Cabloy Start (full-featured edition)

UI layer: Vuetify, a UI component library
Built-in demo: Complete system management, department management, menu authorization, and data-scope-based RBAC
Positioning: Starting point for projects that need enterprise-grade permissions, menus, and department structures
License: MIT

This split itself is an extension of the AI-SDD philosophy: choose a baseline that fits your business starting point first, then let AI deliver bounded increments within that boundary — instead of starting from an empty project and asking AI to guess everything from scratch.

So what is CabloyJS now?

Putting the 2026 changes together:

It is no longer just a TypeScript fullstack framework that helps you scaffolding frontend and backend faster. It is a working system that makes AI Vibe Coding traceable, bounded, and verifiable:

The AI-SDD two-phase workflow makes AI work under specification authority instead of guessing under vague prompts
Auto-derived charts visualize every step of AI progress, so the development pipeline is no longer split in two
The dual-engine plus contract loop architecture gives frontend and backend each their own source of truth, so AI will not mess with both sides simultaneously
Two MIT baselines let you start from the right point for your business instead of building everything from zero

Its ambition is clear: be the best fullstack Vibe Coding framework in the AI era — not by "layering prompt engineering on top," but by using strict typing, repository-internal specification authority, and engineering guardrails to turn the previously uncontrolled "blind AI code generation" into an industrial pipeline that is specification-driven, evidence-backed, and automatically reportable.

Start with a small increment

If you want to feel this workflow yourself, begin from the public scaffolding:

npm create cabloy
npm run dev
npm run dev:zova:admin
npm run dev:zova:web

Then pick a clearly bounded requirement — say, "add a category filter to products" — and run through the full cabloy-spec-generation → cabloy-spec-execution flow. You'll notice that when AI no longer has to guess boundaries, contracts, or the definition of done, its behavior quality jumps up visibly.

NestJS Dynamic Providers vs Cabloy/Vona Provider Scene: Two Ways to Bind One Interface to Many Implementations

Uncle Pushui — Wed, 14 Oct 2026 16:06:31 +0000

Both frameworks answer "one interface, many implementations, pick one at runtime". They disagree not on the implementation technique, but on when the binding happens.

"One interface, several implementations, choose one by configuration or context" is a question every backend framework has to answer. Payments must switch between Stripe, PayPal, and a mock. File storage must switch between local disk and object storage. Captcha must switch between an image puzzle and an SMS code.

NestJS answers it with Dynamic Providers; Cabloy/Vona answers it with a Provider Scene. Both work, but the assembly models are fundamentally different — and that difference propagates all the way to runtime switching, module decoupling, and the more fundamental question of what a consumer actually holds a reference to.

The Short Conclusion

Dimension	NestJS Dynamic Providers	Vona Provider Scene
Binding timing	Once, during module initialization	On every resolution, by name
Expression	`{ provide: TOKEN, useClass: X }`	`@PayProvider()` registers into a scene
Many implementations per interface	Aggregated via `multi: true`, or one token each	N registered under one scene, peers by default
Where implementations live	Usually in one module's `providers` array	Each implementation is a separate module
What the consumer references	An injected token	A name
Runtime switching	Effectively fixed after init (`overrideProvider` only applies while compiling a test module)	`VonaConfig.onions` + per-request `ctx.onionsDynamic`
Contribution to dependency structure	Participates in the assembly graph	Produces no static dependency edges

In one sentence: NestJS binds a token to an implementation in the single assembly phase; Vona defers "which implementation" to every resolution, so it never has an assembly order that could be broken.

The Problem: One Interface, Many Implementations

First, the shared problem. Business code wants to be written like this:

// The consumer depends only on the abstraction
const result = await payService.startPayment({ provider: 'stripe', orderId, amount });

It should not care how Stripe's SDK, PayPal's OAuth flow, or the mock's fixtures are implemented, and adding a new payment method should not force a change here.

The divergence appears at one step: how payService obtains the stripe implementation object.

NestJS's Answer: Bind During Assembly

NestJS expresses this relationship as a provider definition, most commonly useClass:

// pay.module.ts
@Module({
  providers: [
    { provide: PAY_PROVIDER, useClass: StripePayProvider },
  ],
  exports: [PAY_PROVIDER],
})
export class PayModule {}

When several implementations must coexist, multi: true aggregates them into an array:

@Module({
  providers: [
    { provide: PAY_PROVIDER, useClass: StripePayProvider, multi: true },
    { provide: PAY_PROVIDER, useClass: PaypalPayProvider, multi: true },
    { provide: PAY_PROVIDER, useClass: MockPayProvider, multi: true },
  ],
})
export class PayModule {}

The consumer injects the token and receives the bound instance or array:

constructor(@Inject(PAY_PROVIDER) private readonly pay: IPayProvider) {}

useFactory can also express "pick one by configuration":

{
  provide: PAY_PROVIDER,
  useFactory: (config: ConfigService) =>
    config.get('PAY_DRIVER') === 'paypal'
      ? new PaypalPayProvider()
      : new StripePayProvider(),
  inject: [ConfigService],
}

The Key Constraint: Binding Happens Once

Whether you use useClass, useValue, or useFactory, that binding logic runs once, during module assembly: when NestFactory.create() bootstraps the application, the container resolves every module's providers into instances and wires them, and the same instances are reused for the rest of the process lifetime.

Three practical consequences follow:

The set of implementations is fixed at startup. You cannot "register" a new payment implementation at runtime — module assembly is not a runtime behaviour, and the length of a multi: true array is likewise determined during assembly.
Changing the selection at runtime requires a detour. Reading config inside useFactory is fine, but it computes its result during assembly; to change it later you must inject ModuleRef, wrap a mutable factory object, or make the whole provider request-scoped.
Implementation and module boundaries tend to blur. Three payment implementations often end up in the same module's providers array, so "add a payment method" becomes "edit the existing payment module". Separate modules are possible, but that requires deliberate effort rather than being the framework's default shape.

overrideProvider(TOKEN).useClass(...) is available only while compiling a testing module with Test.createTestingModule(). That is an assembly-time behaviour, not a runtime capability.

Vona's Answer: Select at Resolution Time

Vona expresses this relationship as a scene: each business area owns a named provider scene and a matching decorator. For payments:

// a-pay/src/lib/payProvider.ts
export const PayProvider = createBeanDecorator('payProvider', ...);

Implementations then live in separate modules, siblings of the domain module:

Area	Scene	Implementations (each its own module)
Auth	`authProvider`	`auth-simple`, `auth-oauth`
Captcha	`captchaProvider`	`captcha-simple`
Pay	`payProvider`	`pay-stripe`, `pay-paypal`, `pay-mock`
Image	`imageProvider`	`image-native`, `image-cloudflare`
File	`fileProvider`	`file-native`, `file-cloudflare`

Each implementation is simply "a bean registered under a scene":

// pay-stripe/src/bean/payProvider.stripe.ts
@PayProvider()
export class PayProviderStripe extends BeanBase implements IPayProviderExecute {
  async startPayment(options) { /* Stripe SDK */ }
}

What the Consumer Holds Is a Name, Not a Reference

The pay facade obtains implementations by asking the container for a name:

// a-pay/src/bean/bean.payProvider.ts
get<N extends keyof IPayProviderRecord>(providerName: N) {
  const beanFullName = beanFullNameFromOnionName(providerName, 'payProvider');
  return this.app.bean._getBean(beanFullName);
}

And the name translation is a single string replacement:

// onionName = 'pay-stripe:stripe'
// → beanFullName = 'pay-stripe.payProvider.stripe'
onionName.replace(':', '.payProvider.');

So pay-stripe:stripe becomes a container key only at the moment of the call, and the container resolves the instance on demand. The consuming module never imports any concrete implementation — it knows a name.

Selection Happens at Resolution Time, Not Assembly Time

Which implementation is active is decided by three layers, all read at resolution time:

1. Configuration — VonaConfig.onions

Each scene keeps its own enabled entries and options in config, and the framework uses them to decide whether an implementation is usable in the current context.

2. Request scope — ctx.onionsDynamic

A single request can override the selection, for example to disable one aspect in a test:

await app.bean.executor.performAction('post', '/api/test', {
  onions: { interceptor: { 'a-ratelimit:rateLimit': { enable: false } } },
});

3. Scene resolver

For the captcha scene, a scene can select one provider, rotate across several, or vary the choice by user state and business context.

On top of that, each implementation carries enable / match / ignore metadata, filtered at resolution time by checkOnionOptionsEnabled() to decide whether it is active in the current runtime.

The Unit of Extension Is a Module

Adding a payment method means adding a module (scaffolded for you): one new implementation registered into the payProvider scene, with no change to existing implementations or to the consumer.

The Comparison: How Binding Timing Decides Everything

Angle	NestJS assembly-time binding	Vona resolution-time selection
When the token becomes an implementation	At module initialization	On every `get()`
Who changes when adding the Nth implementation	Usually the existing module's providers	A new independent module
Runtime switching	Needs `ModuleRef` / request scope / mutable factory	A config entry or a request-level override
What the consumer holds	An already-resolved instance	A name
Can an implementation form a dependency cycle with its consumer	Possible (recursive resolution during assembly)	No (resolved by name at runtime)

The last row deserves attention. In Vona, the only path from consumer to implementation is "name → container lookup" at runtime: registering the Nth implementation adds zero edges to the dependency structure.

That is exactly why Vona needs no cycle-breaking mechanism at all: there is no recursive resolution during assembly, and no static edge whose number changes with the number of implementations.

When to Use Which

When N implementations must coexist and rotate within one request path (risk-control strategy chains, notification channel rotation): NestJS's multi aggregation works well; on the Vona side, a scene resolver takes on "rotate / choose by user state" logic of this kind.
When the implementation is long-lived, replaceable infrastructure (payment, storage, captcha, auth methods): Vona's Provider Scene fits better, because each implementation is naturally an independent module and switching is a configuration change rather than an edit to an existing module.
When you only need to swap one dependency in a test: NestJS's overrideProvider is more direct; Vona reaches the same end with a per-request onionsDynamic or a config override.

Neither model is strictly better: NestJS's assembly-time binding makes relationships explicit and statically checkable; Vona's resolution-time selection makes extension and switching looser. What actually matters is whether your extension point is determined at startup or variable at runtime.

Summary

NestJS Dynamic Providers and Vona Provider Scene both answer "one interface, many implementations", but they land in different places:

NestJS binds a token to an implementation during assembly — explicit relationships, but the implementation set and binding result are fixed after startup;
Vona selects an implementation by name at resolution — the consumer holds only a name, and implementations register as peers in independent modules;
That difference in timing decides runtime switching, module decoupling, and the more fundamental conclusion about whether an implementation can form a dependency cycle with its consumer.

Put another way, Vona did not make Dynamic Providers smarter; it moved the binding later. As long as the binding happens at resolution time, many implementations cost the dependency structure nothing.

References and Source Code

NestJS

CabloyJS / Vona

How Cabloy/Vona Avoids NestJS Circular Dependencies: A Source-Code Walkthrough of Lazy Property Injection

Uncle Pushui — Wed, 14 Oct 2026 02:36:05 +0000

Circular dependency is not about "can it be resolved?" — it is about "when does resolution happen?"

NestJS circular dependencies are a frequently discussed topic: two Services inject each other through their constructors, and the instantiation moment falls into a "chicken-or-egg" deadlock that can only be broken with forwardRef(). Cabloy/Vona does not have this problem at the architectural level — not because it implements smarter cycle detection, but because it defers dependency resolution to first access.

This article uses Cabloy/Vona's BeanContainer and @Use decorator source code to break down the complete implementation of lazy property injection.

The Short Conclusion

Dimension	NestJS Constructor Injection	Vona Lazy Property Injection
Injection timing	Synchronous during instantiation	Deferred to first property access
Circular dependency	Requires `forwardRef()` + deferred cycle resolution	Naturally safe, no special handling
Constructor parameters	Dependencies passed as constructor arguments	Zero constructor dependencies, only getters
Resolution entry	Container recursively resolves during `resolve()`	Getter triggers container cache lookup
Caching strategy	Stored in container after instantiation	Entered into container cache before `__init__`

In one sentence: NestJS is "inject at construction time, resolve eagerly" — cycles deadlock during instantiation. Vona is "register at declaration time, resolve on access" — the instantiation phase never touches dependencies, and circular dependencies are dissolved by timing.

The Root of NestJS Circular Dependencies

First, let us understand where NestJS's problem lies.

The Timing Dilemma of Constructor Injection

NestJS dependency injection happens during the constructor phase. When the container resolves A:

@Injectable()
class ServiceA {
  constructor(private readonly b: ServiceB) {}  // Constructor parameter = dependency
}

The container needs to create B before it can create A. But if B's constructor also depends on A:

@Injectable()
class ServiceB {
  constructor(private readonly a: ServiceA) {}
}

The resolution chain becomes: new A() → needs B → new B() → needs A → A is not yet constructed → deadlock.

forwardRef Is a Workaround, Not an Elimination

NestJS uses forwardRef() and InjectionToken to defer the resolution order, letting one side complete instantiation first, then injecting the other side afterward. But this is merely a workaround:

Developers must manually identify cycles and annotate with forwardRef;
Over-long cycle chains may still encounter "instance not ready" problems;
It adds implicit complexity to the code.

Vona's design chose a different path: it does not give circular dependencies any opportunity to arise in the first place.

Vona's Three Lines of Defense

Vona structurally does not have an "instantiation-phase" circular dependency problem. The core difference is that dependency resolution is moved from instantiation time to first access time. Three mechanisms ensure this:

1. No Constructor Injection

Vona's Service/Bean always extends BeanBase, and the constructor accepts no dependencies. After instance creation, the container fills in app / ctx references, and dependencies are declared on properties via the @Use(...) decorator.

2. Lazy Property Injection (the Key Mechanism)

Dependencies declared with @Use are not injected at Bean creation time. Instead, a getter is installed using Object.defineProperty. On first property access, the getter resolves the target Bean from the container and caches the result.

3. Container Itself Is Runtime Lookup

BeanContainer.create returns a lazy Proxy. this.bean.xxxService, this.scope('module-x') all resolve from the container by bean full name at access time, producing no static wiring.

Source Code Breakdown: Five Stages

Below, we break down the source code across five stages: declaration → storage → mounting → resolution → caching.

Stage 1: Declaration — `@Use` Decorator Does Only Two Things

// use.ts
export function Use(options?: IDecoratorUseOptions | string): PropertyDecorator & MethodDecorator {
  return function (target: object, prop: MetadataKey, descriptor?: PropertyDescriptor) {
    // ① Read property type from TS design:type metadata
    const beanClass = appMetadata.getDesignType(target, prop) as Constructable;

    // ② Class → bean full name mapping
    let beanFullName: string | undefined = options.beanFullName;
    if (!beanFullName) {
      beanFullName = appResource.getBeanFullName(beanClass);
    }

    // ③ Register metadata — no instantiation happens here
    appResource.addUse(target, { ...options, prop, beanFullName, descriptor });
  };
}

It reads the property type from the design:type metadata generated by TypeScript's emitDecoratorMetadata, so @Use() without arguments can still determine the target Bean;
The class → bean full name (module-name.scene.name) mapping must exist, otherwise it throws directly;
It calls appResource.addUse to register metadata — no instantiation occurs.

Stage 2: Storage — Metadata Map Keyed by Property Name, Inherited Along the Prototype Chain

// resource.ts
addUse(target: object, options: IDecoratorUseOptionsBase) {
  registerMappedClassMetadataKey(target, SymbolDecoratorUse);
  const uses = appMetadata.getOwnMetadataMap(true, SymbolDecoratorUse, target);
  uses[options.prop] = options;
}

getUses(target: object): Record<MetadataKey, IDecoratorUseOptionsBase> | undefined {
  return appMetadata.getMetadata(SymbolDecoratorUse, target);  // Note: getMetadata
}

Writing uses getOwnMetadataMap (attached to the class prototype, keyed by prop), reading uses getMetadata (traverses up the prototype chain) — this means subclasses automatically inherit all @Use dependencies declared by the parent class.

Stage 3: Mounting — Only Install Getter After Instantiation, No Resolution

The strict ordering in the Bean instance creation flow:

// beanContainer.ts
private _createBeanInstance(...) {
  const beanInstance = this._prepareBeanInstance(...);          // new + attach app/ctx
  this[SymbolBeanContainerInstances][key] = beanInstance;       // ① Enter container cache first
  this._initBeanInstance(beanFullName, beanInstance, args);     // ② Inject getter → __init__
}

This ordering ensures: even if a Bean accesses a dependency property during __init__, triggering reverse resolution, the container can directly hit the cache and return the already-registered instance.

The core implementation of injection:

// beanContainer.ts
private _injectBeanInstancePropLazy(beanInstance, prop, targetBeanFullName, useOptions) {
  const self = this;
  Object.defineProperty(beanInstance, prop, {
    enumerable: true,        // Property is enumerable (visible in serialization/spread)
    configurable: true,      // Redefinable for HMR
    get() {
      if (!beanInstance[SymbolBeanInstancePropsLazy])
        beanInstance[SymbolBeanInstancePropsLazy] = {};
      if (!beanInstance[SymbolBeanInstancePropsLazy][prop]) {
        // First access: actually resolve, then cache to instance-private slot
        beanInstance[SymbolBeanInstancePropsLazy][prop] =
          self._injectBeanInstanceProp(beanInstance, targetBeanFullName, useOptions);
        // App-level container additionally registers this dependency edge to HMR
        self.containerType === 'app' &&
          self.app.meta.hmr.addBeanInstanceProp(beanInstance, prop, targetBeanFullName);
      }
      return beanInstance[SymbolBeanInstancePropsLazy][prop];
    },
  });
}

Three implementation highlights:

The getter closure captures the container that installed it (self) — properties installed by the app container always go through app resolution, while those installed by the ctx (request-level) container go through ctx resolution;
The cache slot is an instance-level plain object SymbolBeanInstancePropsLazy — after first access, the property degrades to "pseudo-static" with zero lookup cost thereafter;
The enumerable: true / configurable: true combination is deliberate: enumerable ensures consistent instance export behavior, configurable lets HMR tear down and reinstall.

Stage 4: Resolution — Three Injection Scopes

First access triggers _injectBeanInstanceProp:

// beanContainer.ts
private _injectBeanInstanceProp(
  beanInstance,
  targetBeanFullName: string,
  useOptions: IDecoratorUseOptionsBase,
) {
  const injectionScope = useOptions.injectionScope ?? 'app';

  if (injectionScope === 'app') {
    targetInstance = this.app.bean._getBeanSelectorInner(...);  // Application-level singleton
  } else if (injectionScope === 'ctx') {
    targetInstance = this._getBeanSelectorInner(...);           // Request-level singleton
  } else if (injectionScope === 'new') {
    targetInstance = this._newBeanInner(...);                   // New instance each time
  }
  return targetInstance;
}

'app' / 'ctx' fall into _getBeanSelectorInner: the container instance cache key is beanFullName or beanFullName#selector, creating only if === undefined;
'new' creates a new instance each time, but since the outer getter already caches, only one resolution happens per property lifecycle;
The selector parameter is taken from three sources by priority: the decorated property's descriptor getter → useOptions.init static parameters → useOptions.selector string expression (evaluation context includes self/app/ctx).

Stage 5: Caching — Container Instance Cache

The caching logic of _getBeanSelectorInner:

// beanContainer.ts
_getBeanSelectorInner<T>(
  beanFullName: Constructable<T> | string,
  withSelector?: boolean,
  ...args
): T {
  const beanOptions = appResource.getBean(beanFullName as any);
  const fullName = beanOptions.beanFullName;
  const key = __getSelectorKey(fullName, withSelector, args[0]);
  if (this[SymbolBeanContainerInstances][key] === undefined) {
    this._newBeanInner(true, fullName, withSelector, ...args);
  }
  return this[SymbolBeanContainerInstances][key] as T;
}

Cache key generation:

function __getSelectorKey(beanFullName: string, withSelector?: boolean, selector?: any) {
  if (!withSelector) return beanFullName;
  const isSelectorValid = !isNilOrEmptyString(selector);
  return !isSelectorValid ? beanFullName : `${beanFullName}#${selector}`;
}

Complete Timing of A↔B Circular Dependency

Using two Services A and B that @Use each other as an example, here is the complete timing:

Moment	Action	Result
Declaration	`@Use` registers A→B, B→A mappings	No instance interaction
Business triggers `_getBean('A')`	`new A()`, install lazy getter, enter container cache	A fully exists
First access `a.serviceB`	Getter executes → container creates B (B's construction and getter installation also do not touch A), enters cache	B fully exists
B internally accesses `b.serviceA`	Getter executes → container cache hit → returns existing A	Cycle closes, no reentrance

Two invariants guarantee cycle safety:

Getters never execute during the instantiation phase (no mutual touching);
The dependency target is guaranteed to be registered in the container cache at resolution time (the "enter cache before init" ordering covers even the aggressive case of accessing dependencies during __init__).

Real Code Example

Vona's `@Use` Usage

import { BeanBase, Use } from 'zova';
import { Service } from 'zova-module-a-bean';

@Service()
export class BeanRouter extends BeanBase {
  @Use()
  $$sysRouter: SysRouter;

  @Use()
  $$modelPageData: ModelPageData;
}

Note: zero constructor parameters; all dependencies are declared on properties via @Use. Resolution is triggered only when this.$$sysRouter is accessed.

Equivalent Path in Vona Backend Business Code

In the current repository, backend business code more commonly uses this.scope('module-x').service.yyy and this.bean.xxx instead of property-level @Use — these go through the same container's runtime lookup path:

// BeanContainer.create returns a Proxy
static create(app: VonaApplication, ctx: VonaContext | undefined) {
  const beanContainer = new BeanContainer(app, ctx);
  return new Proxy(beanContainer, {
    get(obj, prop) {
      if (typeof prop === 'symbol') return obj[prop];
      if (obj[prop]) return obj[prop];
      return obj._getBean(prop as any);  // Resolves on access
    },
  });
}

This is essentially the "method-call version" of the same lazy resolution mechanism. The two paths differ only in declaration style (decorator metadata vs string lookup); the resolution and caching mechanisms are fully shared.

Failure Boundary and HMR

Lazy property injection is not without boundaries to be aware of:

_removeBean only destroys the instance in the container cache and calls its __dispose__; the cached reference in other Bean instances' SymbolBeanInstancePropsLazy is not automatically cleared — this is exactly why HMR needs addBeanInstanceProp to register dependency edges for rewiring.

So in hot-reload scenarios, the framework can use the registered dependency edges to find all properties that reference the replaced Bean, tear down old getters, install new ones, clear cache slots, and complete dependency rewiring.

Module-Level Circular Dependencies

Beyond instance-level circular dependencies, Vona also makes design-level provisions at the module level. Per the documentation:

Using this.$scope.<fixedModule>, app.scope(...), or this.app.scope(...) does not by itself require adding the target module to the caller's vonaModule.dependencies. Lookup does not create a module dependency edge, so lookup alone cannot create a circular dependency.

This means module-level circular dependencies are also avoided by design: cross-module lookups do not produce dependency declarations and do not constitute module dependency edges, so modules cannot form circular dependencies merely by "using each other's services."

Summary

The root cause of NestJS's circular dependency problem lies in its design choice of "constructor injection + eager resolution": dependencies must be resolved at instantiation time, circular references inevitably lead to deadlock, and forwardRef can only defer the resolution order.

Vona's lazy property injection mechanism dissolves this problem through three design decisions:

Zero constructor dependencies — the instantiation phase touches no dependencies;
Lazy property getter — dependency resolution is deferred to first access;
Enter cache before init — guarantees the dependency target is always ready at resolution time.

Circular dependencies in Vona require no forwardRef, no special annotation, no developer identification of cycles — they are naturally safe by timing. This is not smarter cycle detection; it is an architectural choice that gives circular dependencies no opportunity to arise.

References and Source Code

NestJS

CabloyJS / Vona

Inside Cabloy's Dual-Engine Architecture: How Vona and Zova Work Together

Uncle Pushui — Sun, 11 Oct 2026 14:43:33 +0000

Vona provides the backend framework and runtime; Zova provides the frontend framework and application layer. They are not a "backend folder + frontend folder" inside one big package. They are two engines that evolve independently, meshed together by generated artifacts, runtime integration, and bidirectional type contracts.

The first thing people notice when opening the Cabloy repository is usually the two large top-level directories: vona/ and zova/. Each has its own package.json, CLI, and workspace configuration, and each even carries its own __CABLOY_BASIC__ edition marker. This is not simply a "backend directory plus frontend directory" — it is the core design of Cabloy's fullstack architecture: one fullstack system, two engines.

This article walks through that dual-engine architecture end to end, using the Cabloy Basic repository (version 5.1.202, MIT licensed) as the baseline.

The Big Picture First

                     ┌──────────────────────────────────────────┐
   Browser  ───────▶ │  Vona (backend runtime, Koa, port 7102)  │
                     │   ├─ SSR Site dispatch (Web/Admin/...)   │
                     │   └─ Renders with Zova-built SSR output  │
                     └───────────▲──────────────────┬───────────┘
       Frontend metadata         │                  │  OpenAPI contracts
       (routes/components/icons) │                  ▼  flow downstream
                     ┌───────────┴──────────────────────────────┐
                     │  Zova (frontend, Vue3 + Vite + TSX)      │
                     │  Standalone SSR dev server (port 9000)   │
                     └──────────────────────────────────────────┘

The key principle: frontend and backend concerns are separated and can evolve independently — but they do not collaborate by hand-copying interfaces or manually copying build files. They collaborate through generated artifacts, runtime integration, and shared conventions.

Backend technology base: Koa, Knex, Redis, and multiple database drivers (CI covers MySQL and PostgreSQL)
Frontend technology base: Vue, Vite, the Quasar toolchain, and TanStack libraries
Edition UI layer: Cabloy Basic uses DaisyUI + Tailwind CSS; Cabloy Start uses Vuetify. Quasar is part of the engineering toolchain, not the edition's UI component library

Part 1. Vona: The Backend Engine

Vona is the backend half of Cabloy. Its goal is to support SSR, SPA, Web, and Admin experiences within one system while keeping frontend and backend decoupled enough to evolve independently.

1. IoC Containers and the Bean System

Every capability in Vona is organized as a framework-managed Bean. All Beans inherit from BeanBase, whose working surface already includes app, ctx, bean, scope, $scope, $logger, $loggerChild, $text, and more — business code never needs to reassemble these access points by hand.

There are two container levels:

Container	Responsibility
app container	Global backend Beans (singleton-style)
ctx container	Request-scoped Beans

A Bean has three forms of identity, and naming is not a style preference — it directly affects injection, config override paths, and how the CLI organizes generated code:

Bean identifier: {moduleName}.{sceneName}.{beanName}, e.g. training-student.service.student
Onion name: {moduleName}:{beanName}, e.g. training-student:student
Bean scene: the operational family a Bean belongs to — service, model, entity, dto, controller, startup, queue, broadcast, and so on. The built-in global bean scene is a deliberate exception with a plain shorthand surface

There are four styles of accessing a Bean:

Access style	Best for	Representative shape
Dependency injection	Explicit wiring in a class	`@Use('training-student.service.student') serviceStudent`
Dependency lookup (the recommended concise default)	Ordinary module business code	`this.scope.service.student.findOne()`
Direct bean access	Container-level control	`this.bean._getBean(...)` / `this.ctx.bean._getBean(...)`
Fresh bean creation	Flows that must not reuse the default instance	`this.bean._newBean(...)`

Note that this.bean._getBean(...) goes through the app-level container, while this.ctx.bean._getBean(...) goes through the request-scoped container.

2. Scope: The Module Resource Facade

The reason Vona backend code stays concise instead of degrading into arbitrary-path imports everywhere is Scope. Each module's service, model, entity, config, constant, locale, and error resources all hang behind one structured facade:

// Resources of the current module
this.scope.model.stockBalance

// A cross-module resource statically known in source
this.$scope.commerceCatalog.model.sku

// In tests or standalone scripts, where you hold an app reference
app.scope('commerce-catalog').model.sku

One important design decision: Scope lookup does not create a module dependency edge. this.$scope.xxx merely resolves a resource from the module set already composed into the application; it neither installs nor loads the target module, and it cannot cause circular dependencies. Only when you genuinely need availability guarantees, dependency-first ordering, or a minimum compatible version do you declare vonaModule.dependencies.

3. AOP and the Structured Request Pipeline

Vona provides AOP across three aspect families — controller, internal, and external — plus a structured request path:

middleware → guard → interceptor → pipe (Zod validation) → filter

The @Core.transaction(...) and @Core.retryable(...) decorators you see in everyday development are both applications of this AOP:

@Core.transaction(...) defaults to REQUIRED propagation: start a transaction if none exists, otherwise join the current one; never escalate isolation casually. Use REQUIRES_NEW only when an independently committed boundary is explicitly required
@Core.retryable(...) retries only safely replayable transient failures through an explicit errorCodes allowlist. It retries the downstream AOP suffix and never blindly retries external side effects

4. Contracts and the Data Layer: Source of Truth for the Forward Chain

The main backend request-handling chain is:

Controller → Service → Model → Entity
             (DTO inference/generation + Zod validation)

Controller, DTO, and Zod schemas — together with decorator metadata such as @Api.field(...) — ultimately produce the OpenAPI document. That OpenAPI output is the single source of contract truth for frontend SDK generation, which becomes crucial in the contract loop below.

Vona also ships a broad set of long-term capabilities: CRUD-oriented workflows, multi-tenancy (a tenant is an instance; ordinary resource CRUD is automatically instance-scoped), multi-database/multi-datasource with sharding, two-layer caching (including the cross-Model modelsClear / modelsClearedBy dependency graph), transactions, authentication/captcha/RBAC/menus, file and image uploads, mail, queues, workers, schedules, election, broadcast, Redlock, WebSocket, metrics, and telemetry.

In terms of code organization, the framework core lives in vona/packages-vona/, the CLI in vona/packages-cli/cli/, and business code in vona/src/suite/ and vona/src/module/.

Part 2. Zova: The Frontend Engine

Zova is the frontend half of Cabloy. It combines the strengths of three mature frameworks: Vue3 reactivity, React-style TSX rendering, and Angular-style IoC. When reading Zova code, do not degrade it into "plain Vue plus a pile of utilities" — enter through its controller / bean / IoC architecture.

1. Three IoC Containers Unify All State Sharing

Many Vue 3 projects mix component-local state, composables, provide/inject, and Pinia depending on where state must be shared. Zova asks a different first question: which Bean owns this state or behavior, and which container scope should own that Bean?

Container	Scope	Rough Vue-world equivalent
sys	System-wide singleton; survives across SSR requests	Module-level singletons / global long-lived state
app	Application / request level	App stores, globally provided state
ctx	Component-instance local	Component-local state, in-component composables

The four typical sharing scopes therefore all fold into one model:

class ControllerPage {
  @Use() $$localCounterState: CounterState;                          // within a component
  @Use({ injectionScope: 'host' }) $$hostCounterState: CounterState; // between components (hierarchical injection)
  @Use({ injectionScope: 'app' })  $$appCounterState: CounterState;  // app-global
  @Use({ injectionScope: 'sys' })  $$sysCounterState: CounterState;  // system-level
}

Under SSR, the distinction between app and sys is especially critical: app-level behavior can bind to a single application instance or a single request, while sys-level behavior is not request-bound and survives across SSR requests.

All Beans likewise inherit from BeanBase, whose core members include sys, app, ctx, bean, scope, $el, and $event; SSR modules extend it with $ssr and $useMeta, page-controller bases provide $params and $query, and component-controller bases provide $props.

2. Controller / Page / Component: TSX Rendering

Every Zova page and component has a controller bean as its logic carrier, with rendering described in TSX. The surrounding frontend engineering capabilities include:

a-router routing: routes with dynamic params must explicitly define route.name; static routes generate canonical URLs via $router.getPagePath(...)
Page meta code generation
Two-layer tabs navigation, router stack, routed dialog
Explicit requiresAuth and ssrProfile declarations (Web defaults to public; cookie-backed or protected first paint uses session)

3. Unified State Management with Models and ModelResource

Async state that drives rendering is owned by Models, not scattered across fetch/cache variables in individual controllers:

Establish query state during render with $useStateData(...), and read the reactive surface owned by the current query (query.data or a model-derived projection)
Resource-style business data is owned by a ModelResource, which uniformly handles queries, caching, and mutations; $apiSchema or the owning resource's schema directly drives automatic rendering of ZForm and ZTable
Only low-reuse, one-off page actions that need no shared state or cache ownership may call the generated $api directly

The purpose of these rules is clear: there is exactly one copy of schema metadata (on the backend); the frontend neither duplicates schemas nor hand-edits generated code.

4. Multi-Flavor Output: One Codebase, Many SSR Sites

The same Zova business source code can be built into multiple flavors (i.e., SSR Sites). The actual build artifacts in this repository (zova/dist/) include:

ssr-cabloyBasicWeb / ssr-cabloyBasicAdmin: the Web and Admin sites of Cabloy Basic
ssr-cabloyCommerce / ssr-cabloyCommerceAdmin: the e-commerce demo sites
rest-cabloyBasicWeb and other rest artifacts: frontend metadata and type packages consumed by Vona

Each flavor has its own env files (zova/env/.env.*), and at build time the SSR bundle and rest output must be produced as a pair and moved together.

Part 3. How the Two Engines Mesh: Two Channels

Between Vona and Zova there are two channels of an entirely different nature.

Channel 1: Vona Integrated SSR (the Runtime Channel)

The same frontend SSR application has two entry points during development. The difference is not "whether it is SSR" but who receives the browser request and owns the response:

Vona integrated SSR:   Browser → Vona(7102) → SSR Site matching → Zova build artifacts → browser hydration
Zova standalone SSR:   Browser → Zova dev server(9000) → frontend SSR (APIs still point to Vona)

npm run dev starts Vona integrated SSR: Web entry http://localhost:7102/, Admin entry http://localhost:7102/admin/
npm run dev:zova:web / npm run dev:zova:admin start Zova standalone SSR (port 9000 by default) for fast hot-reload iteration on pages, routes, and hydration
Opening port 9000 directly cannot replace integrated acceptance at 7102: it bypasses Vona's SSR Site dispatch and the built-artifact handoff
The release/acceptance path is: build the SSR and rest artifacts → sync them into Vona with npm run deps:vona → run full acceptance from the Vona entry

Note that "standalone" only means you can open the Zova development server directly; it does not mean it is an independently deployable SSR application. Adding a mountable site requires a matching flavor, a paired set of SSR/rest artifacts, and an @SsrSite registration on the Vona side.

Channel 2: The Bidirectional Contract Loop (the Type and Codegen Channel)

Type information flows in both directions, and each side has its own source of truth.

Forward chain (backend → frontend)

Controller / DTO / Zod (contract truth)
        │  Vona emits OpenAPI
        ▼
Zova generates SDK ($api) and schema helpers ($apiSchema)
        │  generated code must never be hand-edited
        ▼
Frontend adds only thin semantic wrappers, reusing the same resource owner

When changing a backend contract, change the backend truth first, then regenerate the frontend consumers — never hand-patch generated files.

Reverse chain (frontend → backend)

Zova's route, component, and icon metadata is the truth; after building, it flows back into Vona's tooling and type hints. The correct order is to build Zova first, then sync dependencies:

npm run build:zova:admin   # Admin-side changes
npm run build:zova:web     # also required when the Web flavor is affected — SSR bundle and rest must move as a pair
npm run deps:vona          # then sync the .zova-rest artifacts into Vona

The contract loop also has two typical exception branches, handled in entirely different ways:

Consumer drift: fixed by regenerating; do not hand-edit generated output
Local dependency drift: the .zova-rest artifacts already contain the expected changes, but Vona-side types remain stale — delete vona/node_modules and reinstall dependencies instead of continuing to debug or hand-patching dependency links

The repository itself also wires a contract-loop-gate into git hooks, which automatically checks whether this chain has been broken at commit time. That means the "bidirectional contract" is not a documentation slogan — it is a workflow enforced by engineering guardrails.

Part 4. The Shared Organizational Skeleton: Suite / Module / Package

Both engines organize business capability by the same structural boundaries: suite → module → package. This is an architectural boundary, not just directory placement. Frontend and backend suites of the same name correspond one to one:

Suite	Backend	Frontend	What it demonstrates
a-commerce	`vona/src/suite/a-commerce`	`zova/src/suite/a-commerce`	A complete e-commerce Admin, Web site, personal center, and payment flows
a-training	`vona/src/suite/a-training`	`zova/src/suite/a-training`	Master–detail forms, nested detail records, image and file uploads
a-demo / a-home	Mirrored	Mirrored	Demo and home pages

Business consumers are also explicitly split into two kinds:

Admin Resource: back-office management, reusing the generic Resource owner and resource pages
Web self-service: the self-service Web frontend, with its own state, pages, and server-side scope

When one persisted resource serves both kinds of consumers, the domain and persistence boundary stays single, while the API/DTO contracts, server-side scope, frontend state ownership, and page architecture are separated.

Part 5. One Diagram to Remember It All

Zova (frontend truth)                     Vona (backend truth)
──────────────────────                    ──────────────────────
Page/Component/Controller                 Controller → Service → Model → Entity
sys/app/ctx containers + Bean             app/ctx containers + Bean (scene-based)
ModelResource + TanStack Query            DTO + Zod validation + OpenAPI output
flavors: Basic Web/Admin, Commerce        SSR Site registration, multi-tenant instances
route/component/icon metadata  ─reverse──▶  consumed via deps:vona
$api / $apiSchema generated SDK ◀─forward──  OpenAPI contracts
        │                                         │
        └───────── build artifacts: ssr-* / rest-* ┘
               Vona integrated SSR (7102) faces the world

Once you understand this architecture, many Cabloy working conventions fall into place naturally:

Why regenerating the frontend SDK — not hand-editing $api — is the response to backend API changes
Why frontend route changes must be followed by a Zova build and then deps:vona
Why debugging fullstack issues requires distinguishing 9000 (frontend iteration) from 7102 (integrated truth)
Why schema-driven forms (ZForm/ZTable) never need field definitions duplicated on the frontend
Why business code is organized along suite/module boundaries instead of technical-type directories

Vona and Zova are each complete, independent, independently evolvable frameworks. Cabloy's value is precisely in assembling them — through the SSR runtime channel and the bidirectional contract loop — into one complete fullstack system built for AI Spec-Driven Development.

AI Coding in Action: One Prompt for CRUD, SSR & Multitasking

Uncle Pushui — Sat, 10 Oct 2026 03:09:23 +0000

If you ask AI to build a book management feature, what do you expect to get back?

A set of APIs and a few source files—or an Admin page you can open in a browser and actually use?

Let's try it in CabloyJS. We'll give Codex one prompt to develop and test a Book CRUD module. Then we'll start the servers, open the Admin interface, create a book, and keep edit, detail, and create tasks open at the same time.

You'll see more than how AI writes code. You'll get a feel for the finished feature: what happens when you refresh the list, how you switch between tasks, and whether an unsubmitted form keeps its input.

1. Start with One Prompt

Open Codex in an existing, configured CabloyJS project and enter:

Create a standalone demo-book module to implement CRUD operations for books.

This gives Codex two clear goals:

Create a standalone demo-book module.
Implement CRUD—create, read, update, and delete—for books.

We're using a Cabloy Basic project, with Vona on the backend and Zova on the frontend. The project already has a module structure, development commands, and an Admin interface. Our job is to add a business feature on top of that foundation.

The prompt doesn't need to specify every controller, data model, form component, or page layout. Codex first reads the project conventions, examines the existing structure and tools, and follows the project's development workflow.

What Does AI Actually Do?

For this feature, Codex's work follows four steps:

Understand the project → Run the CRUD generator → Refine fields and integration → Run tests and checks

It examines the project and generator commands, then uses Vona's CRUD generator to create the module. Next, it refines the book fields, validation, menu integration, and supporting code so the resource becomes available in the existing Admin interface.

The resulting book form has three fields:

Field	Purpose	Requirement
Title	Book title	Required
Author	Book author	Required
Description	Book description	Optional

One useful part of the development experience is immediately apparent: once the business resource is defined, the list, detail view, and forms can reuse CabloyJS's existing schema-driven CRUD pages. There is no need to build a new management interface from scratch.

AI adds the business module; the framework supplies the reusable capabilities. Together, they let you focus on the fields and operations a book needs rather than rebuilding page structures and basic interactions for every resource.

2. Development Includes Tests

After creating the module, Codex continues with tests, TypeScript checks, linting, and formatting checks.

This development task took 13 minutes and 57 seconds. Codex's completion summary reports:

All five Book module tests passed.
The backend test suite had 269 passed, ten skipped, and zero failed.
TypeScript, lint, and formatting checks passed.

The implemented capabilities include create, paginated listing, detail viewing, update, delete, and transactional bulk deletion.

At this point, a single business request has led to a module implementation and automated checks. Now let's start the servers and see what the feature feels like in the interface.

3. Two Commands to Open Book Management

In the project root, open the first terminal and start the backend development server:

npm run dev

Open a second terminal and start the Admin frontend development server:

npm run dev:zova:admin

Once the servers are ready, open the Admin interface and select Book from the menu on the left.

The book list is already part of the existing Admin layout: the management menu on the left, search filters and records in the main area, and page navigation above. Creating, searching, and working with records all happen in the same interface.

That's the first tangible result of adding the module: you haven't just gained source files. You have a new business feature you can open and use.

Refresh the List and Experience SSR

The book list supports SSR, or server-side rendering.

Refresh the browser while on the list page. The layout shows no obvious flicker during the refresh and retains the familiar Admin structure.

For someone using the application, the first impression is not the implementation details of SSR—it's how the page appears when opened or refreshed. For the developer, the Book module is now part of CabloyJS's SSR-enabled Admin interface, without having to build an SSR mechanism specifically for this CRUD feature.

4. Create a Book: From Form to List

Click Create to open the book form and enter:

Title: Book One
Author: Kevin

Description is optional, so leave it empty for now and click Submit.

Back in the list, you'll see Book One with Kevin as its author.

It's a simple operation, but it brings the frontend and backend together: open a form, enter the fields, submit the data, and see the result in the list. The module AI just created can now carry out a real business operation.

Next, instead of finishing with this book, let's keep working with it as an open task.

5. Keep Three Tasks Open Without Losing Input

In an Admin application, it's common to start editing a record and then need to check its details. Or perhaps you've begun filling out a new form but need to deal with something else before submitting it.

If leaving the page means reopening it—or entering everything again—your work gets interrupted.

CabloyJS's Admin interface provides a second row of task tabs. Let's use Book One and Book Two to see how they work.

Open Book One for Editing

From the list, open Book One's edit page. Its title and author are already filled in.

Now return to the book list. Look at the tabs above: Book One's edit task is still open. Returning to the list doesn't mean you have to close the edit page.

Open Book One's Details as Another Task

Next, open Book One's detail page from the list.

You now have two tasks for the same book: one for editing and one for viewing details. You can choose whichever you need without going back to the list and finding the record each time.

Start Book Two, but Don't Submit It

Return to the list, click Create, and enter a second book:

Title: Book Two
Author: Tom

Don't submit this time. Leave the form as a draft.

The task tabs now contain three open tasks:

Task	Content
Edit	Book One's edit form
Detail	Book One's detail view
Create	Book Two's unsubmitted form

Switch Back and Continue Where You Left Off

Switch to Book One's edit task, then its detail task, and finally back to Book Two's create task.

The title is still Book Two, and the author is still Tom. The edit and detail tasks also remain open, so you can continue switching among all three.

Book Two hasn't been submitted, but switching tasks hasn't lost the input.

That makes the task tabs more than navigation shortcuts. Each task keeps its current working context. You can check another piece of information and then return to finish the form, without submitting early just to leave the page or retyping everything when you come back.

The experience feels closer to multitasking in a desktop application: several pieces of work can stay open together, rather than forcing you to finish one before moving to the next.

6. A Practical Introduction to Developing with CabloyJS

Looking back, we started with just one business request:

Create a standalone demo-book module to implement CRUD operations for books.

AI developed and checked the module. After starting the servers, we could open the book list, create a record, and use the SSR-enabled pages and task tabs.

This walkthrough gives you a direct feel for several aspects of CabloyJS:

Modular development: the new Book feature is organized as a standalone demo-book module.
AI working with existing tools: AI examines the project and uses its generators and commands instead of introducing a separate implementation approach.
Schema-driven management pages: business fields become part of the list, detail view, and forms, with reusable page capabilities.
SSR page experience: the new resource joins the existing SSR-enabled Admin interface.
Multitasking: edit, detail, and create tasks stay open together, preserving form input when you switch.

CRUD is the business feature at the center of the walkthrough. SSR and multitasking show what it's like to use that feature inside an actual Admin application.

These aren't infrastructure capabilities AI has rewritten from scratch. They are capabilities CabloyJS already provides. AI develops the business feature within the framework, and the new feature benefits from the framework's existing pages and interactions.

Give AI a Request, Get a Feature You Can Use

If you'd like to explore CabloyJS, a small feature like this is a good place to start.

Give AI a clear request. See how it creates the module, refines the fields, and runs checks. Then open the browser, create a record yourself, refresh the list, and keep a few tasks open at once.

Moving from “What code did it generate?” to “What does this feature feel like to use?” turns modules, schemas, and SSR from abstract terms into a concrete development and application experience.

That's the point of hands-on AI coding: turn a request into a feature you can operate, and make the framework's capabilities something you can see and use.

Vona Integrated SSR vs Zova Standalone SSR

Uncle Pushui — Mon, 28 Sep 2026 02:55:47 +0000

When you first run Cabloy Basic, you will usually encounter two kinds of commands:

# Start the complete Cabloy service
npm run dev

# Start the Zova frontend SSR development service
npm run dev:zova:web
# or
npm run dev:zova:admin

Both can open an SSR page, but they serve different goals:

npm run dev normally serves the project at http://localhost:7102.
npm run dev:zova:* normally serves the Web or Admin page at http://localhost:9000.

A newcomer does not need every SSR detail at the start. Remember this first: use 9000 to iterate on the frontend quickly; use 7102 to confirm that the project runs through its complete production-style path.

Two ports, two working rhythms

7102: Vona integrated SSR

When you visit 7102, the request first reaches the Vona backend service. Vona identifies the SSR Site for the URL, loads the corresponding Zova SSR build output, and returns the final HTML response to the browser.

So 7102 represents the complete runtime path:

Browser
  → Vona backend service
  → Zova SSR build output renders the page
  → browser takes over the page

This matches the core production-style model: Vona carries the HTTP request and SSR integration, while Zova renders the frontend page.

Use 7102 when you need to confirm that:

the Web or Admin path is correct;
Vona can find and load the right frontend build output;
backend APIs, SSR pages, and the final HTTP response work together;
the project runs correctly through its complete path before delivery.

9000: Zova standalone SSR

When you visit 9000, the browser enters the Zova frontend development service directly. It still server-renders the page, but its purpose is faster frontend work: edits to user code can hot-reload, and page, route, first render, and hydration issues are easier to inspect quickly.

Browser
  → Zova frontend development service
  → SSR-rendered page + user-code hot reload

Use 9000 first while you are:

changing page layout or interactions;
editing components, routes, or frontend state;
checking the SSR first paint and the behavior after browser hydration;
shortening the edit-to-feedback loop with hot reload.

7102 and 9000 are the default Cabloy Basic development ports. Environment configuration can change the numbers, but not the responsibilities of the two entry points.

How a Cabloy project works as a fullstack system

Cabloy’s fullstack model is built around two simple principles.

1. Frontend build output participates directly in backend SSR

Zova owns frontend application source: pages, components, routes, and frontend state.
Zova’s frontend bundle and SSR-related output are loaded and used by the Vona SSR flow.
Server rendering and browser hydration therefore stay on one coordinated delivery path.

A complete page visit can be understood as:

Browser request
  → Vona receives the request and finds the matching site
  → Zova SSR build output renders the page and prepares initial state
  → Vona returns HTML
  → the browser hydrates and continues the page

That is the basic meaning of integrated SSR: frontend SSR is not an isolated page prerender. It is one fullstack request completed together by Vona and Zova.

2. Type information flows in both directions

Cabloy uses a frontend-backend separation architecture. It does not simply place one shared types.ts file between the two sides. Instead, bidirectional contracts enable frontend and backend types to be generated and shared automatically.

Backend → Frontend: Vona emits Swagger / OpenAPI contracts; Zova uses them to generate SDKs, types, and schema helpers.
Frontend → Backend: Zova generates structural metadata and typing surfaces for routes, components, icons, renderers, and related resources; Vona tooling and type hints can consume them.

The next section uses one small example to make both directions concrete. For now, the key idea is enough: Vona owns backend entry and SSR integration, Zova owns the frontend application and rendering, and build output plus contracts let them collaborate.

Why do types need to synchronize in both directions?

One common fullstack problem is that the backend and frontend maintain two definitions that look alike: the backend changes a field, but the frontend forgets to update it; the frontend adds a renderable resource, but the backend cannot safely reference it.

Vona → Zova: when a backend API changes

When a Controller, DTO, validation rule, or entity field changes, Vona owns the business fact. Vona expresses it as Swagger / OpenAPI, then Zova generates the matching API, types, and schema helpers:

Vona API / DTO / validation
  → Swagger / OpenAPI
  → generated Zova API and types
  → frontend Model / page consumes them

The existing summary/:id endpoint in training-student shows the whole process. It returns a student summary, including a level title, summary text, and description length.

1. Define the endpoint and response DTO on the backend

The Vona Controller declares the URL, parameter, and response DTO:

// vona/.../training-student/src/controller/student.ts
@Web.get('summary/:id', { summary: $locale('StudentSummary') })
@Api.body(v.optional(), v.object(DtoStudentSummary))
@Core.serializer()
async summary(
  @Arg.param('id', v.tableIdentity()) id: TableIdentity,
): Promise<DtoStudentSummary | undefined> {
  return await this.scope.service.student.summary(id);
}

The response DTO declares the actual fields. If the backend adds summaryText, this DTO is the contract source:

// vona/.../training-student/src/dto/studentSummary.tsx
@Dto<IDtoOptionsStudentSummary>()
export class DtoStudentSummary extends $Dto.get(() => ModelStudent, {
  columns: ['id', 'name', 'mobile', 'level'],
}) {
  @Api.field(v.title($locale('LevelTitle')))
  levelTitle: string;

  @Api.field(v.title($locale('Summary')))
  summaryText: string;
}

2. Regenerate the Zova API and types

First make sure Vona’s Swagger output contains the new field, then run:

npm run zova :openapi:generate training-student

This refreshes the generated Zova API method, OpenAPI response type, and schema facade. Do not edit generated files directly; the next generation will overwrite them.

3. Consume the generated API in the frontend

After generation, the Zova API surface provides trainingStudent.summary(...) with its generated response type. A frontend Model can wrap it with a thin semantic method:

// zova/.../training-student/src/model/student.ts
summary(id: TableIdentity) {
  return this.$$modelResource.queryItem({
    id,
    action: 'summary',
    queryFn: async () => {
      const res = await this.scope.api.trainingStudent.summary({
        params: { id },
      });
      return res ?? null;
    },
  });
}

A page or table action only needs to call student.summary(id) to receive fields such as summaryText and levelTitle. The frontend does not need to handwrite a second StudentSummary interface: when the backend DTO changes, regenerate the consumer and keep using the updated type.

The complete flow is: Vona DTO → Swagger / OpenAPI → openapi:generate → Zova API → Model / page.

Zova → Vona: when a frontend resource changes

Some facts belong to the frontend. A custom form field, table cell, route, or icon is implemented by Zova. Vona needs a stable resource identity to reference it, but it does not execute the frontend component source itself.

The current training-student module provides a compact example: Vona defines what a Student Level means and which values are allowed; Zova implements the matching level selector and level badge.

Vona: what Level means, its allowed values, and the renderer key to use
  → Zova: implements the form field and table cell behind that key
  → build and synchronize the handoff
  → Vona can safely reference the refreshed frontend resource

When a Zova resource like this changes, use the complete build and synchronization flow for the relevant flavor. For Admin, for example:

npm run build:zova:admin
npm run deps:vona

The role of these two steps becomes concrete in the training-student level renderer. Zova first declares a stable renderer key and implements the actual form control:

// zova/.../training-student/src/component/formFieldLevel/controller.tsx

declare module 'zova-module-a-openapi' {
  export interface IResourceFormFieldRecord {
    'training-student:formFieldLevel'?: IResourceFormFieldLevelOptions;
  }
}

@Controller()
export class ControllerFormFieldLevel extends BeanControllerBase {
  protected render() {
    const { items = [], itemValue = 'value', itemTitle = 'title' } = this.$props.options ?? {};
    return (
      <div>
        {items.map(item => (
          <button key={String(item[itemValue])} type="button">
            {item[itemTitle]}
          </button>
        ))}
      </div>
    );
  }
}

npm run build:zova:admin produces the Admin SSR and REST handoff artifacts. npm run deps:vona then synchronizes that handoff to Vona. After synchronization, Vona DTO or field metadata can reference the key and pass typed options:

// vona/.../training-student/src/entity/student.tsx
@Api.field(
  v.title($locale('Level')),
  ZovaRender.field('training-student:formFieldLevel', {
    items: studentLevelItems,
    placeholder: $locale('Level'),
  }),
  ZovaRender.cell('training-student:level', { items: studentLevelItems }),
  z.union([z.literal(1), z.literal(2), z.literal(3)]),
)
level: number;

On the backend, DtoStudentSelectResItem inherits from ModelStudent and uses DTO field metadata to define how the list and form should be presented. After receiving the DTO, the frontend dynamically renders it from the renderer key and options: Zova still executes the actual JSX component, while the DTO only describes which renderer to use and which arguments to pass. It does not import or execute the frontend component source directly.

You do not need to memorize every command. The important direction is: the backend owns APIs and business rules; the frontend owns pages and renderers. When something changes, pass the contract from the side that owns the fact to the side that consumes it.

Where to explore next

If you are new to Cabloy, this is a useful learning sequence:

Change a page through 9000 to experience Zova development and hot reload.
Visit the same page through 7102 to see how Vona carries the complete SSR request.
Change an API field and inspect how generated frontend types change from OpenAPI.
Add a frontend renderer and learn why it needs a build and synchronization handoff to Vona.

As a project grows, this division makes problems easier to locate: is it a page-development issue, a Vona integration issue, or a contract-synchronization issue? You no longer have to describe every mismatch as simply “frontend and backend are out of sync.”

CabloyJS AI Spec-Driven Development Automatically Generates Gantt and Burndown Charts

Uncle Pushui — Fri, 11 Sep 2026 07:43:42 +0000

The easiest way to start AI coding is to describe a page or an API in a chat window. But once a project has multiple modules, multiple audiences, and an evolving frontend-backend contract, the genuinely difficult questions become: where does this change belong? Which boundaries have already been confirmed? How can we prove that it is actually complete?

CabloyJS includes two complementary Claude Code Skills that divide the work into two phases: first establish specification authority inside the repository, then execute a bounded delivery increment. This article introduces the two Skills, explains the Spec files they produce and consume, and uses real charts from the built-in a-commerce suite to show the result.

Meet the two Skills first

The two Skills are invoked as follows:

cabloy-spec-generation: creates or maintains the suite planning records under repo-specs/<suite>/, establishing traceability among product, technical, delivery, and acceptance concerns.
cabloy-spec-execution: works from an existing specification to execute one explicit WBS-* item—or a finite, approved phase with a closed boundary—and records the actual verification results.

The following table summarizes the difference:

Dimension	`cabloy-spec-generation`	`cabloy-spec-execution`
Problem addressed	What should be built, and how should boundaries and acceptance be recorded?	How should one approved item be implemented and proven complete?
Input	A new suite description or a request to maintain an existing specification	An explicit `WBS-*` item, or a finite and approved phase
Primary outputs	PRD, SRS, PDP/WBS, ATP, ADRs, derived status, and charts	Source changes, test results, Evidence, derived progress, and charts
Confirmation gate	Confirms identity, scope, topology, site strategy, and more before planning records are written	Confirms the execution dossier, dependencies, scope, commands, and evidence requirements before implementation
What it does not do	Does not write business source code or treat planning as implementation	Does not invent requirements, replace specification generation, or automatically expand into adjacent tasks

1. Establish a specification baseline with generation

In Claude Code, begin with a business description:

/cabloy-spec-generation Plan an equipment-maintenance suite for field technicians and operations managers: include equipment records, work orders, asset history, role-based access control, and an Admin dashboard.

The Skill first performs read-only discovery and asks for missing inputs. Its typical steps are:

inspect the repository root, package.json, CLAUDE.md, and the edition marker;
distinguish a new suite from an extension of an existing suite, and check whether repo-specs/<suite>/ already exists;
independently evaluate whether Web and Admin should reuse an existing site or use a dedicated site;
collect product goals, roles, scope, module topology, tenancy and authorization, states, transactions, verification, and release constraints;
show a generation confirmation gate before writing planning records;
generate files in authority order, run exact-ID traceability checks, and produce two derived charts.

2. Execute a bounded increment with execution

Once the specification is ready and a task’s dependencies are satisfied, invoke execution:

/cabloy-spec-execution WBS-40-03

WBS-40-03 is only an example. A real project should use an ID that actually exists in the target suite. The AI then follows this process:

read README.md, the PRD, SRS, applicable ADRs, the complete WBS, ATP/test plan, progress, Evidence, and derived charts;
check the edition, current revision, workspace state, dependencies, blockers, unresolved TODOs, and whether previous evidence is still valid;
prepare an execution dossier listing the objective, scope, exclusions, authority IDs, source ownership, specialist-Skill routing, verification commands, and evidence format;
obtain explicit confirmation before routing into backend, frontend, or Contract Loop specialist workflows;
run the narrowest meaningful check first, followed by the ATP-required verification;
save Evidence containing the revision, environment, steps, results, and locations of sanitized artifacts;
update derived progress.md, regenerate and check the charts, and leave one unambiguous next action.

/cabloy-spec-execution Execute the next task in the equipment-maintenance suite

If the next incremental WBS ID is unknown, ask the AI to first read the suite’s progress.md and combine it with the WBS, ATP, and existing Evidence to list executable WBS-* IDs whose dependencies are satisfied. The user can then confirm the specific item to execute next.

What generation produces: a connected set of Spec files

For a long-lived business suite, the default core output of cabloy-spec-generation is located at:

repo-specs/<suite>/
├── README.md
├── prd.md
├── srs.md
├── pdp-wbs.md
├── test-plan.md
├── progress.md
├── implementation-gantt.svg
├── implementation-burndown.svg
└── decisions/
    └── 0001-<suite-boundary-slug>.md

This is not simply one large document split into several files. It is a model of separated authority: each record owns one kind of fact, while the others refer to it through stable IDs and links.

File	Facts it owns	What it should not replace
`README.md`	Index, reading order, suite baseline, topology summary, and authority map	Detailed PRD, SRS, or WBS content
`prd.md`	Product goals, roles, scope, journeys, business rules, product requirements, and product acceptance	Table names, DTO syntax, routes, or test commands
`srs.md`	Technical contracts; data and capability ownership; tenancy; identity; authorization; states; transactions; concurrency; APIs/DTOs; SSR; and non-functional boundaries	API authority or authorization determined by a UI layout
`pdp-wbs.md`	Delivery phases, WBS tasks, dependencies, completion checks, and delivery traceability	Upstream product requirements or technical contracts
`test-plan.md`	ATP acceptance scenarios, test levels, fixtures, verification procedures, Evidence format, and release gates	Planned commands presented as results that have already passed
`progress.md`	WBS state, blockers, Evidence pointers, decisions, and the next proof	Requirements, contracts, or acceptance rules
`decisions/*.md`	Long-lived scope, architecture, security, ownership, or integration decisions	A duplicate SRS or status log
`implementation-gantt.svg`	A WBS-derived view of phases, task order, dependencies, and status	Planning authority, date commitments, or duration commitments
`implementation-burndown.svg`	A scope-and-status-derived count of remaining items	A velocity trend or forecast when no historical snapshots exist

From business intent to evidence: how the files connect

The core traceability chain is:

PRD requirement
      ↓
SRS contract
      ↓
PDP/WBS task
      ↓
ATP scenario
      ↓
observed Evidence

It can also be written more compactly:

PRD → SRS → WBS → ATP → Evidence

For example, a product requirement that “an authorized operator can view orders in the current tenant” must be made concrete in the SRS as identity, tenancy, authorization, data ownership, and API contracts. The WBS then defines the implementation boundary and dependencies; the ATP provides executable happy-path, unauthorized, and cross-tenant scenarios; finally, the actual runtime observations are saved as sanitized evidence.

When a task is executed, the document-state update order is:

Upstream authority changes
  → traceability matrix
  → WBS dependencies and completion checks
  → ATP procedures and expected Evidence
  → progress / Evidence
  → two derived charts

progress.md and both SVGs are downstream derived outputs. They help people and AI understand the current state quickly.

How to read the two charts

The charts are automatically generated by built-in scripts from pdp-wbs.md, test-plan.md, and progress.md.

Gantt: inspect delivery order, not a calendar schedule

The Gantt chart reads the formal phases, WBS tasks, dependencies, and progress statuses. It is useful for answering: what delivery packages exist? What is their approximate order? Which tasks depend on preceding phases?

The current chart for the built-in a-commerce suite contains 23 formal WBS tasks, all shown as 23/23 verified.

Burndown: inspect scope counts, not velocity forecasts

In the current a-commerce snapshot, the Burndown chart shows 23 active WBS items, 23 verified, 0 remaining, and 0 deferred.

When this approach is worthwhile

This approach is best suited to enterprise systems that evolve over time, span modules, involve multiple collaborators, and include both Vona backend and Zova Admin/Web/SSR work—especially where tenancy, authorization, transactions, concurrency, auditability, or external integrations are important.

For a one-off page, a simple website, or a very small utility, a lightweight prompt-to-code workflow may be more economical.

Start with a small increment

Choose one clearly bounded capability rather than trying to plan an entire system at once:

Use generation to plan the requirement.
- Record goals, scope, and exclusions.
- Confirm technical contracts, ownership, dependencies, and ATP.
Use execution to deliver one WBS ID.
- Run applicable verification and save sanitized Evidence.
- Update progress and the derived charts.
Proceed to the next increment.

Create a Cabloy project from the public scaffolding:

npm create cabloy
npm run dev
npm run dev:zova:admin
npm run dev:zova:web

Conclusion

AI Spec-Driven Development in CabloyJS is not another way of saying “prompts become code.” It is a more concrete delivery path:

Business intent → specification authority → bounded WBS → acceptance procedure → observed Evidence

cabloy-spec-generation organizes intent into a traceable planning chain. cabloy-spec-execution advances one increment within confirmed boundaries. Together, they reduce the AI’s need to guess about business scope, technical ownership, and the definition of done.

Beyond IoC: CabloyJS as a Full-Stack Resource Addressing System

Uncle Pushui — Sun, 16 Aug 2026 06:44:07 +0000

IoC answers “how a runtime collaborator is obtained.” Full-stack resource addressing answers “which business capability this is, where it enters the system, how each layer locates it, and how it retains one business meaning.”

In a new application, tracing a feature is usually straightforward: find a component, follow an import to its request function, then follow that function to a backend Controller. As a system grows into multiple business domains and modules—with admin resource pages, Web self-service pages, SSR, OpenAPI contracts, and frontend rendering resources—the harder question is no longer simply whether a Service can be injected.

Consider a Student capability. Which business domain owns it? Which module implements it? How does the backend expose it? How does a menu enter it? How does a generic Resource page know what it is displaying? And how do frontend requests, Schemas, permissions, forms, caches, and custom rendering continue to refer to the same business meaning?

IoC matters to all of those questions: it provides object ownership, lifecycle, scope, and dependency resolution. But Cabloy becomes more interesting when IoC is not viewed in isolation. Together with suites, modules, Bean identities, business Resources, OpenAPI, route parameters, selector-backed Models, and rendering metadata, it forms a set of constrained, mappable addressing coordinates.

This is not one universal string that travels through every layer, nor is it zero-configuration magic. Vona and Zova have independent runtime containers. Backend and frontend cooperate through contracts, metadata, generated artifacts, and build outputs. This article uses “full-stack resource addressing system” as a lens for understanding Cabloy architecture—not as the name of an official API that replaces existing terminology.

Separate IoC from addressing first

IoC asks a focused question: who creates, owns, disposes of, and supplies a runtime capability?

In Zova, a Bean may be held in the sys, app, or ctx container scope. Code can use @Use for injection or use containers and Scope for dependency lookup. This single model keeps state sharing, lifecycle behavior, and cross-module collaboration from drifting into unrelated mechanisms. IoC and Beans explains that model in detail.

Addressing asks a broader question: when one layer needs something, which identity expresses the target, who resolves it, and what kind of resource results?

The current repository’s Student sample includes related but non-interchangeable values:

Layer	Example	Question answered
Business domain / suite	`a-training`	Which business domain owns this family of capabilities?
Feature module	`training-student`	Which capability boundary owns Student?
Bean full name	`training-student.service.student`	Which runtime Service should the container resolve?
Business Resource identity (onion name)	`training-student:student`	Which module-qualified business Resource is under discussion?
Route entry	`:resource/:id/:formScene?`	Which page scene is being entered?
HTTP API path	`/api/training/student`	Where should the request be sent?
Resource Model selector	`training-student:student`	Which Resource is the generic owner maintaining state for?
Render resource	`training-student:formFieldLevel`	Which frontend scene capability renders the field?

Think of these as different coordinate systems for the same place: an administrative region, street, building number, navigation entry, delivery address, and room number are related, but they solve different problems. Calling them all an “ID” hides the boundaries that matter.

Let us follow training-student:student through the system.

Coordinate one: suites and modules answer “who owns it?”

Cabloy defines a suite as a business-domain composition boundary and a module as a feature implementation boundary within that domain. In other words:

a suite answers, “which business domain does this group of capabilities belong to?”
a module answers, “within that domain, which capability owns this implementation?”

In the Student sample, the domain is a-training and the module is training-student. Vona and Zova both have corresponding suite/module structures, so backend Controllers, Services, Models, Entities, and DTOs can evolve along the same business boundary as frontend pages, APIs, Models, and metadata. What is shared first is a business coordinate, not a block of memory shared by Node.js and the browser.

That is why a module name matters more than a directory position. Directories can be reorganized and implementation files can move, while a stable module namespace can continue to carry the logical identity of Services, Models, APIs, locales, errors, Resources, and frontend render resources. See Suites and Modules for the boundary between suites and modules.

Coordinate two: Bean full names and the Scope facade

At runtime, one module still needs to locate different families of capabilities. Most scene-based Vona Beans use this full identity:

{moduleName}.{sceneName}.{beanName}

For example:

training-student.controller.student
training-student.service.student
training-student.model.student

Here, sceneName distinguishes capability families such as controllers, services, and models. Two related facts must therefore remain separate:

training-student:student is a module-qualified onion name;
training-student.service.student is a Bean full name whose scene has already been specified.

An onion name is not merely a global Bean key with some characters omitted. A consumer must identify a scene such as service, model, or controller before the framework can resolve the corresponding full Bean name.

Business code usually does not need to write full names everywhere. Scope supplies a typed facade over module resources:

// Business orchestration in the current module
const students = await this.scope.model.student.select();

// A known cross-module target
const sku = await this.$scope.commerceCatalog.model.sku.getById(id);

Scope does not create another identity system. It raises a container-level full name into an everyday way to navigate a module’s resource catalog. Backend Scope can organize services, models, entities, configuration, locales, and errors; frontend Scope commonly exposes facades for configuration, constants, locales, errors, APIs, and API Schemas. Both Vona Backend Foundation and Zova Module Scope describe that division of responsibility.

There is an important limit: Scope lookup can resolve only resources from modules that have already been composed into the active application. A correct string does not install, load, or order an absent module. Module dependencies, suite/application composition, and runtime lookup are related but different concerns. The first establishes availability, ordering, and versioning; only then can the latter retrieve a resource from the composed modules.

Coordinate three: `@Resource()` connects business identity to an HTTP contract

The Student backend Controller uses @Controller('student') and @Resource(). This is a trimmed version of the current implementation, retaining only the roles relevant here:

@Controller('student')
@Resource()
export class ControllerStudent extends BeanBase {
  @Web.get()
  @Api.body(DtoStudentSelectRes)
  async select(
    @Arg.filter(DtoStudentSelectReq) params: IQueryParams<ModelStudent>,
  ): Promise<DtoStudentSelectRes> {
    return await this.scope.service.student.select(params);
  }
}

This is not just a class with two decorators. It connects at least three responsibilities:

the Controller exposes an HTTP-facing action;
DTOs, Entity fields, and validation shape a machine-readable contract;
@Resource() registers the Controller’s onion identity as a business Resource.

When Vona processes the Controller decorator, it derives the onion name from the Bean full name, combines module and controller-path metadata to compute the API path, and records the resource-to-route mapping. training-student:student can therefore remain a stable business Resource identity, while the HTTP path is a transport address derived from backend route metadata.

Avoid saying:

training-student:student === /api/training/student

A more accurate relationship is:

training-student:student
  ──resolved through Resource registration and bootstrap metadata──▶
/api/training/student

The first expresses which business Resource is involved; the second expresses where the request goes. This is one reason a Resource identity is often safer than scattering HTTP strings when frontend state, permissions, Schemas, or route context need to carry business meaning.

Coordinate four: one field contract does not need to be copied into separate knowledge

The value of resource addressing is not limited to finding an endpoint. It also allows one business contract to be recognized and projected by different consumers.

A backend field can participate in:

validation;
OpenAPI generation;
form and table rendering;
serialization or desensitization.

Take mobile from the Student Entity in training-student. This is a trimmed version of the current source:

@Api.field(
  v.title($locale('Mobile')), // OpenAPI field title
  v.required(),               // validation
  v.min(11),                  // validation
  v.serializerReplace({       // response-time desensitization
    patternFrom: /^(\d{3})\d{4}(\d+)$/,
    patternTo: '$1****$2',
  }),
  ZovaRender.order(3),        // display order for generic table and field surfaces
)
mobile: string;

This declaration does not merely describe an isolated string. It is projected through DTOs and the Resource Schema: create, update, and view DTO layouts place { type: 'field', name: 'mobile' } in Student Profile; the list-row Schema inherits the field and orders it through order(3). With no specialized Renderer, the generic form uses the default Input and the generic table uses a plain-text Cell. A query response with @Core.serializer() returns 13812345678 as 138****5678, while the persisted raw value remains unchanged.

Capability	`mobile` declaration or projection	Consumer
Validation	`v.required()` and `v.min(11)`	Request/DTO validation boundary
OpenAPI generation	`@Api.field(...)`, title, and string Schema	OpenAPI and downstream SDK/Schema consumers
Form and table rendering	DTO layout’s `field: mobile` plus `ZovaRender.order(3)`	Generic Resource UI’s default Input and text Cell
Serialization / desensitization	`v.serializerReplace(...)`	Response serialization before data reaches the client

If this field needs specialized controls instead of the default Renderer, it can additionally declare ZovaRender.field('training-student:formFieldLevel', ...) and ZovaRender.cell('training-student:level', ...), as level does in the same Entity. The point is not that every property must carry all four concerns or use a custom component. The point is that these concerns can be composed around the same field contract when they apply.

That does not mean each field automatically grows a complete UI, nor that every presentation decision belongs in the backend. It means the field’s business meaning, data contract, and permitted exposure do not have to be copied into backend DTOs, frontend request types, form rules, table columns, and response post-processing—and then manually kept aligned.

In this forward contract chain, backend Controllers, DTOs, Entities, and validation rules are the source of truth. Vona generates OpenAPI; Zova then generates or consumes SDK/Schema contract material. When a backend contract changes, the recommended path is to propagate that truth forward rather than hand-edit multiple frontend copies. Backend OpenAPI to Frontend SDK and One Contract Surface, Four Uses describe the boundary of that chain.

Coordinate five: routes choose a UI scene; Resource identities choose business context

The generic Resource page makes clear why a page address and a business Resource identity need to remain separate.

rest-resource defines generic routes with dynamic parameters:

export const routes: IModuleRoute[] = [
  { name: 'resource', path: ':resource', component: ZPageResource },
  { name: 'entryCreate', path: ':resource/create', component: ZPageEntryCreate },
  { name: 'entry', path: ':resource/:id/:formScene?', component: ZPageEntry },
];

Dynamic-parameter routes explicitly declare name, which establishes a type contract for page parameters. The route answers whether the active scene is a resource list, a create form, or a form scene for one record. The route itself does not yet know the business meaning of Student, Course, or any other Resource.

The Student SSR menu supplies that context:

@SsrMenu({
  items: {
    student: {
      link: 'presetResource',
      meta: {
        params: {
          resource: 'training-student:student',
        },
      },
    },
  },
})
export class SsrMenuStudent extends BeanBase {}

The menu does not directly render a Student page, nor does it grant authorization. It passes the resource parameter to the predefined generic Resource route:

SSR menu
  → presetResource
  → :resource route parameter
  → Page Controller’s $params.resource

The URL and route locate a page scene; $params.resource brings in business Resource context. Route names, route parameters, menu metadata, and permissions are still four separate objects that must each be verified.

Coordinate six: the Resource identity becomes a selector-backed Model owner

Once the generic page receives its parameter, it does not duplicate a page Controller for every Resource. It injects the current identity into one generic Model:

@Controller()
export class ControllerPageResource extends BeanControllerPageBase {
  @Use({ beanFullName: 'rest-resource.model.resource' })
  get $$modelResource(): ModelResource {
    return usePrepareArg(this.$params.resource, true);
  }

  protected async __init__() {
    await $QueryEnsureLoaded(() => this.$$modelResource.apiSchemasSelect.sdk);
  }
}

There are two addresses at different levels:

Generic Model Bean: rest-resource.model.resource
Current selector: training-student:student

ModelResource is registered with enableSelector: true. It is not a vague global CRUD singleton; it is a selector-backed owner. ModelResource(training-student:student) and ModelResource(other-module:other-resource) can share an implementation while owning distinct Resource contexts.

During initialization, the owner requests bootstrap information with the Resource identity and stores the resolved resourceApi. It then centralizes permissions, form providers, view/create/update/filter/row/page Schemas, and list/item query and mutation capabilities in the same owner.

The conceptual chain is:

$params.resource
  → ModelResource(resource selector)
  → bootstrap(resource)
  → resourceApi
  → schemas / permissions / forms / queries / mutations

This has two practical benefits:

a page does not need to copy the same API path, Schema-loading rule, permission lookup, and cache-invalidation policy into multiple Controllers;
a custom operation for the same Resource can be a thin semantic facade that reuses the existing Resource owner instead of creating a competing query-cache owner.

For example, a training-student frontend Model can initialize the generic owner with training-student:student, then add semantic entry points for business actions such as summary(id) or deleteForce(id) while reusing that owner’s item query, mutation, and invalidation boundary.

One more distinction matters: a call-site value such as ['select', ...] or ['item', id, action] is only a logical query key. The effective cache identity also incorporates Model Bean identity and selector. A short query key is therefore not an address that is globally unique across the application. Model Resource Internals Deep Dive and Model State Guide explain this owner/state identity layer.

Coordinate seven: Schema metadata selects concrete UI capabilities

A generic Resource Page stays deliberately thin: it loads the current Resource Schema, reads schemaRow?.rest?.blocks, and renders what the block metadata specifies. The page shell owns the question, “what is the current context?” Schema and metadata answer, “which blocks should this Resource compose in this scene?”

Where does schemaRow?.rest?.blocks come from? It is not an array assembled ad hoc by a frontend page. For the list page, the current Student sample defines it in the list-row DTO through @Dto({ blocks }):

import type { IDecoratorDtoOptions } from 'vona-module-a-web';

import { $Dto } from 'vona-module-a-orm';
import { Dto } from 'vona-module-a-web';
import { ZovaRender } from 'zova-rest-cabloy-basic-admin';

import { ModelStudent } from '../model/student.ts';

@Dto<IDecoratorDtoOptions>({
  blocks: [
    ZovaRender.block('basic-page:blockPage', {
      blocks: [
        ZovaRender.block('basic-page:blockFilter', {
          formFieldLayout: { inline: true },
          // The full sample also declares the filter form layout here.
        }),
        ZovaRender.block('basic-page:blockToolbarBulk', {
          actions: [ZovaRender.tableActionBulk('basic-table:actionCreate')],
        }),
        ZovaRender.block('basic-page:blockTable'),
        ZovaRender.block('basic-page:blockPager'),
      ],
    }),
  ],
})
export class DtoStudentSelectResItem extends $Dto.get(() => ModelStudent) {
  // List-row fields and each field’s ZovaRender.* metadata.
}

This code is deliberately abbreviated. It retains the important structure: the root basic-page:blockPage composes registered frontend block resources for filtering, bulk toolbar actions, a table, and a pager. It does not mean every DTO should own these blocks, nor that the frontend implementations of those blocks live in Vona. The DTO declares, in backend-generated contract metadata, which rendering capabilities the current Resource list page should select.

The full chain that explains blocks is:

DtoStudentSelectResItem’s @Dto({ blocks })
  → Vona merges blocks into the DTO OpenAPI metadata as rest.blocks
  → the GET select response’s data.list.items references the row DTO Schema
  → ModelResource.apiSchemasSelect.row resolves as schemaRow
  → schemaRow?.rest?.blocks
  → ControllerPageResource calls ZovaJsx.render(...) for each block

In other words, schemaRow is the current select-response row Schema, and rest.blocks is the page-composition declaration attached to that Schema. basic-page:blockTable in ZovaRender.block('basic-page:blockTable') is another module-qualified render-resource identity, resolved by an implementation registered on the Zova side. The backend selects it; the frontend executes it. Neither side directly calls the other side’s objects across processes.

Cabloy resource addressing therefore does not stop at an API. Table cells, form fields, image scenes, and Behaviors can also be selected through module-qualified, scene-aware frontend resource identities. Field metadata can, for example, refer to training-student:formFieldLevel, which a registered frontend capability resolves and renders.

This does not mean backend code executes frontend components. More precisely, backend contracts or metadata can declare which frontend rendering resource should be selected at a point; the frontend still owns the renderer implementation and runtime. Frontend-owned facts such as routes, components, icons, table cells, and form fields also have a reverse contract handoff: refresh the frontend metadata/build output first, then let Vona consume the synchronized local dependency result. Frontend Metadata Back to Backend describes that reverse chain.

The two directions are distinct:

Forward: Vona Controller / DTO / Entity
  → OpenAPI
  → Zova SDK / Schema / API consumers

Reverse: Zova route / component / renderer / metadata
  → frontend metadata or build output
  → Vona-side metadata, tooling, and type consumers

Together they support full-stack collaboration, but neither means that saving arbitrary source on one side automatically teaches the other side everything. Each chain has its own source of truth, generation step, shared handoff, and verification points.

IoC’s actual position on this map

Saying Cabloy is “more than IoC” does not diminish IoC. On the contrary, IoC is the runtime foundation that lets many of these coordinates work:

a Bean’s container scope determines lifecycle and sharing boundaries;
@Use and beanFullName support explicit, resolvable collaboration;
Scope lets everyday business code access capabilities through a module-resource facade;
parameterized injection lets generic ModelResource be reused with the current Resource selector;
lifecycle and Model query/cache mechanisms turn “a resource was found” into “this owner is responsible for its state.”

But treating this only as convenient dependency injection misses the larger collaboration structure. Business domains and modules assign capabilities an owner first; Bean/Scope gives runtime capabilities a resolution boundary; Resource and OpenAPI project a data contract for transport; route parameters bring context into a page; selectors and effective query keys isolate state to the current Resource.

IoC makes a capability obtainable. Resource addressing makes that capability retain its business meaning after it crosses modules, contracts, routes, state, and rendering.

When this is useful—and when it should not be forced

A multi-layer addressing system has a learning cost. Developers need to distinguish suites, modules, Beans, scenes, Resources, routes, selectors, Schemas, and generated artifacts. When debugging, they must begin from the correct coordinate instead of only searching for a component file.

It is usually most valuable for systems that evolve over time, have many modules or consumers, or need a clear contract loop:

Situation	Prefer	Why
One-off page-local UI state	Page/controller-local state	There is no need to introduce reusable Resource semantics.
Reusable asynchronous, persistent, or cross-page state	Model Bean	The state needs an explicit identity, lifecycle, and cache/persistence boundary.
An Admin-style entity with Schemas, permissions, forms, and list/item lifecycle	Existing `ModelResource` or a thin facade	Reuse one Resource owner and a unified invalidation policy.
A custom operation on the same Resource	A semantic facade on the existing owner	Avoid competing request, state, and cache owners.
A distinct Web self-service experience	Dedicated API/DTOs, Model, and page state	One persisted Resource does not require one frontend experience.
A cross-cutting rule around an existing rendering target	Behavior	This is a rendering-boundary concern, not business Resource ownership.

The final two rows are especially important. One business Resource can share a domain and persistence boundary between Admin and Web while using different API/DTO contracts, server-side scopes, state owners, and page architecture. Good resource addressing does not force everything into one generic CRUD page. It lets each boundary state clearly who it serves.

Trace one Resource with seven questions

To validate this mental model in an existing project, choose any registered Resource and follow it through these questions:

Which suite/module owns it?
What is its business Resource identity?
Which Controller/DTO/Entity brings it into the backend contract?
Which menu, route name, and parameters bring it into a page?
Which Bean/Model owner receives it with which selector?
After bootstrap, where do resourceApi, Schemas, permissions, and render metadata come from?
Should this change follow the forward chain, the reverse chain, or first investigate generated/local dependency drift?

The point is not to memorize more names. It is to break “why does this page work?” into a sequence of verifiable resolutions. Instead of asking only, “where is this component?”, you can ask: what is this Resource’s business identity, how is it mapped at this layer, and who owns its state and meaning?

Conclusion

Cabloy does not rule every layer with one global ID. A more accurate description is that it uses the module as an important naming anchor and connects multiple address spaces—suite/module ownership, Bean scenes, Scope, business Resources, OpenAPI, route parameters, Model selectors, query caches, and render metadata—into a traceable full-stack chain.

IoC is one runtime foundation of that chain, but not the whole chain. The engineering benefit is that a business capability can cross backend and frontend, generated artifacts, and distinct runtimes without degrading into scattered URLs, repeated imports, hand-written requests, and disconnected state. Each layer retains its own responsibility and address while still mapping to the same business meaning.

DEV Community: Uncle Pushui

Is There a CabloyJS Equivalent in the React/Next.js Ecosystem?

1. Split CabloyJS into five comparable capability layers

2. Why Next.js itself is not the counterpart

3. Path one: fullstack conventions — RedwoodJS and Blitz.js

RedwoodJS

Blitz.js

4. Path two: admin panels and metadata-driven design — Refine

5. Path three: backend IoC — NestJS + Next.js

6. How the four options compare

7. Selection advice

AI Vibe Coding in Practice, Part 2: Product Decisions and a Revised SMS Suite Plan

1. Registration: prefer explicit registration with a user-chosen userName

1. Why not generate a username automatically?

2. Recommended registration and login contracts

3. Separate phone identity from username

2. Phone-number scope: support international numbers and normalize to E.164

Routing rules

3. International vendors: Twilio and Vonage

1. Twilio: recommended for the initial release

2. Vonage: a second choice

3. Do not default to managed Verify products for this plan

4. The infrastructure must support two vendor sending models

5. Module structure: retain four core modules and extend real Providers independently

6. What enabling both Web/Admin means

7. Updated initial delivery recommendation

Sources

AI Vibe Coding in Practice: An SMS Suite Prompt and Development Plan

1. Overall recommendation

2. Suite and module structure

Dependency direction

3. cabloy-sms: defining provider / clients / scene

1. Provider: implementation of a vendor protocol

2. Client: named account configuration under a Provider

3. Scene: a business sending scenario

4. Instance isolation and send results

4. sms-captcha: reuse verification infrastructure and add SMS semantics

1. Existing capabilities and gaps

2. Recommended responsibilities

3. Recommended verification rules

4. Prevent bypasses through generic endpoints

5. sms-mock: simulate transport while preserving business validation

1. Correct runtime behavior

2. Autofill can reuse the existing response field

3. The frontend needs SMS-specific interactions

6. sms-auth: reuse authentication and establish a trusted phone identity

1. Recommended product behavior

2. Authentication flow

3. Never claim an account automatically through an old mobile field

4. Handle concurrent first registrations separately

5. Frontend login integration

7. Recommended delivery order and acceptance

8. Initial scope and decisions to confirm

Closing note

Functional vs Object-Oriented: Two Cost Curves for Frontend Architecture

1. Tearing down a false dichotomy first

2. Each model's "default answer"

3. Cost curves: pre-paid and post-paid

Functional style: architectural entropy, paid after

Object style: ceremony, paid up front

4. Three things only containerization does cleanly

1. SSR request scope

2. Interceptable call sites

3. Cross-module contracts

5. Honestly listing three costs of the object style

6. Convergence: objects own identity, functions own expression

7. Conclusion: a debate not on the same abstraction layer

Further reading

CabloyJS’s AI Moment: From a TypeScript Fullstack Framework to AI-Spec-Driven Development

Thread One: Turn "having AI write code" into "having AI deliver against a specification"

Phase One: Establish "specification authority" inside the repository

Phase Two: Let AI execute bounded increments

Thread Two: A side effect of AI-SDD — charts are automatically derived from Specs

Thread Three: Dual-Engine Architecture — why Cabloy's Vona + Zova is naturally suited for AI-SDD

Backend truth: Vona's OpenAPI contract

Frontend truth: Zova's routes, components, and metadata

Why this matters for AI

A new edition split: two MIT baselines

Cabloy Basic (reference edition)

Cabloy Start (full-featured edition)

1. Registration: prefer explicit registration with a user-chosen `userName`

Stage 1: Declaration — `@Use` Decorator Does Only Two Things

Vona's `@Use` Usage