FrameFlow AI Comic Studio
FrameFlow is an end-to-end AI comic drama production workspace. It includes project and episode management, reusable character and scene assets, AI script and storyboard jobs, shot production, TTS/video/lipsync processing, FFmpeg rendering with immutable source manifests and SRT/VTT sidecars, immutable versions, review workflows, user-scoped persistent notifications with authenticated realtime updates, email-backed workspace invitations, delivery, usage quotas, persisted administrator-only AI provider connection verification, Prometheus metrics, infrastructure capacity and backup-age alerts, and Alertmanager webhook notifications.
Local development
Requirements: Node.js 24+, Docker Compose, and FFmpeg.
cp .env.example .env
npm ci
npm run infra:up
npm run db:migrate
npm run db:seed
npm run dev
The web app runs at http://127.0.0.1:5173 by default. The repository's current preview setup may use port 4173 instead. The API readiness endpoint is http://127.0.0.1:8787/health/ready; it also verifies that the generation worker heartbeat is current.
Cloud jobs require valid OpenAI and Replicate configuration. Missing provider credentials cause explicit failed jobs; the system does not substitute generated demo output.
Publishing to Douyin, Kuaishou, Bilibili, and Xiaohongshu requires a separately deployed connector that owns each platform's application credentials and API-specific behavior. FrameFlow stores encrypted channel tokens, schedules delivery jobs, and verifies signed status callbacks. The connector HTTP contract, environment variables, and live acceptance checklist are documented in docs/deployment.md.
Verification
npm run build:all
npm test
The GitHub Actions workflow in .github/workflows/ci.yml runs migrations, the complete web and server test suites, a real three-store backup and isolated restore rehearsal, production builds, a production-dependency audit, production Compose validation, container image builds, and both the accepting and rejecting sides of the production configuration gate. Its production values are synthetic and generated only inside the runner; no deploy credentials are stored in the workflow.
After deployment, npm run smoke:production runs an authenticated, provider-free production path through persistence, object upload/download, BullMQ, FFmpeg rendering, subtitle sidecars, review approval, audit logs, and secure download delivery. The default mode reports AI provider configuration without starting billable jobs. A separate --include-ai mode performs live OpenAI and Replicate generation only after an exact billable-charge acknowledgement, complete seven-workflow readiness, and a 700-credit preflight. Required environment variables, provider-specific parameter handling, and data-retention behavior are documented in the deployment guide.
Production deployment, TLS/media routing, monitoring, controlled firing/resolved Alertmanager webhook acceptance, read-only Stripe resource verification, backup, restore, and upgrade procedures are documented in docs/deployment.md. The production Compose stack includes a fail-fast configuration gate before migrations; it rejects placeholder secrets, unsafe public endpoints, and incomplete provider or billing configuration without printing secret values. Production backups are checksum-protected and pass a standalone read-only archive verifier before success metrics are published. A separate restore-rehearsal command restores all three data stores into randomly named, labeled Docker resources with no published ports, verifies their contents, publishes rehearsal metrics, and removes the isolated resources. Supplied hardened systemd timers run a verified backup daily and require a fresh successful backup before the monthly restore rehearsal; the scheduler refuses to use a missing or unexpected backup mount.