Eco Manager Wiki

Appearance

Admin Studio Architecture ​

Summary ​

Admin Studio is a separate frontend application in the Eco Manager monorepo.

It is a super-user/admin interface for the Universal Entity Platform. It should provide powerful CRUD, discovery, configuration, and inspection features while staying safe, auditable, and permission-aware.

Why A Separate App? ​

Admin Studio should be separate from the normal frontend because it has a different purpose and risk profile.

The main frontend is for operational users:

text
Engineers
Commissioning teams
Remote support users
Operations managers

Admin Studio is for platform-level work:

text
Super users
System administrators
Implementation leads
Developers
Product owners

Keeping it as a separate app gives:

  • cleaner routing,
  • clearer permission boundaries,
  • safer deployment controls,
  • focused user experience,
  • reduced risk of exposing admin features to normal users,
  • freedom to build a power-user UI without complicating engineer workflows.

Workspace Position ​

text
apps/
├── backend/
├── frontend/
└── admin/

apps/admin imports:

text
@eco-manager/contracts

It should not import:

text
@eco-manager/db

Only the backend talks to the database.

Backend Boundary ​

Admin Studio should use explicit admin routes and contracts.

Example:

text
/admin/entity-types
/admin/entities
/admin/property-groups
/admin/property-definitions
/admin/tag-groups
/admin/templates
/admin/groups
/admin/relationships
/admin/audit

These routes should call the same application services where appropriate, but they must enforce stricter capabilities than normal operational routes.

UX Model ​

Admin Studio should feel like a structured entity workspace.

Recommended layout:

text
Left sidebar
    Entity Types
    Hierarchy
    Groups
    Tags
    Templates
    Views

Center panel
    Current entity/type/template/editor

Right panel
    Properties
    Relationships
    Audit
    Permissions

Recommended power features:

  • global command palette,
  • global entity search,
  • recent entities,
  • pinned entities,
  • breadcrumbs from root path,
  • entity graph navigation,
  • soft-deleted item browser,
  • schema/configuration diff preview,
  • guarded bulk edits,
  • JSON inspector for advanced users.

Core Screens ​

Entity Type Explorer ​

Manage entity type definitions such as:

  • customer,
  • site,
  • building,
  • room,
  • asset,
  • credential,
  • tag,
  • group.

Entity Explorer ​

Browse and edit actual entities.

Views:

  • hierarchy tree,
  • table view,
  • graph relationships,
  • grouped collections,
  • search results.

Property Builder ​

Manage:

  • property groups,
  • property definitions,
  • validation rules,
  • display order,
  • sensitivity flags,
  • searchable flags.

Tag Builder ​

Manage:

  • tag groups,
  • tags,
  • single-select / multi-select behavior,
  • colours,
  • system/user-managed flags.

Template Builder ​

Manage templates that compose:

  • entity type,
  • property groups,
  • tag groups,
  • default tags,
  • default relationships,
  • default validation rules.

Relationship Explorer ​

Inspect and manage graph relationships such as:

  • uses,
  • depends_on,
  • connects_to,
  • managed_by,
  • applies_to.

Group Manager ​

Manage entity groups and memberships.

Examples:

  • commissioning batches,
  • critical asset sets,
  • maintenance scopes,
  • reporting collections.

Audit Inspector ​

Inspect audit events and sensitive operations.

Admin Studio should make it easy to answer:

  • who changed this,
  • when did it change,
  • what changed,
  • what entity was affected,
  • was this a secret operation,
  • was this a bulk operation.

Guardrails ​

Admin Studio must enforce strong guardrails.

Capability Checks ​

Examples:

text
admin.entity_type.create
admin.entity_type.update
admin.entity_type.delete
admin.template.update
admin.property_definition.update
admin.bulk_update
admin.purge

Root Entity Scope ​

Even admin operations should be scoped unless the user has platform-wide capability.

Example:

text
User can edit entities only when target.path <@ allowed_root.path

Dangerous Operations ​

Dangerous operations should require:

  • explicit confirmation,
  • preview of affected records,
  • audit reason,
  • capability check,
  • transaction boundary.

Examples:

  • reparent subtree,
  • bulk update,
  • delete subtree,
  • restore subtree,
  • purge deleted records,
  • change property definition type,
  • retire tag group,
  • rotate tenant encryption key.

Relationship To Metadata-Assisted UI ​

Admin Studio should use metadata heavily, but it is not a no-code application builder.

Developers still own:

  • application workflows,
  • backend logic,
  • external integrations,
  • security-critical behavior,
  • custom operational screens,
  • remote access flows,
  • Vault reveal/copy/rotation flows.

Admin Studio gives trusted users and developers the power to configure the platform model safely.

MVP Scope ​

Alpha Admin Studio should include:

  • entity type CRUD,
  • entity browse/edit,
  • hierarchy tree,
  • property group CRUD,
  • property definition CRUD,
  • tag group CRUD,
  • tag CRUD,
  • entity group CRUD,
  • template CRUD,
  • relationship inspection,
  • soft-delete browser,
  • audit event view.

Out of scope for Alpha:

  • visual automation builder,
  • arbitrary external API connector builder,
  • custom page builder,
  • unrestricted script execution,
  • direct database table editor.