Eco Manager Wiki

Appearance

Universal Entity Platform Handbook ​

This handbook documents the Universal Entity Platform used by Eco Manager and similar asset-management systems.

The platform provides a reusable foundation for modelling customers, sites, buildings, rooms, assets, tags, groups, credentials, connection methods, and future business concepts without repeatedly redesigning the database and API.

Who This Is For ​

This pack is primarily for developers building the backend, frontend, database schema, contracts, tests, and future integrations.

It is also suitable for technical leads who need to review architecture decisions, data ownership, security boundaries, and long-term maintainability.

Design Summary ​

The Universal Entity Platform is based on a small set of stable primitives:

  • Entity
  • Entity Type
  • Hierarchy
  • Entity Group
  • Property Group
  • Property Definition
  • Property Value
  • Tag Group
  • Tag
  • Relationship
  • Template
  • Root Entity Scope
  • Lifecycle State
  • Audit Event

The hierarchy uses both:

text
parent_entity_id
path ltree

This gives developers:

  • direct parent lookup,
  • fast child lookup,
  • fast descendants,
  • fast ancestors,
  • strong foreign key integrity,
  • future RLS support.
  1. Core Concepts
  2. Data Model
  3. Hierarchy and ltree
  4. Properties and Metadata
  5. Tags and Groups
  6. Relationships
  7. Templates
  8. Authorization and Root Scope
  9. Lifecycle: Soft Delete, Restore, Purge
  10. Contracts and API Shape
  11. Backend Implementation Guide
  12. Drizzle and PostgreSQL Guide
  13. Frontend Integration Guide
  14. Testing Strategy
  15. Operational Notes

Pack Structure ​

text
docs/universal-entity-platform/
├── README.md
├── reference/
│   ├── 01-core-concepts.md
│   ├── 02-data-model.md
│   ├── 03-hierarchy-and-ltree.md
│   ├── 04-properties-and-metadata.md
│   ├── 05-tags-and-groups.md
│   ├── 06-relationships.md
│   ├── 07-templates.md
│   ├── 08-authorization-and-root-scope.md
│   ├── 09-lifecycle.md
│   └── glossary.md
├── implementation/
│   ├── 10-contracts-and-api.md
│   ├── 11-backend-implementation.md
│   ├── 12-drizzle-postgres.md
│   └── 13-frontend-integration.md
├── testing/
│   └── 14-testing-strategy.md
├── operations/
│   └── 15-operational-notes.md
├── decisions/
│   ├── ADR-0001-universal-entity-platform.md
│   ├── ADR-0002-parent-plus-ltree.md
│   ├── ADR-0003-metadata-assisted-ui.md
│   └── ADR-0004-root-entity-scoped-authorization.md
└── templates/
    ├── entity-type-spec-template.md
    ├── property-group-template.md
    └── use-case-template.md

What This Platform Is Not ​

The Universal Entity Platform is not intended to become an unrestricted low-code website builder.

Developers still own application-level forms, workflows, integration logic, authorization logic, custom UI, and operational behavior.

The platform is intended to make common modelling and CRUD work consistent, type-safe, reusable, and easier to extend.