Epic: Custom Entity Types - User-Defined Schemas with Natural Language Creation

[malibio]

Overview

Enable users to create custom entity types (like "Invoice", "Customer", "Training Session") through natural language descriptions, without requiring code changes or app restarts. Custom entities will work seamlessly with the existing slash command system, plugin registry, and schema-driven property UI.

Vision

User Experience:

User: "Create an Invoice entity with invoice number, amount, vendor, and status"
AI: Creates schema definition
→ Slash command "/invoice" immediately available (no restart)
→ User types "/invoice" → Creates invoice node with schema properties
→ Properties display in SchemaPropertyForm (already exists)
→ User fills in invoice details via auto-generated form

Architecture Summary

NodeSpace already has 90% of the infrastructure needed:

• ✅ Universal node schema - Single table supports any node type
• ✅ Flexible metadata - JSON field stores arbitrary properties
• ✅ Schema system - Defines fields, validation, types
• ✅ Schema-driven property UI - Auto-generates forms from schemas
• ✅ Plugin registry - Dynamic slash command discovery
• ✅ Hot-reloading support - No restart needed for new plugins

What's Missing:

• ❌ Hardcoded ALLOWED_NODE_TYPES validation (blocks custom types)
• ❌ Schema-to-plugin auto-registration (manual wiring needed)
• ❌ Natural language schema creation (AI integration)
• ❌ Generic entity rendering component

User Stories

Story 1: Invoice Tracking

As a freelancer
I want to create an Invoice entity type with amount, vendor, due date, and status
So that I can track my invoicing directly in NodeSpace

Story 2: Customer Management

As a small business owner
I want to create a Customer entity with name, email, phone, and notes
So that I can manage my customer relationships in one place

Story 3: Training Sessions

As a fitness coach
I want to create a Training Session entity with date, participants, exercises, and duration
So that I can plan and track my client sessions

Story 4: Rapid Prototyping

As a developer building a custom app
I want to define entity types through natural language
So that I can quickly prototype data models without writing code

Sub-Issues

1. Remove Hardcoded Node Type Validation - Enable Schema-Based Type Discovery #446: Remove Hardcoded Node Type Validation (Backend - Foundation)
2. Auto-Register Plugins for Custom Entity Schemas - Enable Hot-Reload Slash Commands #447: Auto-Register Plugins for Custom Entity Schemas (Frontend - Foundation)
3. Natural Language Schema Creation via MCP - AI-Powered Entity Definition #448: Natural Language Schema Creation via MCP (AI Integration - Enhancement)
4. Generic Custom Entity Rendering - Polish UI for Schema-Driven Types #449: Generic Custom Entity Rendering (Frontend - Enhancement)

Technical Architecture

Current Flow (Blocked):

User creates schema → Schema stored in DB
↓
User tries to create node with custom type
↓
❌ Backend validation: "Only text, task, date supported"

Target Flow (After Implementation):

User: "Create Invoice entity..."
↓
AI creates schema → Schema stored in DB
↓
Auto-register plugin → Slash command available
↓
User types "/invoice" → Creates invoice node
↓
BaseNode + SchemaPropertyForm render entity
↓
✅ Full CRUD without restart

Acceptance Criteria

Phase 1: Foundation (Issues #446, #447)

• Custom entity types can be created without code changes
• Backend validates types against schema existence (not hardcoded list)
• Slash commands automatically include custom entity types
• No app restart required when adding new entity types
• Generic rendering works for all custom types

Phase 2: AI Integration (Issue #448)

• Users can describe entities in natural language
• AI generates schema definitions with correct field types
• Properties use proper namespace prefixes (custom:, org:, plugin:)
• Schemas validate according to existing validation rules

Phase 3: Polish (Issue #449)

• Custom entities render cleanly with BaseNode + SchemaPropertyForm
• Fallback UI for entities without schemas
• Icon system supports custom types
• Documentation for creating custom components (optional enhancement)

Success Metrics

• Users can create 5+ custom entity types in under 5 minutes
• No backend deployments required for new entity types
• 100% compatibility with existing node features (mentions, hierarchy, etc.)
• Zero performance degradation vs. built-in types

Related Documentation

• Node Behavior System - Hybrid core vs extension architecture
• Schema Management Guide - Schema system details
• Component Architecture - Component patterns
• Plugin System - Plugin registry documentation

Implementation Timeline

• Week 1: Backend validation removal (Remove Hardcoded Node Type Validation - Enable Schema-Based Type Discovery #446)
• Week 1: Auto-registration system (Auto-Register Plugins for Custom Entity Schemas - Enable Hot-Reload Slash Commands #447)
• Week 2: Natural language schema creation (Natural Language Schema Creation via MCP - AI-Powered Entity Definition #448)
• Week 2: UI polish and testing (Generic Custom Entity Rendering - Polish UI for Schema-Driven Types #449)

Dependencies

• None - All infrastructure exists
• Post-implementation: Could enhance with custom component system (Advanced Plugin Architecture Enhancement #85 - Advanced Plugin Architecture)

Risk Assessment

Low Risk - This is an enabling change that leverages existing, tested infrastructure:

• Schema system already production-ready
• Plugin registry already supports runtime registration
• No database migrations required
• Backward compatible with existing types

---

Labels: epic, foundation, enhancement, ai-integration, backend, frontend

[malibio]

All sub-issues complete:

• ✅ Remove Hardcoded Node Type Validation - Enable Schema-Based Type Discovery #446 - Remove Hardcoded Node Type Validation
• ✅ Auto-Register Plugins for Custom Entity Schemas - Enable Hot-Reload Slash Commands #447 - Auto-Register Plugins for Custom Entity Schemas
• ✅ Natural Language Schema Creation via MCP - AI-Powered Entity Definition #448 - Natural Language Schema Creation via MCP
• ✅ Generic Custom Entity Rendering - Polish UI for Schema-Driven Types #449 - Generic Custom Entity Rendering

Custom entity types are now fully supported - users can create schemas via natural language, slash commands auto-register, and entities render with schema-driven UI.