Quick Start

Build a complete Course entity for a Learning Management System in five minutes.

The Scenario

We will create a Course entity that:

1. Has a typed model with JSON serialization, capability mixins, and @Entity/@Field annotations.
2. Connects to a REST API at /lms/courses for CRUD.
3. Gets automatic route generation (list, detail, create, edit, dashboard).
4. Appears in the application navigation menu and command palette.

1. 1

   Define the Entity Model

   EntityBase brings id and name. Layer in EntityCapability mixins (Auditable for timestamps + author, Versionable for version_number / is_active, Draftable for the draft workflow). Annotate with @Entity / @Field so the generator can emit field definitions, the API base, and a default EntityConfiguration.

   course.dart

   Run code generation: dart run build_runner build --delete-conflicting-outputs
2. 2

   Customize the Generated Configuration

   The generator emits courseConfig with everything wired (metadata, fields, default table layout, routing, the standard inline + header actions, and a basic form). Most apps keep the generated config and only override the slots they really need — for example, swapping the auto-generated table layout for a richer one with custom cell builders.

   course_config.dart
3. 3

   Register with the Feature Descriptor

   Plug the configuration into a Vyuh feature via EntityExtensionDescriptor. The plugin picks it up during initialization and generates GoRouter routes for it automatically.

   lms_feature.dart
4. 4

   Auto-Generated Routes

   Once registered, the entity system uses NavigationPathBuilder.collection(prefix: "/lms/courses") to mint /lms/courses (list), /lms/courses/new (create), /lms/courses/:id (view), /lms/courses/:id/edit (edit), and /lms/courses/dashboard. The Course entry shows up in the navigation menu under the configured menuCategory, and the command palette indexes it for global search.

   Never hardcode these URLs in app code. Use vyuh.entity?.getConfig<Course>()?.route.list() / .view(id) / .edit(id) instead.

How It All Fits Together

Key Concepts Introduced

Concept	Description
EntityBase	Base class — id and name only
Auditable / Versionable / Draftable	Capability mixins that add audit / version / draft fields
EntityReference	Lightweight reference to another entity (id + name)
@Entity / @Field	Annotations consumed by vyuh_entity_generator
$EntityBase (generated)	Per-entity superclass that mixes in the right capabilities
entityConfig (generated)	Default EntityConfiguration<T> you tweak via copyWith
EntityConfiguration<T>	Single descriptor binding metadata, API, layouts, editor, actions, routing
EntityMetadata	Display name, icon, category, visibility, priority
HttpEntityApi<T>	Default REST CRUD with EndpointBuilder and query caching
EntityRouting<T>	Path patterns, route builder, navigation mode, route-level Authorize
NavigationPathBuilder	Generates URL patterns from a prefix
StandardRouteBuilder	Builds GoRouter routes for list/detail/create/edit/dashboard
EntityTableConfig / EntityGridConfig	The two stock list layouts
EntityExtensionDescriptor	Per-feature registration of entities, services, and field formatters

Next Steps

• Design Philosophy — the principles behind the system
• Architecture — packages, layers, and the plugin lifecycle
• Entity Model — EntityBase, mixins, and references in detail
• Annotations guide — every annotation parameter