Eco Manager Wiki

Appearance

Universal Entity Platform ​

Purpose ​

The Universal Entity Platform is the core data and behavior model for Eco Manager.

It allows the product to model customers, sites, buildings, rooms, assets, credentials, tags, groups, and future concepts without repeated schema redesign.

Core Principle ​

Everything important is an entity.

Examples:

  • Customer
  • Site
  • Building
  • Room
  • Asset
  • Credential metadata
  • Tag
  • Group
  • Connection method
  • Vendor
  • User-facing collection

An entity provides identity, hierarchy, metadata, relationships, and auditability. Specific modules may add specialised behaviour where needed.

Entity Type Definitions ​

Entity types are data-driven rather than hard-coded PostgreSQL enums.

Examples:

text
customer
site
building
room
asset
credential
tag
group
connection_method
vendor

This allows new types to be added without database schema changes.

Hierarchy ​

Eco Manager uses both an adjacency list and an ltree materialised path.

Each entity has:

text
parent_entity_id
path

The parent pointer provides:

  • immediate parent lookup,
  • immediate child lookup,
  • foreign key integrity,
  • simple service logic.

The ltree path provides:

  • fast subtree queries,
  • fast ancestor queries,
  • depth calculations,
  • future tenant isolation,
  • future RLS policies.

Default hierarchy:

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

Future hierarchy:

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

Adding Room should not require a major redesign.

Entity Groups ​

An entity group is an entity that contains members by membership rather than strict hierarchy.

Groups are useful for:

  • commissioning batches,
  • maintenance sets,
  • critical asset lists,
  • regional collections,
  • customer portfolios,
  • tag collections,
  • reporting scopes.

A group may contain mixed entity types if allowed by its configuration.

Example:

text
Commissioning Batch 2026-07
├── Asset A
├── Asset B
└── Asset C

This is not containment. It is membership.

Property Groups ​

Property groups organize typed properties into meaningful sections.

Examples:

text
Device
├── Manufacturer
├── Model
├── Serial Number
└── Firmware Version
text
Network
├── IP Address
├── Subnet Mask
├── Gateway
└── VLAN
text
BACnet
├── Device Instance
├── Network Number
└── MAC Address
text
Credentials
├── Username
└── Secret Reference

Property groups allow developers to build structured forms and views consistently.

Property Definitions ​

A property definition describes a property that can be assigned to entities.

It should define:

  • key,
  • display name,
  • value type,
  • validation rules,
  • whether it is required,
  • whether it is sensitive,
  • whether it participates in search,
  • which property group owns it.

Sensitive values must not be stored as ordinary property values. They must be stored through the Vault.

Tags and Tag Groups ​

Tags are entities.

Tag groups organize tags into useful sets.

Examples:

text
Criticality
├── Low
├── Medium
└── High
text
Commissioning Status
├── Not Started
├── In Progress
├── Blocked
└── Complete
text
Vendor
├── Trend
├── Siemens
├── Schneider
└── Tridium

A tag group may be configured as:

  • single-select,
  • multi-select,
  • system-managed,
  • user-managed.

Relationships ​

Relationships are separate from hierarchy.

Hierarchy answers:

text
Where is this thing?

Relationships answer:

text
How is this thing associated with another thing?

Examples:

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

Containment should not be stored in the relationship graph. Containment belongs to parent_entity_id and path.

Templates ​

Templates combine entity type, property groups, tag groups, and defaults.

Example asset template:

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

Templates allow developers and authorized users to introduce new object types and forms with minimal code.

Metadata-Assisted UI, Not a Low-Code Builder ​

The frontend should use metadata to reduce repetitive development work and keep common screens consistent, but Eco Manager is not intended to become a drag-and-drop website builder. Application-level forms, workflows, permissions, validation, integration behavior, and operational logic should still be designed and implemented by developers.

Metadata should help developers build common product surfaces faster, including:

  • create and edit forms for known entity types,
  • detail views,
  • property sections,
  • tag selectors,
  • filters,
  • search facets,
  • table columns,
  • basic dashboards.

Custom UI and explicit application code should be used for workflows that need special behavior, such as Vault reveal, remote session launch, approval, audit review, Simpro synchronization, remote connectivity, and operational session handling.

Future versions may introduce user-facing tools for configuring rules, integrations, automations, or external-service workflows. That should be treated as a deliberate product capability, not as the Alpha architecture goal.

Admin Studio ​

Admin Studio is the dedicated app for managing the Universal Entity Platform.

It should provide powerful CRUD and configuration tools across entity types, entities, properties, tags, groups, templates, and relationships while preserving strict authorization, audit, and root-scope boundaries.

Design Goal ​

The goal is a strongly opinionated metadata-driven platform that makes common asset-management changes easy while preserving maintainable code, clear permissions, predictable behavior, and excellent developer experience.

The architecture should be flexible enough to grow into more user-configurable behavior later, without forcing the initial product into a generic low-code platform.