Frontend Integration Guide

Purpose

The frontend should use the Universal Entity Platform to build powerful, consistent, developer-maintained application screens.

This is metadata-assisted UI, not a drag-and-drop website builder.

Developers still own:

• application routes,
• feature workflows,
• form composition,
• permissions UX,
• remote access flows,
• Vault flows,
• integration flows,
• custom business logic.

Metadata helps reduce repetitive CRUD work.

Frontend Responsibilities

The frontend should:

• import contracts from the contracts package,
• call typed API clients,
• render hierarchy navigation,
• render entity detail views,
• render property groups,
• render tag selectors,
• show group membership,
• show relationships,
• enforce optimistic UX rules where helpful,
• defer security enforcement to backend,
• handle API errors cleanly.

Suggested Feature Structure

apps/frontend/src/features/universal-entity-platform/
├── api/
│   ├── entity-queries.ts
│   ├── hierarchy-queries.ts
│   ├── property-mutations.ts
│   └── tag-mutations.ts
│
├── components/
│   ├── EntityBreadcrumb.tsx
│   ├── EntityTree.tsx
│   ├── EntityDetailHeader.tsx
│   ├── PropertyGroupSection.tsx
│   ├── TagSelector.tsx
│   ├── RelationshipList.tsx
│   └── GroupMembersTable.tsx
│
├── forms/
│   ├── EntityCreateForm.tsx
│   ├── EntityMoveForm.tsx
│   ├── PropertyValueField.tsx
│   └── TemplateBackedEntityForm.tsx
│
├── hooks/
│   ├── useEntity.ts
│   ├── useEntityChildren.ts
│   ├── useEntityPath.ts
│   └── useEntityTemplate.ts
│
└── pages/
    ├── EntityDetailPage.tsx
    ├── EntityChildrenPage.tsx
    └── EntityGroupPage.tsx

Hierarchy UX

Common views:

• tree navigation,
• breadcrumb path,
• children list,
• descendant table,
• move dialog,
• create child action.

Breadcrumb should use path endpoint:

GET /entities/:entityId/path

Children should use:

GET /entities/:entityId/children

Avoid loading entire subtrees unless needed.

Property UI

Property groups should render as sections.

Example:

Device
├── Manufacturer
├── Model
└── Serial Number

Network
├── IP Address
├── Subnet Mask
└── Gateway

Use property definition valueType to choose controls.

Examples:

valueType	Control
text	text input
long_text	textarea
number	number input
boolean	switch/checkbox
date	date picker
ip_address	validated text input
single_select	select
multi_select	multi-select
secret_reference	Vault-aware secret field
entity_reference	entity picker

Secret References

Secret values are not ordinary property values.

A secret_reference field should launch Vault-specific UI.

Examples:

• create credential,
• link existing secret,
• request reveal,
• copy secret,
• rotate secret.

Do not display or edit plaintext secrets in generic property forms.

Tags UX

Tag groups should render based on selection mode.

Single-select group:

Criticality: Low | Medium | High

Multi-select group:

Capabilities: BACnet, Modbus, Remote Access Ready

Tag assignment should be optimistic only if rollback is handled well.

Groups UX

Groups should support:

• create group,
• add members,
• remove members,
• show member table,
• filter by type,
• perform batch actions where authorized.

Group membership is not hierarchy, so do not show members as children in the structural tree unless the UI clearly labels the section as group membership.

Relationships UX

Show relationships separately from hierarchy.

Example sections:

Uses
Depends On
Connected To
Managed By

Relationships should link to entity detail pages.

Permissions UX

The frontend may hide unavailable actions based on capability hints, but the backend must enforce permissions.

UI should handle:

403 ENTITY_OUT_OF_SCOPE
403 CAPABILITY_DENIED
404 ENTITY_NOT_FOUND
409 CYCLE_DETECTED
422 INVALID_PROPERTY_VALUE

Use clear messages.

Examples:

You do not have access to this customer scope.

This move would create an invalid hierarchy.

Metadata-Assisted Forms

Generated form sections are acceptable.

Generated full applications are not the goal.

Recommended approach:

• developers create application pages,
• metadata controls sections and fields,
• custom components handle special workflows,
• contracts define API shapes,
• backend validates everything.

TanStack Query Keys

Suggested query keys:

["entity", entityId]
["entity", entityId, "children"]
["entity", entityId, "path"]
["entity", entityId, "properties"]
["entity", entityId, "tags"]
["entity", entityId, "relationships"]
["group", groupEntityId, "members"]
["template", templateId]

Invalidate carefully after mutations.

Examples:

Move entity:

invalidate old parent children
invalidate new parent children
invalidate target path
invalidate descendants if visible

Set property:

invalidate entity properties
invalidate entity detail if summary fields depend on property