StoryBoard AI Music Video Storyboarder

The StoryBoard AI Music Video Storyboarder is a production-ready application with project management, asset management, AI-powered storyboard generation, and MediaBunny Studio editing/export tooling.

Current Status

• Core storyboard, asset, and AI generation flows are shipped.
• MediaBunny Studio is available at /projects/:projectId/mediabunny for all users in this deployment.
• MediaBunny currently supports per-source export workflows; single-file composed timeline export is in active roadmap execution (docs/mediabunny/MEDIABUNNY_NEXT_ROADMAP.md).
• Official MediaBunny docs live under docs/mediabunny/; historical planning docs are archived under docs/_legacy/mediabunny/.

Run Locally

Prerequisites: Node.js 22 LTS recommended (.nvmrc is set to 22)

1. Install dependencies: npm install
2. Copy .env.example → .env.local, set GEMINI_API_KEY and AI_GATEWAY_API_KEY, and review overrides in docs/CONFIGURATION.md.
3. Prepare the database:
   • npm run migrate to apply SQL migrations, or
   • npm run seed to apply migrations and load a sample project.
4. Start services in separate terminals:
   • npm run dev:server (Express API on port 4000)
   • npm run dev (Vite frontend on port 3333, proxying /api → 4000)
5. Visit http://localhost:3333; projects and generated assets are stored under data/.

Build & Typecheck

• Frontend build (Vite): npm run build or npm run build:web
• Server build (dist-server/): npm run build:server
• Build both: npm run build:all
• Frontend typecheck: npm run typecheck
• Server typecheck: npm run typecheck:server

Run the compiled server with npm run start:server once dist-server is generated.

Note: dist-server/ is a generated build artifact and is ignored by version control. Do not commit files from this folder.

Bundle analysis & CI guard

• Analyze bundles locally: npm run analyze (generates dist/stats.html treemap with gzip/brotli sizes; only included when ANALYZE is set in the script).
• CI size guard:
  • npm run ci:build — production build used by CI
  • npm run ci:check-bundle — checks gzip sizes and fails if limits are exceeded
  • Current limits (tweak in scripts/check-bundle-sizes.mjs): entry ≤ 200 kB gzip; each non-vendor app chunk ≤ 300 kB gzip.

Operational Scripts

• npm run check:db — verifies migrations and asset directory permissions.
• npm run maintain prune — removes orphaned asset references/files and prunes empty directories.
• npm run maintain export <projectId> [outputDir] — exports a project bundle (JSON + assets).
• npm run test:api — Vitest + Supertest smoke tests covering health/projects/scenes/chat/assets.

Deployment notes

• Build the frontend: npm run build
• Run the server: npm run start:server — serves API and dist/; assets under dist/assets/ are long-cached (Cache-Control: public, max-age=31536000, immutable), index.html is no-cache, and non-API routes fall back to index.html (SPA routing)
• Environment: set PORT, CORS_ORIGIN, GEMINI_API_KEY, and AI_GATEWAY_API_KEY for Grok video via Vercel Gateway (see docs/CONFIGURATION.md)
• CDN/reverse proxy (optional): you can host dist/ on a CDN and proxy /api to the Node server; ensure SPA 404 fallback to /index.html and respect the cache headers above.

Architecture

This application follows a feature-first architecture with clear module boundaries. See docs/ARCHITECTURE.md for detailed documentation.

Key Directories

• server/ — Express app, migrations, stores, and maintenance scripts.
• src/ — React UI, hooks, providers, and Gemini integrations (client-side).
  • src/features/ — Feature-first modules (app-shell, layout, library, scene, project, generation) with colocated components/hooks/state. See src/features/README.md.
  • src/components/ — Shared UI components used across features.
  • src/hooks/ — Shared React hooks.
  • src/services/ — Core services and dependency injection.
  • src/ui/ — Reusable UI primitives and icon pack.
  • src/utils/ — Shared utility functions.
  • src/config/ — Application-wide configuration.
  • src/types/ — Shared TypeScript types.
• data/ — SQLite database (storyboard.db) and generated asset hierarchy.

Module Boundaries

Critical Rule: Features don't import from other features. This ensures:

• Clear separation of concerns
• Independent testability
• No circular dependencies (verified with madge)

See docs/ARCHITECTURE.md for import rules and best practices.

See docs/CONFIGURATION.md for configuration details, docs/mediabunny/README.md for MediaBunny Studio docs, and docs/mediabunny/MEDIABUNNY_NEXT_ROADMAP.md for next MediaBunny milestones. Historical phase logs are archived in docs/_legacy/.

Key Principles:

• Respect existing design system (no new colors/styles)
• Integrate within existing UI/UX (no new top-level navigation)
• Maintain module boundaries (features don't import features)
• Test for regressions (all existing features must work)

See .kiro/steering/current-mission.md for detailed integration roadmap and .kiro/specs/legacy/gemini-api-enhancement/tasks.md for complete task breakdown.

Troubleshooting

Common Issues

Database not found or migration errors

# Reset the database completely
npm run db:reset

Port already in use

• Default ports: 3333 (frontend), 4000 (backend)
• Change backend port: set PORT in .env.local
• Vite will auto-increment if 3333 is taken

Environment validation errors

• Check your .env.local against .env.example
• Ensure GEMINI_API_KEY is set correctly
• Ensure AI_GATEWAY_API_KEY is set when using xai/grok-imagine-video
• Server will show specific validation errors at startup

better-sqlite3 binding errors (Could not locate the bindings file)

• Use Node 22 LTS (nvm use in this repo).
• Rebuild the native addon: npm rebuild better-sqlite3.
• Verify binding health: npm run check:sqlite.
• If it still fails, remove and reinstall dependencies: rm -rf node_modules package-lock.json && npm install (PowerShell: Remove-Item -Recurse -Force node_modules, package-lock.json).
• Do not share one node_modules directory between PowerShell and WSL runs; native binaries are platform-specific.

better-sqlite3 ABI mismatch (NODE_MODULE_VERSION ... compiled against a different Node.js version)

• You switched Node majors after install (for example, installed on Node 22 and ran on Node 24).
• Run npm run fix:sqlite to rebuild and verify bindings for the active Node runtime.
• If needed, do a clean reinstall in your current shell/runtime.

npm audit high vulnerabilities

• Run npm audit --json to see exact direct/transitive sources.
• This repo is configured to pass with zero known vulnerabilities on a clean install.
• If audit regresses after forced upgrades/downgrades, do a clean reinstall and recheck.

TypeScript errors in IDE

# Restart TypeScript server or run:
npm run typecheck

Pre-commit hook failures

• Fix TypeScript errors in staged files
• Run npm run typecheck to see all issues

Assets not loading

• Ensure data/ directory exists and is writable
• Check /api/health endpoint for disk space status
• Run npm run maintain prune to clean orphaned files

Getting Help

• Check existing documentation
• Review CONTRIBUTING.md for development setup
• Open an issue with reproduction steps