Package Map

This monorepo is organized around a small set of stable top-level areas.

Root

• package.json — shared scripts and release entrypoints
• lerna.json — package topology
• repo-docs-internal/ — edition-local maintainer notes and ADRs
• repo-agent-governance/ — authored portable agent rules, root skill bundles, adapter definitions, and deterministic tools
• CLAUDE.md, AGENTS.md, .claude/, .agents/, .codex/, .cursor/ — generated platform adapters plus platform-specific runtime integration
• repo-docs/ — unified public docs
• repo-specs/ — suite-local product, technical, delivery, ATP, progress, observed-evidence, and ADR authority

repo-specs/ is distinct from repo-docs/, which explains reusable public guidance, repo-agent-governance/, which owns portable executable workflow behavior and adapter generation, and repo-docs-internal/, which preserves supporting maintainer rationale. For the public planning workflow, see Generate a Cabloy Suite Specification.

Backend side

• vona/packages-cli/ — Vona CLI and command sets
• vona/packages-utils/ — shared utilities
• vona/packages-vona/ — framework packages
• vona/src/module/ — first-party Vona modules
• vona/src/module-vendor/ — vendor-provided modules
• vona/src/suite/ — first-party suites and their modules
• vona/src/suite-vendor/ — vendor-provided suites and their modules

A useful structural rule is:

• package is the publishable/package-metadata unit
• module is the main backend capability unit
• suite is the composition unit that groups modules into a larger architecture surface

Representative backend package metadata

Representative package metadata in the current repo shows the distinction clearly.

Module package

Example: vona/src/suite/a-training/modules/training-student/package.json

• package name: vona-module-training-student
• title: training-student
• vonaModule.dependencies records genuine module availability, dependency-first ordering, and minimum-version requirements

Suite package

Example: vona/src/suite/a-demo/package.json

• package name: vona-suite-a-demo
• title: a-demo
• dependencies declare which module packages the suite composes

Suite-contained module package

Example: vona/src/suite/a-demo/modules/demo-basic/package.json

• package name: vona-module-demo-basic
• title: demo-basic
• vonaModule.dependencies still expresses module-level dependencies even when the module lives under a suite

This matters because Vona modularization is not just folder layout. Package metadata participates in dependency declarations and architecture boundaries.

Practical modularization edge table

Surface	Main role
Package	metadata, publication, and ordinary package imports/dependencies
Suite package dependencies	compose the module packages that the suite includes
Module vonaModule.dependencies	declare genuine target-module availability, dependency-first ordering, and minimum-version requirements
Scope lookup	resolve resources from an already application-composed module without creating a module dependency edge

A practical comparison is:

• a standalone module package uses vonaModule.dependencies when its feature truly requires another module to be available, ordered first, or at a minimum compatible version
• a suite package uses ordinary package dependencies to compose the module packages it contains or depends on
• a suite-contained module still remains a module package with its own vonaModule.dependencies
• this.$scope.<module> and app.scope(...) perform runtime lookup of an already composed module; cross-module service, model, config, locale, or other resource lookup alone is not a reason to add vonaModule.dependencies

Do not add speculative module dependency declarations merely to document a scope lookup or avoid an assumed circular dependency. Lookup creates no module-order edge. Conversely, scope lookup cannot make an absent module available: declare a module dependency when the feature genuinely requires the target module's availability, ordering, or minimum version.

How this relates to backend docs

Use this package map together with:

• Suites and Modules
• Backend Essentials
• Backend Foundation
• Vona Module Dependencies
• Backend CLI
• Backend Scripts
• Backend Directory Structure

A practical split is:

• the backend essentials pages explain the architecture model
• this page grounds that model in the real monorepo layout

For the broader backend entry path, also see Backend (Vona).

Frontend side

• zova/packages-cli/ — Zova CLI and command sets
• zova/packages-utils/ — shared utilities
• zova/packages-zova/ — framework packages
• zova/src/ — modules, suites, and vendor source

For the frontend architectural meaning of modules, suites, scope-driven resources, and runtime/startup structure, see /frontend/modules-and-suites, /frontend/module-scope, /frontend/ioc-and-beans, /frontend/environment-config-guide, /frontend/app-startup-guide, and /frontend/system-startup-guide.

For the practical frontend directory tree contributors navigate, also see Frontend Directory Structure.

Sibling edition

• cabloy-start is a separate sibling repository, not a subdirectory of this monorepo.

Maintainer note for cross-repo guidance

When maintaining docs, skills, or rules that refer to Cabloy Start, keep the cross-repo guidance conceptually aligned with the system documented here.