Class Management Console (Admin)

Source: Copied from Plings-Docs/admin/class-management-console.md (2025-06-18).

This document specifies the administrative tooling required to curate and extend the ObjectClass ontology that underpins the Universal Object Graph System (UOGS). It also outlines a reusable graph-navigation pattern (“Bloom-style”) that can be applied to spatial and functional relations at the instance level.

1 Purpose

A dedicated console is critical to keep the class taxonomy clean, discoverable, and free of duplicates. It acts as a CMS for manufacturers, power users, and internal moderators while exposing AI-assisted workflows to accelerate new class creation.

2 Core Pages & Features

Page / View Primary Function Key UI Elements
Class Explorer (Tree Navigator) Browse the SUBCLASS_OF hierarchy • Lazy-loaded tree in left sidebar
• Search / filter bar
• Breadcrumbs & depth indicator
• Right-hand details panel (properties, component list, functional relations, audit log)
• Context menu: Add subclass, Duplicate, Export, Deprecate
Class Editor / Wizard Create new or edit existing classes Stepper: Basics → Components → Functional Relations → Review & Publish. Variant picker: “Minor bump” vs “Fork as new subclass”. Auto-validation (unique name, no cyclical parents, etc.)
Relation Manager Add / remove COMPATIBLE_WITH, POWERS, etc. Neo4j Bloom-style mini-map with drag-to-connect interaction, bulk select, and predicate dropdown
AI-Assisted Class Generator Draft classes from unstructured input Text/PDF dropzone → LLM suggests: name, description, properties, component requirements, compatibility edges
Governance / Review Queue Moderate community submissions Diff viewer, Approve / Request changes / Reject, comment thread

Re-use for Other Graphs

The Bloom-style navigator is generic and will also be used in:

  • Spatial Navigator – visualises IN, ON, NEXT_TO, … between instances.
  • Functional Navigator – visualises COMPATIBLE_WITH, WORKS_WITH, POWERS, … between instances.

Each navigator swaps the predicate palette but keeps the same UI primitives (zoom/pan canvas, mini-map, edge-drawer).

3 Technical Hooks (GraphQL)

Operation Description
classTree(parentId, depth) Returns SUBCLASS_OF children recursively
createClass(input) / updateClass(id, input) Write operations on ObjectClass nodes
addFunctionalRelation(fromClassId, toClassId, predicate) Adds compatibility edge
removeFunctionalRelation(..) Deletes edge
classUpdated(id) (subscription) Real-time update feed for collaborative edits

API layer enforces: no self-loops, duplicate edge block, auto-create inverses for directional predicates, and symmetric normalisation (per functional_relationships_system.md).

4 UX Guidelines

  1. Virtualised Lists – infinite scroll in tree for large taxonomies.
  2. Breadcrumbs – always visible so users understand context inside deep hierarchies.
  3. Colour & Badges – denote visibility (public, private), status (draft, deprecated), and version.
  4. Diff-First Publishing – when editing, show before/after diff to reduce accidental breaking changes.
  5. Inherited Preview – display functional relations inherited from parent classes in a lighter colour (uses inherited=true flag from API).

5 AI Extensions (Optional, but Recommended)

Feature Flow
Auto-Suggest Subclasses On class view, backend queries sales/catalogue data & proposes popular variants (e.g., different lengths, materials).
Consistency Checker LLM + rule engine flags inconsistent property naming (colour vs color), missing units, etc.
Ontology Gap Finder Scheduled job finds leaf nodes with large instance counts and suggests splitting.

6 Security & Governance

  • Only users with role class_admin or manufacturer ownership can create/edit their classes.
  • Private classes remain hidden from the public tree unless the viewer has access.
  • All writes are logged in Audit Log System (see audit_log_system.md).
  • Review queue required for public visibility if class owner ≠ Plings or trusted manufacturer.

7 No Schema Changes Needed

The console relies solely on existing nodes and relationships:

  • Taxonomy: :ObjectClass + SUBCLASS_OF
  • Component list: ComponentRequirement sub-docs and PART_OF when instantiated
  • Compatibility: functional predicates (COMPATIBLE_WITH, etc.) with inheritance rules

Therefore this document is purely an application-layer spec and sits alongside frontend_views_and_permissions.md and super_admin_console.md.