--- title: Update Demos dimension: things category: plans tags: architecture, backend, connections, groups, ontology, people, things related_dimensions: connections, events, groups, knowledge, people scope: global created: 2025-11-03 updated: 2025-11-03 version: 1.0.0 ai_context: | This document is part of the things dimension in the plans category. Location: one/things/plans/update-demos.md Purpose: Documents demo pages modernization plan Related dimensions: connections, events, groups, knowledge, people For AI agents: Read this to understand update demos. --- # Demo Pages Modernization Plan **Status:** Planning **Version:** 1.0.0 **Created:** 2025-10-25 **Ontology Version:** 2.0.0 (6-Dimension Architecture) ## Executive Summary The ONE Platform demo pages (`/demo/*`) showcase the 6-dimension ontology but need modernization to be **beautifully interactive and useful**. This plan transforms static demo pages into living, breathing examples of the ONE Platform's power. ## Current State Analysis ### What Exists (8 Demo Pages) | Page | Status | Backend Connected | Interactive | Notes | | ------------------- | --------------- | ----------------- | -------------- | --------------------------- | | `/demo` | ✅ Working | Partial | ❌ Static | Index page with navigation | | `/demo/groups` | ⚠️ Needs Update | ❌ No | ❌ Static | Groups dimension demo | | `/demo/people` | ✅ Working | ✅ Yes | ✅ Interactive | **REFERENCE** - Just fixed! | | `/demo/things` | ⚠️ Needs Update | ❌ No | ❌ Static | Things dimension demo | | `/demo/connections` | ⚠️ Needs Update | ❌ No | ❌ Static | Connections dimension demo | | `/demo/events` | ⚠️ Needs Update | ❌ No | ❌ Static | Events dimension demo | | `/demo/search` | ⚠️ Needs Update | ❌ No | ❌ Static | Knowledge/search demo | | `/demo/api` | ⚠️ Needs Update | ❌ No | ❌ Static | API documentation | ### Backend Infrastructure (Excellent!) **Available Resources:** - ✅ 8 mutation files (groups, people, things, connections, knowledge, contact, init, onboarding) - ✅ 10 query files (all dimensions covered) - ✅ 90 exported functions total - ✅ HTTP API with all 6 dimensions exposed - ✅ Convex backend at `https://veracious-marlin-319.convex.cloud` **The backend is 100% ready - we just need to connect the frontend!** ## The Vision: Living Ontology Demos ### Design Principles 1. **Interactive, Not Static** - Every dimension has live data manipulation 2. **Real Backend** - All demos connect to actual backend (no fake data) 3. **Beautiful UX** - Smooth animations, instant feedback, delightful interactions 4. **Educational** - Teach users how the ontology works through interaction 5. **Progressive** - Start simple, reveal complexity on demand 6. **Consistent Pattern** - Same structure across all dimension pages ### The Perfect Demo Pattern Each dimension page follows this structure: ``` ┌─────────────────────────────────────────────────────────┐ │ 1. HERO - What is this dimension? │ │ - Title, description, icon │ │ - Live connection status badge │ │ - "Try it now" CTA │ └─────────────────────────────────────────────────────────┘ ↓ ┌─────────────────────────────────────────────────────────┐ │ 2. INTERACTIVE PLAYGROUND │ │ - Live data from backend │ │ - Create/Read/Update/Delete operations │ │ - Real-time updates │ │ - Beautiful error handling │ └─────────────────────────────────────────────────────────┘ ↓ ┌─────────────────────────────────────────────────────────┐ │ 3. CODE EXAMPLES │ │ - React hooks for this dimension │ │ - HTTP API endpoints │ │ - Copy-paste ready examples │ └─────────────────────────────────────────────────────────┘ ↓ ┌─────────────────────────────────────────────────────────┐ │ 4. RELATIONSHIPS EXPLORER │ │ - How this dimension connects to others │ │ - Visual relationship graph │ │ - Example use cases │ └─────────────────────────────────────────────────────────┘ ↓ ┌─────────────────────────────────────────────────────────┐ │ 5. NEXT STEPS │ │ - Link to next dimension │ │ - Related documentation │ │ - Build something section │ └─────────────────────────────────────────────────────────┘ ``` ## Implementation Plan (100 Cycles) ### Phase 1: Foundation (Cycle 1-20) **Cycle 1-5: Create Shared Components** - `DemoContainer.tsx` - Wrapper with connection status - `DemoPlayground.tsx` - Interactive data manipulation - `DemoCodeBlock.tsx` - Syntax-highlighted code examples - `DemoStats.tsx` - Live statistics display - `DemoRelationshipGraph.tsx` - Visual relationship explorer **Cycle 6-10: Update Demo Index Page** - Add live backend connection test - Show real statistics from all dimensions - Add "health check" visualization - Improve navigation cards with counts - Add quick start guide **Cycle 11-15: Create Demo Hooks** - `useBackendConnection.ts` - Manage connection state - `useDemoData.ts` - Fetch and cache demo data - `useDemoMutation.ts` - Handle create/update/delete - `useDemoRefresh.ts` - Auto-refresh data - Error handling utilities **Cycle 16-20: Setup Demo State Management** - Nanostores for demo state - Cache layer for demo data - Optimistic updates - Real-time sync - Toast notifications ### Phase 2: Dimension 1 - Groups (Cycle 21-30) **Cycle 21-23: Groups List & Create** - Display all groups from backend - Create new group form (inline) - Group type selector (6 types) - Hierarchical display (parent → child) **Cycle 24-26: Group Details** - Click group to see details - Edit group properties - Group settings panel - Member count, usage stats **Cycle 27-29: Group Hierarchy** - Visual tree structure - Drag-and-drop to reparent - Create subgroup inline - Breadcrumb navigation **Cycle 30: Groups Code Examples** - `useGroups()` hook example - HTTP API examples - Create group mutation - List groups query ### Phase 3: Dimension 2 - People (Cycle 31-40) **Cycle 31-33: Polish Existing Implementation** - ✅ Already working! (Just fixed) - Add profile pictures (avatar component) - Role badges with colors - Better form validation **Cycle 34-36: People Permissions** - Show what each role can do - Interactive permission matrix - Role hierarchy visualization - Try changing roles **Cycle 37-39: People Relationships** - Show people's group memberships - Display created things - Activity timeline - Social graph **Cycle 40: People Code Examples** - All hooks documented - Complete API reference - Auth integration examples ### Phase 4: Dimension 3 - Things (Cycle 41-50) **Cycle 41-43: Things Gallery** - Grid/list view toggle - Filter by type (66 types!) - Search by name - Sort by created/updated **Cycle 44-46: Create Thing** - Type selector with icons - Dynamic form based on type - Property builder - Status selector **Cycle 47-49: Thing Details** - Full property viewer - Connections to/from this thing - Events timeline for this thing - Edit inline **Cycle 50: Things Code Examples** - Create/read/update examples - Type-safe property access - Advanced querying ### Phase 5: Dimension 4 - Connections (Cycle 51-60) **Cycle 51-53: Connection Visualizer** - D3.js force-directed graph - Click node to see connections - Filter by relationship type (25 types) - Zoom & pan **Cycle 54-56: Create Connection** - Select from thing (autocomplete) - Select to thing (autocomplete) - Relationship type picker - Metadata editor **Cycle 57-59: Connection Explorer** - List all connections - Bidirectional display - Strength indicator - Temporal validity **Cycle 60: Connections Code Examples** - Graph traversal patterns - Relationship queries - Connection mutations ### Phase 6: Dimension 5 - Events (Cycle 61-70) **Cycle 61-63: Event Timeline** - Chronological list - Filter by type (67 types!) - Filter by actor/target - Time range selector **Cycle 64-66: Event Details** - Expand event to see metadata - Click actor/target to navigate - Event type explanation - Related events **Cycle 67-69: Event Analytics** - Event frequency chart - Popular event types - Activity heatmap - Export events (CSV/JSON) **Cycle 70: Events Code Examples** - Subscribe to events - Query event history - Event logging patterns ### Phase 7: Dimension 6 - Knowledge/Search (Cycle 71-80) **Cycle 71-73: Semantic Search** - Search box with instant results - Vector similarity display - Source highlighting - Relevance scoring **Cycle 74-76: Knowledge Creation** - Upload text/documents - Auto-chunking - Label selector - Embedding generation **Cycle 77-79: Knowledge Graph** - Visual knowledge connections - Topic clustering - Related knowledge - Knowledge lineage **Cycle 80: Knowledge Code Examples** - RAG implementation - Semantic search API - Knowledge creation ### Phase 8: API Demo Enhancement (Cycle 81-85) **Cycle 81-82: Interactive API Tester** - Select endpoint from dropdown - Fill parameters (autocomplete) - Execute request - View formatted response **Cycle 83-84: API Documentation** - Complete endpoint list - Request/response schemas - cURL examples - SDKs (TypeScript, Python, Go) **Cycle 85: API Playground** - Multi-tab request builder - Save requests - Share API examples - Export as Postman collection ### Phase 9: Polish & Performance (Cycle 86-95) **Cycle 86-88: Animations & Transitions** - Framer Motion for smooth transitions - Loading skeletons - Success/error animations - Page transitions **Cycle 89-91: Accessibility** - ARIA labels everywhere - Keyboard navigation - Screen reader testing - Focus management **Cycle 92-94: Performance** - React.memo for heavy components - Virtualized lists for large datasets - Debounced search - Image lazy loading **Cycle 95: Mobile Responsive** - Touch-friendly controls - Mobile-optimized layouts - Hamburger menu for nav - Swipe gestures ### Phase 10: Documentation & Testing (Cycle 96-100) **Cycle 96-97: User Guide** - Interactive tutorial - Video walkthrough - FAQ section - Troubleshooting **Cycle 98-99: Testing** - E2E tests for each dimension - Visual regression tests - Performance benchmarks - Accessibility tests **Cycle 100: Launch** - Deploy to production - Update main site links - Share on social media - Gather user feedback ## Technical Specifications ### Component Library **Core Components:** ```typescript // Shared across all dimension demos -DemoContainer.tsx - // Wrapper with status DemoHero.tsx - // Hero section DemoPlayground.tsx - // Interactive area DemoCodeBlock.tsx - // Code examples DemoStats.tsx - // Live statistics DemoGraph.tsx - // D3 visualizations DemoForm.tsx - // CRUD forms DemoList.tsx - // Data display DemoDetail.tsx - // Item details DemoToast.tsx; // Notifications ``` **Dimension-Specific:** ```typescript // Custom per dimension -GroupsHierarchy.tsx - // Tree structure PeopleMatrix.tsx - // Permission matrix ThingsGallery.tsx - // Thing type gallery ConnectionsGraph.tsx - // Force-directed graph EventsTimeline.tsx - // Chronological timeline KnowledgeSearch.tsx; // Semantic search UI ``` ### Data Flow ``` User Action → Demo Component → useDemoMutation hook ↓ HTTP API Call ↓ Backend Mutation/Query ↓ Database Update ↓ Real-time Refresh ↓ UI Update ``` ### State Management ```typescript // Demo stores (Nanostores) export const $demoConnection = atom({ status: "connecting" | "connected" | "disconnected", backend: "https://veracious-marlin-319.convex.cloud", latency: number, }); export const $demoGroup = atom | null>(null); export const $demoView = atom<"list" | "grid" | "graph">("list"); export const $demoFilters = atom({ type: null, status: null, search: "", }); ``` ### Styling **Tailwind Classes:** - Demo containers: `bg-white rounded-lg shadow-lg p-8` - Interactive areas: `border-2 border-dashed border-blue-200 rounded-lg p-6` - Success states: `bg-green-50 border-green-200 text-green-700` - Error states: `bg-red-50 border-red-200 text-red-700` - Code blocks: `bg-slate-900 text-slate-100 rounded-lg p-4` **Animations:** ```typescript // Framer Motion variants const containerVariants = { hidden: { opacity: 0, y: 20 }, visible: { opacity: 1, y: 0, transition: { duration: 0.3 }, }, }; const itemVariants = { hidden: { opacity: 0, x: -20 }, visible: (i: number) => ({ opacity: 1, x: 0, transition: { delay: i * 0.1 }, }), }; ``` ## Success Metrics **User Engagement:** - [ ] Average time on demo pages > 5 minutes - [ ] Demo interaction rate > 80% - [ ] Code copy rate > 50% - [ ] Return visitor rate > 40% **Technical Performance:** - [ ] Page load time < 1 second - [ ] Backend API latency < 200ms - [ ] Lighthouse score > 95 - [ ] Zero console errors **Educational Impact:** - [ ] Users understand 6 dimensions - [ ] Can explain ontology to others - [ ] Build first app within 30 minutes - [ ] Positive feedback score > 4.5/5 ## Reference Implementation **✅ /demo/people is the gold standard!** What makes it perfect: - ✅ Connects to real backend - ✅ Interactive form (Add User) - ✅ Real-time data updates - ✅ Beautiful UX with badges - ✅ Proper error handling - ✅ Loading states - ✅ Success feedback **Replicate this pattern for all other dimensions!** ## Next Actions 1. **Read this plan thoroughly** 2. **Start with Cycle 1: Create DemoContainer.tsx** 3. **Follow the 100-cycle sequence** 4. **Test each component as you build** 5. **Deploy incrementally** ## Dependencies **Frontend:** - React 19 (installed) - Framer Motion (need to install) - D3.js (need to install for graphs) - React Syntax Highlighter (for code blocks) **Backend:** - ✅ All APIs ready - ✅ All queries/mutations working - ✅ HTTP endpoints tested **Design:** - ✅ Tailwind CSS v4 - ✅ shadcn/ui components - ✅ Lucide icons ## Conclusion This plan transforms demo pages from **static documentation** into **living, breathing showcases** of the ONE Platform's power. By following the 100-cycle sequence, we'll create demos that are: - 🎨 **Beautiful** - Delightful UX with smooth animations - 🔗 **Connected** - Real backend integration - 🎓 **Educational** - Teach through interaction - 🚀 **Inspiring** - Make builders want to create **The demos will become the #1 way people learn ONE Platform.** --- **Status:** Ready to implement **Assigned:** Frontend Specialist **Est. Time:** 100 cycles (not days - we plan in cycles!) **Priority:** High - Demos are our best marketing