Technical Design Document: Cyc MVP

🛠 How We'll Build It

Recommended Approach: AI-Assisted Development

Based on your requirements and the power of modern AI coding tools, here's the strategy for building Cyc:

Primary Tool: Loveable.dev

Why it's perfect for you: It generates complete, production-ready applications from descriptions
What it costs: Already in your budget ✓
Learning curve: Easy - just describe what you want
Key strength: Can handle complex requirements like the Entertainment API

Supporting Tool (Recommended): Roo-Cline or Cursor

Why add this: For quick iterations and debugging after loveable.dev creates the base
What it costs: Roo-Cline is free (VS Code extension), Cursor is $20/month
When to use: When you need to tweak specific features or fix issues

Why This Approach Works for Cyc

Unlike traditional no-code tools, AI assistants can:

✅ Implement the Philips Hue Entertainment API properly (UDP streaming, DTLS encryption)
✅ Create smooth, low-latency light control
✅ Build a professional desktop application
✅ Handle complex networking and timing requirements

📋 Project Setup Checklist

Development Environment
- Install VS Code (free) - https://code.visualstudio.com/
- Install Node.js (free) - https://nodejs.org/
- Install Git (free) - https://git-scm.com/
- Install Roo-Cline extension in VS Code (optional but helpful)
Project Setup
- Create a new folder called "cyc-app"
- Open it in VS Code
- Create a GitHub repository (free) for backup
Philips Hue Setup
- Register for Philips Hue Developer account (free)
- Get your Hue Bridge IP address
- Generate an API username/token

🏗 Technical Architecture

Application Type: Electron Desktop App

Why Electron?

Works on Windows, Mac, and Linux
Uses familiar web technologies (HTML/CSS/JavaScript)
Can access system-level features needed for Entertainment API
Used by apps like Discord, Slack, VS Code

Core Technologies

Cyc Desktop App
├── Electron (Desktop wrapper)
├── Node.js (Backend/Entertainment API)
├── HTML/CSS/JavaScript (User Interface)
└── Local SQLite Database (Show files)

Data Flow

User presses GO → 
  Electron UI → 
    Node.js Backend → 
      Entertainment API (UDP) → 
        Hue Bridge → 
          Lights change

🎯 Building Your Features with AI

Feature 1: Cue List

Prompt for Loveable.dev/Roo-Cline:

Create an Electron desktop app with a cue list system for theatrical lighting:
- Display a numbered list of cues (Cue 1, Cue 2, etc.)
- Each cue has a name field and fade time setting
- Store cues in a local SQLite database
- Dark theme with high contrast for theater use
- Large, readable text

What the AI will build:

Database schema for cues
UI component for the cue list
Add/Edit/Delete functionality
Auto-save to local database

Feature 2: GO Button

Prompt for AI:

Add a large GO button to the app that:
- Takes up significant screen space (theater operators need to hit it quickly)
- Shows current cue number and name
- Shows next cue preview below
- Advances through cues sequentially when pressed
- Has visual feedback when pressed (color change/animation)
- Keyboard shortcut: Spacebar also triggers GO

Feature 3: Philips Hue Entertainment API Integration

Critical Prompt for AI:

Integrate Philips Hue Entertainment API for low-latency lighting control:
- Use the Entertainment API, NOT the standard REST API
- Implement UDP streaming with DTLS encryption
- Create entertainment groups for lights
- Stream at 25Hz for smooth fades
- Handle connection/disconnection gracefully
- Reference this documentation: https://developers.meethue.com/develop/hue-entertainment/

Important: The standard Hue API is too slow for theatrical use. Must use Entertainment API.

Libraries the AI should use:

node-dtls-client for DTLS encryption
dgram for UDP communication
Built-in Node.js crypto libraries

Feature 4: Fade Time Control

Prompt for AI:

Implement fade time control for each cue:
- Each cue stores a fade duration (0-30 seconds)
- When GO is pressed, lights fade smoothly over the specified duration
- Use Entertainment API's streaming to create smooth fades
- Show a progress bar during fades
- Allow stopping a fade in progress with an emergency STOP button

🎨 Design Implementation

UI Design Prompt for AI

Design the Electron app UI with:
- Dark background (#1a1a1a) with white/yellow text for contrast
- Split view: Cue list on left (30%), control panel on right (70%)
- GO button is green (#00ff00) and at least 200px tall
- Current cue highlighted in yellow
- Completed cues grayed out
- Sans-serif font (Arial or Helvetica) for clarity
- Minimum font size 16px for readability in dark theaters

📊 Database & Data Storage

Local Storage Strategy

SQLite database for show files (stored in app's user data folder)
Tables needed:
- shows (id, name, created_date, modified_date)
- cues (id, show_id, cue_number, name, fade_time)
- cue_lights (id, cue_id, light_id, color, brightness)
- settings (bridge_ip, api_token, entertainment_group)

No Cloud = No Ongoing Costs

Everything saves locally on the user's computer
No servers to pay for
No data privacy concerns
Shows can be exported/imported as JSON files for backup

🚀 Launching Your MVP

Building the App with AI

Day 1-2: Core Structure
- Use loveable.dev to generate initial Electron app
- Get basic window opening with mock cue list
Day 3-5: Hue Integration
- This is the hardest part - be patient with the AI
- Test with real Hue lights ASAP
- May need multiple prompts to get Entertainment API working
Day 6-7: Polish & Testing
- Add keyboard shortcuts
- Test full show run-through
- Build installer for your operating system

Packaging for Distribution

Prompt for AI:
"Add electron-builder to package the app as:
- .exe installer for Windows  
- .dmg for Mac
- .AppImage for Linux"

Estimated Costs

Development tools: $0 (VS Code, Node.js, Git)
Loveable.dev: Already budgeted ✓
Optional Cursor/Roo-Cline: $0-20/month
Hosting: $0 (it's a desktop app!)
Domain (if you want a website): $12/year
Total: $0-20/month

📚 Getting Unstuck - Your Lifelines

When the AI Gets Confused

Break down the request into smaller pieces
Provide example code from the Philips Hue developer docs
Reference specific libraries: "Use the node-dtls-client library"
Show error messages directly to the AI

Resource Library

Philips Hue Entertainment API:

Official Docs: https://developers.meethue.com/develop/hue-entertainment/
Python example (for AI reference): https://github.com/hrdasdominik/hue-entertainment-pykit
.NET example: https://www.nuget.org/packages/HueApi.Entertainment

Electron Development:

Quick Start: https://www.electronjs.org/docs/latest/tutorial/quick-start
Electron Forge (easy packaging): https://www.electronforge.io/

Community Help:

Philips Hue Developer Forum: https://developers.meethue.com/forum/
Electron Discord: https://discord.com/invite/APGC3k5yaH
Stack Overflow: Tag with [electron] and [philips-hue]

⚠️ Important Limitations & Workarounds

What this approach CAN'T do:

DMX Integration: This version is Philips Hue only
- Workaround: Document which Hue bulbs work best for theater
Instant Response: ~100-500ms latency is expected
- Workaround: Train operators to hit GO slightly early
100+ Lights: Hue Bridge maxes at 50-63 lights
- Workaround: Document multi-bridge setup for future version

Security Considerations:

Store Hue API tokens encrypted (AI can implement this)
Don't hardcode credentials
Local-only data means no cloud security risks

📈 Growth Path

After Successful MVP:

Immediate Additions (Week 3-4):
- BACK button for previous cue
- Blackout button
- Basic effects (color loops, pulses)
Version 2.0 (Month 2-3):
- Multiple show files
- Import/export shows
- Backup cue lists
- DMX integration (would need hardware)
When to Consider Professional Development:
- If you get 50+ paying customers
- If you need mobile apps
- If you want cloud sync

🎯 Success Checklist

AI can generate a working Electron app
Philips Hue Entertainment API connects successfully
Can create and save a cue list
GO button advances through cues with proper fade times
Latency is under 1 second
App packages as installable desktop software
Successfully run a complete show

💡 Key Prompting Strategy for Entertainment API

Since the Entertainment API is complex, here's the exact approach:

First, have AI create the basic app without Hue integration
Then add standard Hue API to test connection
Finally, upgrade to Entertainment API with this specific prompt:

Replace the standard Hue API with Entertainment API:
1. Create an Entertainment configuration using PUT /api/<username>/groups/<id>
2. Start streaming using PUT with {"stream":{"active":true}}
3. Send light data via UDP port 2100 using DTLS-PSK encryption
4. Format messages as per Entertainment API spec: [0x00, 0x00, sequence, 0x00, 0x00, 0x00, ...color data]
5. Stream at 25Hz (40ms intervals) for smooth fades
6. Use node-dtls-client library for DTLS implementation
7. Reference: https://developers.meethue.com/develop/hue-entertainment/philips-hue-entertainment-api/

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Technical Design Document: Cyc MVP

🛠 How We'll Build It

Recommended Approach: AI-Assisted Development

Why This Approach Works for Cyc

📋 Project Setup Checklist

🏗 Technical Architecture

Application Type: Electron Desktop App

Core Technologies

Data Flow

🎯 Building Your Features with AI

Feature 1: Cue List

Feature 2: GO Button

Feature 3: Philips Hue Entertainment API Integration

Feature 4: Fade Time Control

🎨 Design Implementation

UI Design Prompt for AI

📊 Database & Data Storage

Local Storage Strategy

No Cloud = No Ongoing Costs

🚀 Launching Your MVP

Building the App with AI

Packaging for Distribution

Estimated Costs

📚 Getting Unstuck - Your Lifelines

When the AI Gets Confused

Resource Library

⚠️ Important Limitations & Workarounds

📈 Growth Path

🎯 Success Checklist

💡 Key Prompting Strategy for Entertainment API

FilesExpand file tree

echDesign-Cyc-MVP.md

Latest commit

History

echDesign-Cyc-MVP.md

File metadata and controls

Technical Design Document: Cyc MVP

🛠 How We'll Build It

Recommended Approach: AI-Assisted Development

Why This Approach Works for Cyc

📋 Project Setup Checklist

🏗 Technical Architecture

Application Type: Electron Desktop App

Core Technologies

Data Flow

🎯 Building Your Features with AI

Feature 1: Cue List

Feature 2: GO Button

Feature 3: Philips Hue Entertainment API Integration

Feature 4: Fade Time Control

🎨 Design Implementation

UI Design Prompt for AI

📊 Database & Data Storage

Local Storage Strategy

No Cloud = No Ongoing Costs

🚀 Launching Your MVP

Building the App with AI

Packaging for Distribution

Estimated Costs

📚 Getting Unstuck - Your Lifelines

When the AI Gets Confused

Resource Library

⚠️ Important Limitations & Workarounds

📈 Growth Path

🎯 Success Checklist

💡 Key Prompting Strategy for Entertainment API