@symbiosedb/studio-ui

Beautiful web-based IDE for SymbioseDB with query editing, graph visualization, and data management.

A production-ready Next.js 14 application that provides a complete database management interface with Apple-inspired design, real-time updates, and advanced features like time travel debugging and preview environments.

Why @symbiosedb/studio-ui?

Database Management. Beautifully Simple.

# Start Studio
npm run dev

# Open http://localhost:3000
# ✅ SQL, Cypher, GraphQL query editor with syntax highlighting
# ✅ Visual graph exploration with D3.js force-directed layout
# ✅ Query history and favorites with local storage
# ✅ Real-time data updates via WebSocket
# ✅ Time travel debugging with snapshot/restore
# ✅ CSV import/export for data management

No complex setup. No configuration files. Just beautiful database management that works.

✨ Features

Query Editor

• 📝 Multi-Language Support - SQL, Cypher (graph), GraphQL
• 🎨 Syntax Highlighting - Monaco editor integration
• 🔍 Schema-Aware Autocomplete - Intelligent suggestions
• ⚡ Live Query Preview - Debounced execution (300ms)
• 💾 Query History - Search and replay past queries
• ⭐ Favorites - Save frequently used queries
• 📊 Performance Metrics - Execution time tracking

Graph Visualization

• 🕸️ D3.js Force-Directed Layout - Interactive node visualization
• 🎯 Visual Query Builder - Drag-and-drop Cypher generation
• 🔍 Path Exploration - BFS/DFS algorithms for traversal
• 🎨 Customizable Styling - Node colors, sizes, labels
• 📐 Zoom & Pan - Smooth navigation
• 🖱️ Click & Drag - Interactive node positioning
• 📊 Relationship Properties - View edge metadata

Data Management

• ✏️ CRUD Operations - Create, read, update, delete
• 📥 CSV Import - Bulk data import with validation
• 📤 CSV Export - Export query results
• 🔍 Advanced Filtering - Multi-column filters
• 📄 Pagination - Handle large datasets
• 🗂️ Schema Browser - Visual table structure
• 📊 Data Preview - Sample data view

Advanced Features

• ⏱️ Time Travel Debugging - Snapshot & restore database state
• 🌿 Preview Environments - Git-branch databases
• 🔄 Real-Time Updates - WebSocket subscriptions
• 📊 Visual Timeline - Scrub through database history
• 🎯 Point-in-Time Recovery - Restore to any timestamp
• 🔒 Authentication - JWT and API key support

Design System

• 🎨 Apple-Inspired - Linear, Stripe, Arc Browser aesthetic
• 🌗 Dark/Light Modes - Automatic theme switching
• 📱 Responsive - Mobile-first design
• ♿ Accessible - WCAG AAA compliance
• 🎬 Smooth Animations - 150ms/250ms/350ms timing
• 💫 Micro-Interactions - Delightful UX

📦 Installation

# Clone repository
git clone https://github.com/symbiosedb/symbiosedb.git
cd symbiosedb/packages/studio-ui

# Install dependencies
npm install

# Set environment variables
cp .env.example .env.local
# Edit .env.local with your settings

# Start development server
npm run dev

# Open http://localhost:3000

Dependencies:

• Next.js >= 14.0.0
• React >= 18.2.0
• D3.js >= 7.8.5
• @symbiosedb/design-system
• @symbiosedb/preview-environments
• @symbiosedb/auto-seed

🚀 Quick Start

1. Configure Connection

Create .env.local file:

# SymbioseDB API
NEXT_PUBLIC_SYMBIOSEDB_API_URL=http://localhost:3000
NEXT_PUBLIC_SYMBIOSEDB_API_KEY=your-api-key

# WebSocket (Real-time)
NEXT_PUBLIC_REALTIME_URL=ws://localhost:8080

# Optional: GitHub OAuth for Preview Environments
GITHUB_CLIENT_ID=your-github-client-id
GITHUB_CLIENT_SECRET=your-github-client-secret
GITHUB_WEBHOOK_SECRET=your-webhook-secret

2. Start Studio

npm run dev

Navigate to http://localhost:3000

3. Execute Your First Query

1. Open query editor
2. Select database type (SQL/Cypher/GraphQL)
3. Write query:

   SELECT * FROM users LIMIT 10

4. Press Cmd+Enter or click "Execute"
5. View results in table format

4. Explore Graph Data

1. Switch to "Graph" tab
2. Execute Cypher query:

   MATCH (u:User)-[:FOLLOWS]->(f:User)
   RETURN u, f
   LIMIT 20

3. View interactive force-directed graph
4. Click and drag nodes to rearrange
5. Hover for relationship details

🎨 Features in Detail

Query Editor

Keyboard Shortcuts:

• Cmd+Enter / Ctrl+Enter - Execute query
• Cmd+S / Ctrl+S - Save query to favorites
• Cmd+K / Ctrl+K - Open command palette
• Cmd+/ / Ctrl+/ - Toggle comment

Autocomplete:

• Table names after FROM, JOIN
• Column names after SELECT, WHERE
• Function names (COUNT, SUM, AVG)
• Cypher patterns (MATCH, WHERE, RETURN)

Query History:

• Automatic saving of all executed queries
• Search history by SQL text
• Filter by date range
• Re-execute with one click

Graph Visualization

Layout Algorithms:

• Force-Directed - Natural clustering (default)
• Hierarchical - Top-down tree structure
• Circular - Radial arrangement
• Grid - Organized matrix

Customization:

• Node colors by type
• Node sizes by property value
• Label display (auto-hide when crowded)
• Edge styling (solid, dashed, arrows)

Interactions:

• Click node → Show properties
• Double-click node → Expand relationships
• Right-click → Context menu
• Drag → Reposition node
• Scroll → Zoom in/out

Time Travel Debugging

Snapshots:

• Automatic snapshot on every write operation
• Manual snapshot creation
• Delta compression for efficient storage
• LRU eviction when limit reached

Timeline Navigation:

• Visual timeline with draggable slider
• Snapshot markers with timestamps
• Current position indicator
• Jump to specific time

Restore Operations:

• Preview mode (dry-run)
• Absolute timestamp restore
• Relative time restore (e.g., -5 minutes)
• Rollback to any snapshot

Preview Environments

Automatic Provisioning:

• Create database per Git branch
• Auto-generate preview URLs
• Seed with realistic data
• Auto-cleanup on branch deletion

Git Integration:

• GitHub webhook support
• Automatic deployment on push
• PR-based previews
• Branch tracking

💡 Examples

Example 1: Complex SQL Query

-- Top 10 active users with most followers
SELECT
  u.id,
  u.name,
  u.email,
  COUNT(DISTINCT f.follower_id) as follower_count,
  COUNT(DISTINCT p.id) as post_count
FROM users u
LEFT JOIN followers f ON f.user_id = u.id
LEFT JOIN posts p ON p.user_id = u.id
WHERE u.last_login > NOW() - INTERVAL '30 days'
GROUP BY u.id, u.name, u.email
ORDER BY follower_count DESC
LIMIT 10

Example 2: Graph Pattern Matching

// Find friend recommendations (friends of friends)
MATCH (me:User {id: $userId})-[:FOLLOWS]->(friend)-[:FOLLOWS]->(fof)
WHERE fof.id <> $userId
  AND NOT (me)-[:FOLLOWS]->(fof)
RETURN DISTINCT fof.id, fof.name, COUNT(friend) as mutual_friends
ORDER BY mutual_friends DESC
LIMIT 10

Example 3: GraphQL Query

query {
  users(
    where: { active: { eq: true } }
    orderBy: { createdAt: DESC }
    limit: 10
  ) {
    id
    email
    name
    posts {
      id
      title
      createdAt
    }
  }
}

Example 4: Time Travel Restore

// Navigate to Time Travel tab
// 1. View timeline of snapshots
// 2. Drag slider to desired point
// 3. Click "Preview" to see changes
// 4. Click "Restore" to apply

// Programmatic restore via API:
const restored = await fetch('/api/time-travel/restore', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    timestamp: Date.now() - 300000, // 5 minutes ago
    preview: false
  })
});

Example 5: CSV Import

// Navigate to Data Management tab
// 1. Click "Import CSV"
// 2. Select table: "users"
// 3. Upload CSV file
// 4. Map columns
// 5. Click "Import"

// CSV format:
// email,name,age
// [email protected],Alice,30
// [email protected],Bob,25

// Result: 2 rows imported into users table

🔧 Configuration

Environment Variables

# API Connection
NEXT_PUBLIC_SYMBIOSEDB_API_URL=http://localhost:3000
NEXT_PUBLIC_SYMBIOSEDB_API_KEY=your-api-key

# WebSocket (Real-time)
NEXT_PUBLIC_REALTIME_URL=ws://localhost:8080

# Authentication (Optional)
NEXT_PUBLIC_AUTH_ENABLED=true
NEXTAUTH_SECRET=your-nextauth-secret
NEXTAUTH_URL=http://localhost:3000

# GitHub OAuth (Optional - for Preview Environments)
GITHUB_CLIENT_ID=your-github-client-id
GITHUB_CLIENT_SECRET=your-github-client-secret
GITHUB_WEBHOOK_SECRET=your-webhook-secret

# Analytics (Optional)
NEXT_PUBLIC_ANALYTICS_ID=your-google-analytics-id

# Feature Flags (Optional)
NEXT_PUBLIC_ENABLE_TIME_TRAVEL=true
NEXT_PUBLIC_ENABLE_PREVIEW_ENVS=true
NEXT_PUBLIC_ENABLE_GRAPH_VIZ=true

📚 Components Reference

Query Editor Component

import { QueryEditor } from '@/components/QueryEditor';

<QueryEditor
  defaultLanguage="sql"          // 'sql' | 'cypher' | 'graphql'
  onExecute={(query) => {...}}   // Execute callback
  enableHistory={true}           // Enable query history
  enableAutocomplete={true}      // Enable schema-aware autocomplete
  theme="dark"                   // 'dark' | 'light'
/>

Graph Visualization Component

import { GraphVisualization } from '@/components/GraphVisualization';

<GraphVisualization
  data={{
    nodes: [{ id: '1', label: 'User', properties: {...} }],
    edges: [{ source: '1', target: '2', type: 'FOLLOWS' }]
  }}
  layout="force-directed"        // Layout algorithm
  width={800}
  height={600}
  onNodeClick={(node) => {...}}  // Node click handler
/>

Timeline Viewer Component

import { TimelineViewer } from '@/components/TimelineViewer';

<TimelineViewer
  snapshots={allSnapshots}
  onRestore={(snapshot) => {...}}
  enablePreview={true}
/>

Preview Environments Component

import { PreviewEnvironments } from '@/components/PreviewEnvironments';

<PreviewEnvironments
  previews={allPreviews}
  onDelete={(id) => {...}}
  onRefresh={() => {...}}
/>

🐛 Troubleshooting

Issue 1: "Cannot connect to API" Error

Problem: Studio cannot connect to SymbioseDB API.

Solution: Check API URL in .env.local:

NEXT_PUBLIC_SYMBIOSEDB_API_URL=http://localhost:3000

Ensure API server is running:

cd packages/api
npm run dev

Issue 2: Graph Visualization Not Rendering

Problem: Graph tab shows blank screen.

Solution: Check browser console for errors. Ensure D3.js is loaded:

npm install d3@^7.8.5

Clear Next.js cache:

rm -rf .next
npm run dev

Issue 3: Query History Not Saving

Problem: Executed queries don't appear in history.

Solution: Check localStorage quota:

// In browser console
console.log(localStorage.getItem('queryHistory'));

// Clear if too large
localStorage.removeItem('queryHistory');

Issue 4: Real-Time Updates Not Working

Problem: Database changes don't appear automatically.

Solution: Check WebSocket connection:

NEXT_PUBLIC_REALTIME_URL=ws://localhost:8080

Ensure realtime server is running:

cd packages/realtime
npm run dev

Issue 5: Slow Performance with Large Graphs

Problem: Graph visualization lags with 500+ nodes.

Solution: Enable pagination or limit results:

-- Limit nodes
MATCH (n:User)
RETURN n
LIMIT 100

-- Or use filtering
MATCH (n:User)
WHERE n.active = true
RETURN n

🔗 Related Packages

• @symbiosedb/design-system - UI components and design tokens
• @symbiosedb/preview-environments - Git-branch databases
• @symbiosedb/auto-seed - Realistic data generation
• @symbiosedb/sdk - Client SDK for API calls

🧪 Running Tests

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Run with coverage
npm test -- --coverage

# Run specific test suite
npm test QueryEditor.test.tsx
npm test GraphVisualization.test.tsx
npm test TimelineViewer.test.tsx

Test Coverage: 372/372 tests passing (100%)

🏗️ Development

Project Structure

studio-ui/
├── app/                    # Next.js 14 app directory
│   ├── layout.tsx         # Root layout with theme
│   ├── page.tsx           # Homepage
│   ├── query/             # Query editor page
│   ├── graph/             # Graph visualization page
│   ├── data/              # Data management page
│   └── api/               # API routes
├── components/            # React components
│   ├── QueryEditor.tsx
│   ├── GraphVisualization.tsx
│   ├── TimelineViewer.tsx
│   ├── PreviewEnvironments.tsx
│   └── ...
├── lib/                   # Utilities
│   ├── db.ts             # Database client
│   ├── realtime.ts       # WebSocket client
│   └── theme.ts          # Theme management
├── public/               # Static assets
├── styles/               # Global CSS
└── __tests__/            # Jest tests

Build for Production

# Build optimized production bundle
npm run build

# Start production server
npm start

# Or deploy to Vercel
vercel deploy

📄 License

MIT © SymbioseDB

🌟 Show Your Support

If you find SymbioseDB Studio helpful:

• ⭐ Star us on GitHub
• 🐦 Follow us on Twitter
• 💬 Join our Discord

Built with ❤️ by the SymbioseDB team