Operational Notes

Purpose

This document covers operational concerns for running and maintaining the Universal Entity Platform.

Performance Expectations

The platform is optimized for read-heavy asset directory workloads.

Expected common reads:

• get children,
• get entity detail,
• get entity path,
• get descendants,
• get properties,
• get tags,
• get relationships.

Expected less frequent writes:

• create entity,
• update properties,
• assign tags,
• move subtree,
• soft-delete subtree,
• restore subtree.

ltree makes hierarchy reads fast. Reparenting is more expensive because descendant paths must be updated.

Index Monitoring

Important indexes:

idx_entities_parent
idx_entities_path_gist
idx_entities_active_type
idx_entity_relationships_source
idx_entity_relationships_target
idx_entity_property_values_active
idx_entity_tags_active
idx_entity_group_members_active

Use EXPLAIN ANALYZE when queries become slow.

Reparenting Large Subtrees

Moving a large subtree updates every descendant path.

Operational guidance:

• keep moves transactional,
• audit large moves,
• consider warning users for large subtree moves,
• consider background jobs for very large moves,
• disallow cross-root moves by default.

Soft Delete Large Subtrees

Soft delete can touch many tables.

For large subtrees:

• load affected ids efficiently,
• update dependent tables with set-based SQL,
• avoid row-by-row loops where possible,
• emit summary event plus selected per-entity events if needed.

Purge Jobs

Purge is physical deletion.

Recommended properties:

• explicit job,
• retention policy,
• dry-run mode,
• audit summary,
• admin-only execution,
• safe batching.

Example purge states:

eligible
in_progress
completed
failed

Backups

Backups must include:

• database data,
• migrations,
• seed metadata,
• key references if using encryption integrations,
• audit logs.

If Vault data is encrypted with external keys, backup strategy must account for key availability.

Observability

Useful metrics:

• entity count by type,
• active vs deleted entity count,
• average hierarchy depth,
• largest subtree size,
• reparent operation duration,
• soft-delete operation duration,
• property validation failures,
• authorization denials,
• slow hierarchy queries.

Useful traces:

• create entity,
• move entity,
• get descendants,
• soft delete subtree,
• restore subtree,
• apply template.

Audit Retention

Audit events should generally outlive ordinary entity records.

Do not physically delete audit records casually.

If legal or privacy requirements require redaction, prefer payload redaction over deleting the event row.

Metadata Governance

Because entity types, properties, tags, and templates are configurable, you need governance.

Recommended rules:

• system metadata can only be changed by developers/admins,
• user-created metadata can be scoped to root entity where needed,
• deleting property definitions should be restricted,
• renaming display names is safer than changing keys,
• keys should be stable once used.

Key Naming Rules

Stable keys should use:

lower_snake_case

Examples:

bacnet_device_instance
commissioning_status
network_ip_address

Avoid spaces, punctuation, or user-facing names as keys.

Migration Safety

When changing metadata shape:

• add new fields before removing old fields,
• backfill in batches,
• keep compatibility in contracts where needed,
• document migration impact,
• create an ADR for major shifts.

Disaster Recovery Considerations

Test restore of:

• hierarchy paths,
• soft-deleted records,
• metadata definitions,
• audit events,
• encryption key references where relevant.

Operational Anti-Patterns

Anti-pattern: Direct DB edits to path

Never manually edit entities.path without also validating parent and descendants.

Anti-pattern: Reusing path labels

Path labels must be immutable and unique.

Anti-pattern: Hard deleting entities manually

Manual deletes can break FK integrity and audit assumptions.

Anti-pattern: Uncontrolled metadata editing

Allowing anyone to change property definitions or templates can break forms, reports, and validation.