Skip to content

FEATURES.md

Latest commit

 

History

History
338 lines (275 loc) · 9.44 KB

FEATURES.md

File metadata and controls

338 lines (275 loc) · 9.44 KB
Raw

Features & Design — Cradle AI MVP

Complete breakdown of MVP features, UI/UX design system, and future roadmap.

🎯 MVP Features (12 Day 6 Hours)

✅ Core Detection (Phase 1)

Feature Status Tech Notes
Video Upload ✅ HTML5 Drag & Drop Max 500MB, MP4/MOV/AVI
Crying Detection ✅ librosa (pitch/energy/timbre) + GPT-5.6 vision Acoustic analysis, not phrase transcription
Movement Detection ✅ OpenCV Frame Diff Pixel change detection
Adult Detection ✅ YOLOv8 + GPT-5.6 Vision Person detection, cooldown-limited events
Sleep State ✅ Heuristic (Quiet + no movement)

✅ Analysis & Output (Phase 2)

Feature Status Tech Notes
Timeline Generation ✅ Detection Engine Chronological events
AI Summary ✅ GPT-5.6, deterministic fallback Natural language narrative
Sleep Quality Score ✅ Scoring Algorithm 0-100 value
Statistics Dashboard ✅ Vanilla JS Total sleep, episodes, visits
Color-coded Events ✅ CSS 4 event types, 4 colors
Night History ✅ /api/videos Past uploads, click through to reload any analysis

Configuration & Rules (Phase 3)

/api/alert-rules exists in the backend but is intentionally not exposed in the UI: this product analyzes footage after the fact, so per-rule "notify me" toggles implied a live-monitoring capability the app doesn't have. Removed from the dashboard rather than ship a control that does nothing.

🎨 Design System

Color Palette (Night Theme)

Background Layers:

--ink-950: #060B1A       Deep space
--ink-900: #0B1330       Night sky
--ink-800: #121C43       Card background
--ink-700: #1B2A5C       Hover state

Sky & Accent:

--dusk-500: #35529E      Primary blue
--sky-400:  #6FA8DC      Secondary blue
--baby-300: #A9D8F5      Light accent
--baby-100: #E4F3FC      Text/light UI
--white:    #FBFDFF      Pure white

Event Colors:

--glow-cry:    #F5B8C4   Pink (crying)
--glow-move:   #C9B6F2   Purple (movement)
--glow-adult:  #8FE3C0   Teal (adult)
--glow-sleep:  #6FA8DC   Blue (sleep)

Typography

Fraunces (serif)
- Font-weight: 500–600
- Use: Headings, brand, numbers
- Example: "78/100" sleep score

Inter (sans-serif)
- Font-weight: 400–700
- Use: Body copy, UI text
- Example: "Baby fell asleep"

JetBrains Mono (monospace)
- Font-weight: 400–500
- Use: Timestamps, labels, data
- Example: "20:05" timeline mark

Component Styles

Cards/Panels

background: var(--ink-800);
border: 1px solid var(--line);  /* rgba(169,216,245,0.14) */
border-radius: 20px;
backdrop-filter: blur(10px);

Buttons

/* Primary (Baby Blue) */
background: var(--baby-300);
color: var(--ink-950);
border-radius: 100px;
padding: 11px 20px;

/* Secondary (Transparent) */
background: transparent;
color: var(--baby-300);
border: 1px solid var(--line);

Timeline Dots

width: 12px;
height: 12px;
box-shadow: 0 0 0 4px var(--ink-800), 0 0 12px currentColor;

📐 Layout Grid

Desktop (1240px max-width):

Header [Logo] [Nav] [Status]
─────────────────────────────────
Hero [Left 1.15fr] [Right 0.85fr]
─────────────────────────────────
Stats [4 columns × 1fr]
─────────────────────────────────
Main Grid
  [Timeline 1.3fr] [Insights 1fr]
    ├─ Night Timeline   ├─ Summary
    └─ Events           └─ Alert Cfg

Mobile (<880px):

Hero → 1 column
Stats → 2 columns
Main Grid → 1 column (stack)
Nav → hidden

✨ Animations

Starfield (Background)

Galaxies — Rotating conic gradients

--duration: 95s–140s
--effect: Subtle rotation, low opacity
--respect: prefers-reduced-motion

Stars — Twinkling opacity

--small: 0.35–0.75 opacity, 4.5s cycle
--mid: 0.25–0.6 opacity, 6s cycle
--big: 0.45–0.9 opacity, 3.2s cycle

Interactive

Dropzone Hover

--border: rgba(169,216,245,0.35) → var(--baby-300)
--background: Darken by 20%
--transition: 0.2s ease

Button Hover

--transform: translateY(-1px)
--shadow: (optional) 0 4px 12px rgba(111,168,220,0.2)

Threshold Slider

--accent-color: var(--baby-300)
--track: rgba(255,255,255,0.1)
--thumb: var(--baby-300)

📱 Responsive Breakpoints

Breakpoint Use Case
1240px Max container width
880px Tablet (hero/grid switch to 1-col)
375px Mobile (very compact)

Media Query:

@media (max-width: 880px) {
  .hero, .main-grid { grid-template-columns: 1fr; }
  .stats { grid-template-columns: repeat(2, 1fr); }
  nav { display: none; }
}

🚀 Future Features (Post-MVP)

Phase 2 — Intelligence

  • PDF export of nightly report
  • Confidence score display per event
  • Multi-night trend analysis
  • AI sleep coaching recommendations
  • Parent notifications (email, SMS)

Phase 3 — Platform

  • Mobile app (React Native)
  • Caregiver collaboration (share access)
  • Video playback with timeline sync
  • Machine learning model training (fine-tuning)
  • White-label dashboard for clinics

Phase 4 — Premium

  • Real-time alerts via push notifications
  • Cloud video storage (Cloudinary)
  • Integration with smart home (Alexa, Google)
  • Sleep pattern AI (circadian rhythm analysis)
  • Pediatrician insights marketplace

🎬 User Flow

┌─────────────────────────────┐
│  User visits dashboard      │
│  (Night sky loads)          │
└────────────┬────────────────┘
             ↓
┌─────────────────────────────┐
│  User drags video or clicks │
│  "Choose file"              │
└────────────┬────────────────┘
             ↓
┌─────────────────────────────┐
│  API uploads video          │
│  Shows progress %           │
│  Starts bg processing       │
└────────────┬────────────────┘
             ↓
┌─────────────────────────────┐
│  Frontend polls status      │
│  Shows "Analyzing..."       │
│  with loading animation     │
└────────────┬────────────────┘
             ↓ (Backend processing)
  ┌──────────────────────────┐
  │ Extract frames (OpenCV)  │
  │ Detect movement          │
  │ Send to GPT-5.6 Vision   │
  │ Extract & analyze audio  │
  │ Generate summary         │
  │ Save to SQLite           │
  └──────────────┬───────────┘
                 ↓
┌─────────────────────────────┐
│  Frontend receives results  │
│  (JSON timeline + summary)  │
└────────────┬────────────────┘
             ↓
┌─────────────────────────────┐
│  Display Dashboard:         │
│  • Stats cards (4 types)    │
│  • Timeline (events)        │
│  • AI summary (prose)       │
│  • Sleep quality score      │
│  • Recent nights (history)  │
└────────────┬────────────────┘
             ↓
┌─────────────────────────────┐
│  User clicks a past night   │
│  (fetches /api/analysis/id) │
└─────────────────────────────┘

🎯 MVP Success Criteria

✅ Code Quality

  • Clean REST API boundary
  • No API keys in repo
  • README + documentation
  • Setup takes <5 min

✅ Functionality

  • Video uploads without errors
  • Processing completes in <2 min for demo videos
  • Timeline + summary visible
  • No console errors

✅ Design

  • Beautiful night theme
  • Starfield animations smooth
  • Mobile responsive
  • Loading states visible

✅ Deployment

  • Backend running on Render (or similar)
  • Frontend on Vercel (or similar)
  • Both accessible from DevPost link
  • API keys not exposed

📊 Performance Targets

Metric Target Notes
Page Load <2s Including animations
Video Upload <30s For 100MB file
Processing 30s–2min Depends on video length
API Response <500ms Typical GET/POST
Timeline Render <100ms For 20 events

🔐 Security Notes

  • ✅ API keys in .env (never committed)
  • ✅ CORS configured (no open wildcards)
  • ✅ File upload validation (size + format)
  • ✅ SQLite (fine for MVP; upgrade for production)
  • 🔄 Auth not implemented (add later)

Great design starts with clear thinking. You've got this! 🌙