Eco Manager Wiki

Appearance

Core Concepts ​

Purpose ​

The Universal Entity Platform provides a stable, reusable foundation for modelling business objects that share common concerns:

  • identity,
  • hierarchy,
  • properties,
  • tags,
  • grouping,
  • relationships,
  • access control,
  • lifecycle management,
  • auditability.

Instead of creating a completely new CRUD stack for every new business object, developers define new entity types, property groups, tag groups, templates, and application-specific behavior.

Primary Rule ​

Every important business object is represented by exactly one entity.

Examples:

text
Customer    -> Entity
Site        -> Entity
Building    -> Entity
Room        -> Entity
Asset       -> Entity
Credential  -> Entity
Tag         -> Entity
Group       -> Entity

A domain table may still exist when the object has special behavior, but the object should still own one entity row.

Entity ​

An entity is the universal identity record.

It answers:

text
What is this object?
Where is it in the hierarchy?
Is it active or deleted?
What type is it?
What is its stable platform identity?

It does not store ordinary business attributes like hostname, serial number, address, or password.

Those are represented through domain tables, properties, or the Vault depending on behavior.

Entity Type ​

An entity type defines what kind of object an entity represents.

Examples:

text
customer
site
building
room
asset
credential
tag
group
connection_method
vendor

Entity types are stored as data, not PostgreSQL enums. This allows new types to be introduced without schema migrations.

Hierarchy ​

Hierarchy models containment.

Default Eco Manager hierarchy:

text
Customer
└── Site
    └── Building
        └── Asset

Future hierarchy:

text
Customer
└── Site
    └── Building
        └── Room
            └── Asset

Hierarchy answers:

text
Where is this thing located or owned structurally?

Hierarchy is implemented by:

text
entities.parent_entity_id
entities.path ltree

Do not store containment in the generic relationship table.

Relationship ​

Relationships model associations that are not containment.

Examples:

text
Asset uses Credential
Asset depends_on Asset
Asset connects_to Asset
User manages Asset
Connection Method applies_to Site

Relationships answer:

text
How is this thing associated with another thing?

They may form arbitrary graphs, including cycles where the business domain allows them.

Entity Group ​

An entity group is a named collection of entities.

Groups are useful for:

  • commissioning batches,
  • maintenance sets,
  • reporting scopes,
  • critical asset lists,
  • customer portfolios,
  • project collections,
  • user-defined collections.

A group is itself an entity, with members stored in a membership table.

Group membership is not containment.

Property Group ​

A property group is a named section of related properties.

Examples:

text
Device
Network
BACnet
Modbus
Credentials
Commissioning

Property groups are used by the frontend to organize forms and detail views.

Property Definition ​

A property definition describes a typed property that may be assigned to entities.

Examples:

text
hostname
ip_address
serial_number
firmware_version
bacnet_device_instance
commissioning_status

A property definition defines validation rules, display behavior, sensitivity, and searchability.

Property Value ​

A property value stores the actual value for an entity and property definition.

Example:

text
Entity: Asset A
Property: ip_address
Value: "192.168.1.40"

Sensitive values must not be stored as ordinary property values unless they are references to Vault-managed secrets.

Tag Group ​

A tag group organizes tags.

Examples:

text
Criticality
Commissioning Status
Vendor
Asset Class
Environment

Tag groups may be configured as single-select or multi-select.

Tag ​

A tag is an entity representing a label that can be assigned to other entities.

Examples:

text
Critical
Trend
Commissioned
Blocked
Production

Tags are assigned through a tagging table or a tagged_with relationship. Prefer a dedicated entity_tags table when tag querying and uniqueness matter.

Template ​

A template defines the expected metadata shape for a type of entity.

Example:

text
BACnet Controller Template
├── Property Groups
│   ├── Device
│   ├── Network
│   └── BACnet
└── Tag Groups
    ├── Vendor
    └── Commissioning Status

Templates help developers and authorized users create consistent entity forms and defaults.

Root Entity Scope ​

A root entity defines an authorization and tenancy boundary.

Examples:

text
Customer A root
Customer B root
Internal engineering root

A user may be scoped to one or more root entities.

Most operations must verify:

text
target.path <@ allowed_root.path

This concept can later support PostgreSQL RLS.

Lifecycle ​

Entities support soft delete, restore, and hard delete.

Normal deletion is soft deletion:

text
deleted_at = now()

Hard delete is explicit and normally performed by purge jobs after a retention period.