oneie/one/things/plans/update-demos.md

Build apps, websites, and AI agents in English. Zero-interaction setup for AI agents (Claude Code, Cursor, Windsurf). Download to your computer, run in the cloud, deploy to the edge. Open source and free forever.

---
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<ConnectionState>({
  status: "connecting" | "connected" | "disconnected",
  backend: "https://veracious-marlin-319.convex.cloud",
  latency: number,
});

export const $demoGroup = atom<Id<"groups"> | null>(null);
export const $demoView = atom<"list" | "grid" | "graph">("list");
export const $demoFilters = atom<DemoFilters>({
  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