create-analytics-demo 1.0.0

package/README.md

@@ -0,0 +1,80 @@
+# create-analytics-demo
+
+Scaffold a real-time analytics event visualization (WebSocket + browser).
+
+Shows how events flow from your app to analytics services (Amplitude, Braze, etc.) with animated paths, code snippets, and an event history sidebar.
+
+## Usage
+
+```bash
+npx create-analytics-demo my-project
+```
+
+The CLI will ask for:
+- **App name** — displayed in the UI
+- **Accent color** — hex color for the brand theme
+
+Use `--defaults` / `-y` to skip prompts.
+
+## Quick start
+
+```bash
+cd my-project
+npm install
+cd demo-server && npm install && cd ..
+npm run demo
+```
+
+This opens `http://localhost:3000` with the visualization. Then send events from your app or with curl:
+
+```bash
+curl -X POST http://localhost:3001/event \
+  -H "Content-Type: application/json" \
+  -d '{
+    "event": "login completed",
+    "userId": "u_123",
+    "deviceId": "d_abc",
+    "properties": {"method": "email"}
+  }'
+```
+
+You'll see the event travel as an animated ball from the phone to the service logos. Click on a ball or sidebar item to see the Swift code snippet.
+
+## Customization
+
+Edit `src/demo.config.ts` to change:
+
+- **App name and theme** — colors, branding
+- **Services** — names, colors, logos (put images in `public/`)
+- **Event categories** — maps event names to display categories
+- **Secondary service events** — which events also go to the second service
+- **Code snippets** — Swift code shown when clicking an event
+- **Server/demo ports**
+
+## Project structure
+
+```
+my-project/
+├── demo-server/
+│   └── server.js             # Express + WebSocket server
+├── src/
+│   ├── demo.config.ts        # ← Edit this to customize everything
+│   ├── components/            # IPhoneFrame, TravelingBall, LiveCodePanel, etc.
+│   └── demo/
+│       └── DemoApp.tsx        # Main visualization
+├── public/                   # Service logos go here
+└── demo.html
+```
+
+## How it works
+
+1. **demo-server** receives POST requests at `/event` and broadcasts them via WebSocket
+2. **DemoApp** connects to the WebSocket and visualizes each event as an animated ball traveling along SVG paths from the phone to the service logos
+3. Click any event to see the corresponding code snippet
+4. The sidebar shows a scrollable event history
+
+## Deploy
+
+Pre-configured for Vercel (`vercel.json`) and Netlify (`netlify.toml`). Just connect your repo.
+
+For the WebSocket server, deploy `demo-server/` separately (e.g. Railway, Render) and update `demo.wsUrl` in `demo.config.ts`.

package/index.js

@@ -0,0 +1,161 @@
+#!/usr/bin/env node
+
+const path = require("path");
+const fs = require("fs");
+const prompts = require("prompts");
+const ejs = require("ejs");
+const chalk = require("chalk");
+
+const TEMPLATE_DIR = path.join(__dirname, "template");
+
+// ── Helpers ─────────────────────────────────────────────────────────────────
+
+function copyDir(src, dest, ejsVars) {
+  fs.mkdirSync(dest, { recursive: true });
+
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    const srcPath = path.join(src, entry.name);
+    let destName = entry.name;
+
+    // _gitignore → .gitignore
+    if (destName === "_gitignore") destName = ".gitignore";
+
+    const destPath = path.join(dest, destName);
+
+    if (entry.isDirectory()) {
+      copyDir(srcPath, destPath, ejsVars);
+    } else if (entry.name.endsWith(".ejs")) {
+      // Process EJS template
+      const template = fs.readFileSync(srcPath, "utf-8");
+      const rendered = ejs.render(template, ejsVars);
+      const finalName = destName.replace(/\.ejs$/, "");
+      fs.writeFileSync(path.join(dest, finalName), rendered);
+    } else {
+      // Copy as-is
+      fs.copyFileSync(srcPath, destPath);
+    }
+  }
+}
+
+function hexToRgba(hex, alpha) {
+  const r = parseInt(hex.slice(1, 3), 16);
+  const g = parseInt(hex.slice(3, 5), 16);
+  const b = parseInt(hex.slice(5, 7), 16);
+  return `rgba(${r}, ${g}, ${b}, ${alpha})`;
+}
+
+function lightenHex(hex, amount) {
+  let r = parseInt(hex.slice(1, 3), 16);
+  let g = parseInt(hex.slice(3, 5), 16);
+  let b = parseInt(hex.slice(5, 7), 16);
+  r = Math.min(255, r + amount);
+  g = Math.min(255, g + amount);
+  b = Math.min(255, b + amount);
+  return `#${r.toString(16).padStart(2, "0")}${g.toString(16).padStart(2, "0")}${b.toString(16).padStart(2, "0")}`;
+}
+
+// ── Main ────────────────────────────────────────────────────────────────────
+
+async function main() {
+  const args = process.argv.slice(2);
+  const useDefaults = args.includes("--defaults") || args.includes("-y");
+  const projectName = args.find((a) => !a.startsWith("-"));
+
+  if (!projectName) {
+    console.log(chalk.red("Usage: npx create-analytics-demo <project-name>"));
+    process.exit(1);
+  }
+
+  const targetDir = path.resolve(process.cwd(), projectName);
+
+  if (fs.existsSync(targetDir)) {
+    console.log(chalk.red(`Directory "${projectName}" already exists.`));
+    process.exit(1);
+  }
+
+  console.log();
+  console.log(chalk.bold("  create-analytics-demo"));
+  console.log(chalk.gray("  Real-time analytics visualization (Remotion + WebSocket)"));
+  console.log();
+
+  let appName, accentColor;
+
+  if (useDefaults) {
+    appName = projectName
+      .replace(/[-_]/g, " ")
+      .replace(/\b\w/g, (c) => c.toUpperCase());
+    accentColor = "#FC5B40";
+  } else {
+    const response = await prompts(
+      [
+        {
+          type: "text",
+          name: "appName",
+          message: "App name",
+          initial: projectName
+            .replace(/[-_]/g, " ")
+            .replace(/\b\w/g, (c) => c.toUpperCase()),
+        },
+        {
+          type: "text",
+          name: "accentColor",
+          message: "Accent color (hex)",
+          initial: "#FC5B40",
+          validate: (v) =>
+            /^#[0-9a-fA-F]{6}$/.test(v) || "Enter a valid hex color (e.g. #FC5B40)",
+        },
+      ],
+      { onCancel: () => process.exit(0) }
+    );
+    appName = response.appName;
+    accentColor = response.accentColor;
+  }
+  const accentSoft = lightenHex(accentColor, 30);
+
+  // Template variables
+  const vars = {
+    projectName,
+    appName,
+    accentColor,
+    accentSoft,
+  };
+
+  console.log();
+  console.log(chalk.cyan("  Scaffolding project..."));
+
+  // Copy template → target
+  copyDir(TEMPLATE_DIR, targetDir, vars);
+
+  // Make start-demo.sh executable
+  const startScript = path.join(targetDir, "start-demo.sh");
+  if (fs.existsSync(startScript)) {
+    fs.chmodSync(startScript, 0o755);
+  }
+
+  console.log(chalk.green("  ✔ Project created in ./" + projectName));
+  console.log();
+  console.log(chalk.bold("  Next steps:"));
+  console.log();
+  console.log(chalk.cyan(`    cd ${projectName}`));
+  console.log(chalk.cyan("    npm install"));
+  console.log(chalk.cyan("    cd demo-server && npm install && cd .."));
+  console.log(chalk.cyan("    npm run demo"));
+  console.log();
+  console.log(chalk.gray("  Then send events:"));
+  console.log(
+    chalk.gray(
+      '    curl -X POST http://localhost:3001/event -H "Content-Type: application/json" \\'
+    )
+  );
+  console.log(
+    chalk.gray(
+      `         -d '{"event":"login completed","userId":"u_123","deviceId":"d_abc","properties":{"method":"email"}}'`
+    )
+  );
+  console.log();
+}
+
+main().catch((err) => {
+  console.error(chalk.red(err.message));
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "create-analytics-demo",
+  "version": "1.0.0",
+  "description": "Scaffold a real-time analytics visualization project (Remotion + WebSocket)",
+  "bin": {
+    "create-analytics-demo": "index.js"
+  },
+  "files": [
+    "index.js",
+    "template/**"
+  ],
+  "dependencies": {
+    "chalk": "^4.1.2",
+    "ejs": "^3.1.10",
+    "prompts": "^2.4.2"
+  }
+}

package/template/_gitignore

@@ -0,0 +1,16 @@
+node_modules
+dist
+.DS_Store
+.env
+
+# Remotion output
+out
+
+# Demo build output
+demo-dist
+
+# AI editors/tools
+.claude
+.codex
+.cursor
+.gemini

package/template/demo-server/package.json.ejs

@@ -0,0 +1,15 @@
+{
+  "name": "<%= projectName %>-demo-server",
+  "version": "1.0.0",
+  "description": "WebSocket server for <%= appName %> analytics demo",
+  "main": "server.js",
+  "scripts": {
+    "start": "node server.js",
+    "dev": "node --watch server.js"
+  },
+  "dependencies": {
+    "cors": "^2.8.5",
+    "express": "^4.18.2",
+    "ws": "^8.16.0"
+  }
+}

package/template/demo-server/server.js.ejs

@@ -0,0 +1,106 @@
+const express = require('express');
+const cors = require('cors');
+const { WebSocketServer } = require('ws');
+const http = require('http');
+
+const app = express();
+const PORT = 3001;
+
+// Middleware
+app.use(cors());
+app.use(express.json());
+
+// Create HTTP server
+const server = http.createServer(app);
+
+// Create WebSocket server
+const wss = new WebSocketServer({ server });
+
+// Store connected clients
+const clients = new Set();
+
+// WebSocket connection handling
+wss.on('connection', (ws) => {
+  console.log('Browser connected');
+  clients.add(ws);
+
+  // Send welcome message
+  ws.send(JSON.stringify({
+    type: 'connected',
+    message: 'Connected to <%= appName %> Demo Server',
+    timestamp: new Date().toISOString()
+  }));
+
+  ws.on('close', () => {
+    console.log('Browser disconnected');
+    clients.delete(ws);
+  });
+
+  ws.on('error', (error) => {
+    console.error('WebSocket error:', error);
+    clients.delete(ws);
+  });
+});
+
+// Broadcast to all connected clients
+function broadcast(data) {
+  const message = JSON.stringify(data);
+  clients.forEach((client) => {
+    if (client.readyState === 1) { // WebSocket.OPEN
+      client.send(message);
+    }
+  });
+}
+
+// HTTP endpoint to receive events from app
+app.post('/event', (req, res) => {
+  const event = {
+    type: 'analytics_event',
+    ...req.body,
+    receivedAt: new Date().toISOString()
+  };
+
+  console.log(`Event received: ${event.event}`);
+  console.log(`  userId: ${event.userId || 'anonymous'}`);
+  console.log(`  deviceId: ${event.deviceId}`);
+  if (event.properties) {
+    console.log(`  properties:`, event.properties);
+  }
+  console.log('');
+
+  // Broadcast to all connected browsers
+  broadcast(event);
+
+  res.status(200).json({ success: true });
+});
+
+// Health check endpoint
+app.get('/health', (req, res) => {
+  res.json({
+    status: 'ok',
+    clients: clients.size,
+    timestamp: new Date().toISOString()
+  });
+});
+
+// Reset endpoint (to clear state in browser)
+app.post('/reset', (req, res) => {
+  console.log('Reset requested');
+  broadcast({ type: 'reset', timestamp: new Date().toISOString() });
+  res.json({ success: true });
+});
+
+// Start server
+server.listen(PORT, () => {
+  console.log('');
+  console.log('='.repeat(55));
+  console.log('   <%= appName %> Demo Server');
+  console.log('='.repeat(55));
+  console.log('');
+  console.log(`   HTTP endpoint:  http://localhost:${PORT}/event`);
+  console.log(`   WebSocket:      ws://localhost:${PORT}`);
+  console.log(`   Health check:   http://localhost:${PORT}/health`);
+  console.log('');
+  console.log('   Waiting for connections...');
+  console.log('');
+});

package/template/demo.html.ejs

@@ -0,0 +1,28 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title><%= appName %> Analytics - Live Demo</title>
+    <style>
+      * {
+        margin: 0;
+        padding: 0;
+        box-sizing: border-box;
+      }
+      body {
+        background: #0a0a12;
+        font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+        overflow: hidden;
+      }
+      #root {
+        width: 100vw;
+        height: 100vh;
+      }
+    </style>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/demo/main.tsx"></script>
+  </body>
+</html>

package/template/netlify.toml

@@ -0,0 +1,8 @@
+[build]
+  command = "npm run demo:build"
+  publish = "demo-dist"
+
+[[redirects]]
+  from = "/*"
+  to = "/demo.html"
+  status = 200

package/template/package.json.ejs

@@ -0,0 +1,26 @@
+{
+  "name": "<%= projectName %>",
+  "version": "1.0.0",
+  "description": "<%= appName %> Analytics Video",
+  "scripts": {
+    "dev": "remotion studio",
+    "build": "remotion bundle",
+    "render": "remotion render MyComp out.mp4",
+    "upgrade": "remotion upgrade",
+    "demo": "vite --config vite.demo.config.ts",
+    "demo:build": "vite build --config vite.demo.config.ts"
+  },
+  "dependencies": {
+    "@remotion/cli": "^4.0.0",
+    "@remotion/player": "^4.0.0",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
+    "remotion": "^4.0.0"
+  },
+  "devDependencies": {
+    "@types/react": "^18.2.0",
+    "@vitejs/plugin-react": "^4.2.1",
+    "typescript": "^5.0.0",
+    "vite": "^5.0.0"
+  }
+}

package/template/remotion.config.ts

@@ -0,0 +1,4 @@
+import { Config } from "@remotion/cli/config";
+
+Config.setVideoImageFormat("jpeg");
+Config.setOverwriteOutput(true);