Eco Manager Wiki

Appearance

07 — Frontend Architecture ​

The Admin Console frontend should be a developer-grade configuration interface for the entity platform.

It should be clear, safe, and fast to use.

Technology Assumptions ​

  • React 19
  • TanStack Router
  • TanStack Query
  • TanStack Form or React Hook Form
  • Zod contracts from packages/contracts
  • Hono client or typed fetch wrapper
  • shadcn/ui or equivalent component library

Suggested Feature Structure ​

text
apps/frontend/src/features/entity-platform-admin/

├── routes/
│   ├── model-versions.route.tsx
│   ├── model-version-detail.route.tsx
│   ├── entity-types.route.tsx
│   ├── property-groups.route.tsx
│   ├── property-definitions.route.tsx
│   ├── relationship-definitions.route.tsx
│   ├── templates.route.tsx
│   └── publish.route.tsx
│
├── api/
│   ├── model-versions.api.ts
│   ├── entity-types.api.ts
│   ├── properties.api.ts
│   ├── relationships.api.ts
│   └── templates.api.ts
│
├── components/
│   ├── model-version-switcher.tsx
│   ├── metadata-table.tsx
│   ├── metadata-form-shell.tsx
│   ├── publish-status-card.tsx
│   ├── validation-results-panel.tsx
│   ├── impact-analysis-panel.tsx
│   └── destructive-change-warning.tsx
│
├── forms/
│   ├── entity-type-form.tsx
│   ├── property-group-form.tsx
│   ├── property-definition-form.tsx
│   ├── relationship-definition-form.tsx
│   └── template-form.tsx
│
├── hooks/
│   ├── use-current-model-version.ts
│   ├── use-draft-model.ts
│   ├── use-published-model.ts
│   └── use-model-validation.ts
│
└── utils/
    ├── metadata-labels.ts
    ├── value-type-options.ts
    └── model-diff.ts

Admin Console Navigation ​

Suggested navigation:

text
Model Versions
Entity Types
Hierarchy Rules
Property Groups
Property Definitions
Tag Groups
Tags
Relationship Definitions
Templates
Validation
Publish
Audit

UI Principles ​

  1. Show whether the user is editing a draft or viewing published model.
  2. Make destructive changes visually obvious.
  3. Validate early, but publish only after full backend validation.
  4. Show impact before publishing.
  5. Use consistent table/form patterns.
  6. Avoid hiding advanced details from developers.
  7. Provide enough explanation for technical administrators.
  8. Keep application-level logic out of metadata editing screens.

Metadata-Assisted Forms ​

The Admin Console itself may use conventional developer-built forms.

The runtime application can use metadata to help render forms for entity data.

Example runtime form generation:

  1. Load published model.
  2. Resolve entity type.
  3. Resolve assigned property groups.
  4. Render property inputs by value type.
  5. Validate with contract and metadata rules.
  6. Submit to generic runtime entity API.

Entity Type Form Fields ​

Recommended fields:

  • key,
  • name,
  • description,
  • icon,
  • color,
  • root allowed,
  • hierarchy allowed,
  • can have children,
  • allowed parent types,
  • allowed child types,
  • property groups,
  • tag groups.

Property Definition Form Fields ​

Recommended fields:

  • key,
  • name,
  • description,
  • property group,
  • value type,
  • required,
  • sensitive,
  • searchable,
  • filterable,
  • default value,
  • validation rules,
  • display order.

Relationship Definition Form Fields ​

Recommended fields:

  • key,
  • name,
  • description,
  • source entity type,
  • target entity type,
  • cardinality,
  • directional,
  • self-reference allowed,
  • lifecycle behavior.

Publish Screen ​

The publish screen should show:

  • draft summary,
  • validation results,
  • warnings,
  • destructive changes,
  • affected runtime data counts,
  • required approvals,
  • final publish button.

Publishing should never feel like a casual save action.