Entity System

Entity Management Framework

A type-safe framework for managing entities with full CRUD, fine-grained permissions, drafts with workflow integration, version history, audit trails, and configurable UI layouts. Split into a widget-free core package and a Flutter UI package.

Key Capabilities

Unified Entity Configuration

EntityConfiguration brings together metadata, API, layouts, editors, actions, routing, and permissions into a single descriptor per entity type.

Permissions & Authorization

Fine-grained permission system with role-based access, group membership, route-level guards, and entity-level permission checks with caching.

Drafts, Versioning & Audit

Full draft lifecycle with 8 statuses, automatic version tracking, field-level audit trails with change comparison, and revision comments.

Configurable Layouts & Editors

Shell, dashboard, and table layouts with docked/overlay panels. Multi-part entity editors with form-based and custom editor parts.

Core Components

Component	Description
EntityConfiguration<T>	Central descriptor unifying metadata, API, layouts, editors, actions, and routing
EntityApi<T>	Abstract CRUD interface with HTTP implementation, caching, and draft/count operations
EntityEditor<T>	Editor config with form-based and custom editor parts, transformers, and draft/verification behavior
EntityLayouts<T>	Layout descriptor holding list, detail, summary, dashboard, and analytics layouts
PermissionService	Authorization facade for view/create/edit/delete/approve/reject checks with group membership
EntityRouting<T>	Route configuration with path builders, navigation mode, and route-level permissions
EntitySystemPlugin	Plugin entry point for registering entity configurations and building routes
EntityExtensionBuilder	Extension system for registering new entity types with services and formatters

Packages

vyuh_entity_systemCore logic — models, API, services, permissions, drafts, versioning (widget-free)vyuh_entity_system_uiFlutter UI — layouts, widgets, tables, editors, command palette, error display

Architecture

The entity system is split into two packages with a clear separation:

• vyuh_entity_system — Widget-free core with models, API layer, services, permissions, drafts, versioning, search, and the extension/plugin system.
• vyuh_entity_system_ui — Flutter widgets including entity shells, table layouts, editors, command palette, version/audit views, error display, and navigation.

EntityConfiguration — The Central Descriptor

Every entity type is described by a single EntityConfiguration<T> that brings together:

EntityConfiguration<T extends EntityBase>(
  metadata: EntityMetadata(...),     // Name, icon, category, visibility
  api: EntityApi<T>(...),            // CRUD operations
  layouts: EntityLayouts<T>(...),    // List, detail, summary, dashboard, analytics
  editor: EntityEditor<T>(...),      // Form parts, transformers, verification
  actions: EntityActionsConfig<T>(...), // Inline, menu, collection, header actions
  routing: EntityRouting<T>(...),    // Paths, navigation mode, permissions
  fields: [...],                     // Field definitions
  filterPresets: [...],              // Saved filter configurations
)

CRUD & API Layer

EntityApi<T> defines the standard operations with an HTTP implementation:

Method	Description
get(id)	Fetch a single entity
getMany(...)	Paginated list with query, sort, and filters
create(entity, {remarks})	Create with optional remarks
update(id, entity, {remarks})	Update with optional remarks
delete(id)	Delete an entity
count(...)	Count with query and filters
getDrafts(...)	Fetch draft entities
countDrafts(...)	Count drafts

Caching is provided through CachedMixin and CachedVersioningMixin for query-level caching.

Permissions

The permission system provides fine-grained authorization:

• PermissionService — Facade with canView(), canCreate(), canEdit(), canDelete(), canApprove(), canReject()
• Group membership — isMemberOf(), isMemberOfAny(), isMemberOfAll()
• Route-level permissions — EntityRoutePermissions with separate lists for list/create/view/edit/dashboard
• Permission caching — EntityPermissionCache for performance
• Open provider — OpenPermissionProvider for development/testing

Drafts & Versioning

Draft Lifecycle

Entities support a full draft workflow with 8 statuses:

draft → underReview → approved → effective (or rejected / cancelled)

Each draft tracks its WorkflowOperation (registration, modification, activation, deactivation), revision count, comments, and optional workflow instance ID.

Version History

VersionedEntityApi provides version-specific operations. Each EntityVersion captures the full entity state, version number, change summary, and submitter info.

Audit Trails

EntityAudit records capture the action, performer, timestamp, before/after state, and field-level change records (FieldChangeRecord) for precise diff tracking.

Layouts

The layout system uses a type hierarchy for different display contexts:

Layout Type	Purpose
ListLayout<T>	Displays multiple entities (tables, grids) with search, multi-select, batch actions
EntityLayout<T>	Displays a single entity (detail views)
AggregateLayout<T>	Dashboard and analytics views

EntityLayouts<T> groups these into list, details, summary, dashboard, and analytics.

The UI package provides concrete implementations:

• EntityShellLayout — Main container with docked or overlay panels
• TableListLayout — Configurable table with columns, sorting, filtering, column resize, row actions, and batch actions
• EntityDashboardLayout — Dashboard-style entity overview
• RelatedEntitiesLayout — Display related entities in tabs

Editors

EntityEditor<T> configures how entities are created and edited:

// Form-based editor
EntityEditor.form(
  getForm: ({entityId, isDraft}) => myFormDefinition,
  transformer: MyEntityTransformer(),
  allowDrafts: true,
  verifyCreate: ActionBehavior.yes,
  remarksUpdate: ActionBehavior.auto,
)

// Multi-part editor with tabs
EntityEditor.multiPart(
  createParts: () => [
    FormEditorPart(getForm: (...) => basicInfoForm),
    FormEditorPart(getForm: (...) => detailsForm),
    CustomEditorPart(builder: (ctx, partCtx) => MyCustomWidget()),
  ],
  transformer: MyEntityTransformer(),
)

Editor parts support lifecycle hooks: initialize, loadData, validate, validateAsync, getData, and onSaveSuccess.

Routing & Navigation

EntityRouting<T> configures entity routes with convenience builders:

EntityRouting(
  path: NavigationPathBuilder.collection(prefix: 'orders'),  // /orders, /orders/:id
  mode: EntityNavigationMode.panel,  // panel or fullPage
  permissions: EntityRoutePermissions(
    list: ['order.view'],
    create: ['order.create'],
    edit: ['order.edit'],
  ),
)

Search & Command Palette

• FuzzySearch — Client-side fuzzy matching across entity navigation items
• SearchSyncService — Background search index synchronization
• CommandPaletteDialog — Keyboard-triggered (Ctrl/Cmd+K) search UI across all registered entities
• EntitySearchContentProvider — Integration with external search plugins

Services & Real-time

• EntityServicesContainer — Service registry for accessing entity services
• EntityRealtimeService — Polling-based real-time updates with pluggable RealtimeStrategy
• EntityNameCacheService — Caches entity display names for reference resolution
• EntityLocalizationService — Localization support for entity content
• EntityDataExtractor — Field extraction utilities for computed displays