Overview

This section presents complete, production-ready examples demonstrating architectural patterns, relationship types, and UI/UX patterns you can adapt for your own applications.

Overview

All examples follow the Vyuh Framework architecture with:

• Entities extending VersionedEntity for automatic versioning and audit trails
• JsonSerializable for type-safe serialization (NO MobX codegen)
• Multi-schema design (sso, elog, lms schemas) with PostgreSQL
• EntityConfiguration pattern with metadata, API, layouts, forms, and actions
• MobX raw observables for state management

Available Examples

User Management

A complete SSO user management system with authentication and access control.

What you'll learn:

• VersionedEntity with automatic versioning and audit trails
• Multi-tab detail layouts (details, groups, versions, audit)
• Import/export collection actions
• Custom API endpoints for related data
• Immutable fields (email locked after creation)

Key patterns: SSO authentication, role-based access, custom form fields, CSV import/export

Course Management

A learning management system with courses, lessons, and enrollments.

What you'll learn:

• Enums with @JsonValue for type-safe categories
• One-to-many relationships (course → lessons)
• Many-to-many relationships (course ↔ users via enrollments)
• Rich detail layouts with custom analytics
• Duplicate action for template reuse
• Computed properties (daysUntilStart)

Key patterns: Educational platforms, enrollment tracking, course analytics, content categorization

Equipment & Areas

Equipment tracking with many-to-many area assignments and maintenance scheduling.

What you'll learn:

• Complex many-to-many relationships with junction tables
• Bidirectional layouts (equipment → areas, area → equipment)
• Mapping models with metadata (isPrimary, audit fields)
• Entity picker for multi-select assignments
• Hierarchical relationships (area → parent area)
• Maintenance and calibration tracking
• Interactive confirmation workflows

Key patterns: Asset management, resource allocation, location tracking, maintenance scheduling

Common Patterns Summary

Entity Design

@JsonSerializable(createToJson: true, fieldRename: FieldRename.snake)
class MyEntity extends VersionedEntity {
  static const schemaName = 'schema.table';

  static final typeDescriptor = TypeDescriptor(
    schemaType: schemaName,
    title: 'MyEntity',
    fromJson: MyEntity.fromJson,
  );

  // Your fields...

  MyEntity({
    required super.id,
    required super.name,
    super.versionNumber = 1,
    super.isActive = true,
    // ... other params
  }) : super(schemaType: schemaName);

  factory MyEntity.fromJson(Map<String, dynamic> json) =>
      _$MyEntityFromJson(json);

  @override
  Map<String, dynamic> toJson() => _$MyEntityToJson(this);
}

Configuration Pattern

EntityConfiguration<MyEntity>(
  metadata: EntityMetadata(
    identifier: 'my-entities',
    name: 'MyEntity',
    pluralName: 'MyEntities',
    icon: Icons.inventory,
  ),
  api: MyEntityApi(),
  layouts: EntityLayoutDescriptor<MyEntity>(...),
  form: EntityFormDescriptor<MyEntity>(...),
  actions: EntityActionsDescriptor<MyEntity>(...),
  route: EntityRouteBuilder.collection('my-entities'),
)

Relationship Types

One-to-Many:

EntityLayout<Parent>.detail(
  key: 'children',
  title: 'Children',
  builder: (context, parent) => RelatedEntitiesLayout<Parent, Child>(
    parent: parent,
    fetchRelated: (parent) async {
      final api = context.read<ChildApi>();
      return api.list(filters: {'parent_id': parent.id});
    },
  ),
)

Many-to-Many:

EntityLayout<Entity>.detail(
  key: 'related',
  title: 'Related',
  builder: (context, entity) => StandardRelatedEntitiesTab<Entity, Related>(
    parent: entity,
    relationSegment: 'related',
    emptyMessage: 'No related items',
  ),
)

Next Steps

1. Choose an example that matches your use case
2. Study the entity design to understand the data model
3. Review the layouts to see how data is presented
4. Examine the forms to understand input validation
5. Explore the API to see how operations are implemented
6. Adapt the patterns to your specific domain

Each example demonstrates production-ready patterns following Vyuh Framework best practices.

Additional Resources

• Entity Configuration - Detailed configuration options
• Forms - Form fields and validation
• Quick Start - Get started with entities
• Best Practices - Architecture guidelines