ShotFlow

AI-powered screenplay-to-production planning platform for filmmakers.

From script to production packet in one focused workspace.

---

Overview

ShotFlow is an AI-powered screenplay-to-production planning platform for filmmakers, assistant directors, producers, and creative teams who need to turn an existing script into a practical production packet.

It exists to reduce the gap between creative intention and on-set execution. Instead of moving through a scattered workflow of notes, spreadsheets, and disconnected documents, ShotFlow keeps the script, analysis, breakdowns, and exportable planning materials in one place.

The result is a focused workspace that helps teams move from screenplay to production-ready planning faster, with less manual overhead and more creative clarity.

---

Problem Statement

Screenplay pre-production is still too manual for many small teams.

• Script breakdowns are often assembled by hand.
• Production notes are scattered across documents, chats, and spreadsheets.
• Creative intent gets lost when teams move from reading a screenplay to planning a shoot.
• Translating imagination into production-ready documents takes time and coordination.
• The workflow is fragmented between writing, analysis, scene planning, and exportable handoff materials.

For filmmakers and assistant directors, that friction slows momentum and makes it harder to get from idea to execution with confidence.

---

Solution

ShotFlow solves that problem with a single end-to-end workflow:

Screenplay
   ↓
AI Analysis
   ↓
Scene Breakdown
   ↓
Characters
   ↓
Shot List
   ↓
Camera Suggestions
   ↓
Lighting Suggestions
   ↓
Storyboard Prompts
   ↓
Production-ready Export

The application turns a screenplay into structured production planning assets that are easier to scan, review, and share with a crew.

---

Challenge Theme

Creative Industries

ShotFlow aligns with the IBM SkillsBuild AI Builders Challenge theme because it uses AI as a creative partner rather than a novelty layer.

It supports:

• AI-assisted filmmaking
• Storytelling tools for creative teams
• Workflow automation for pre-production
• Bridging imagination and execution
• Structured planning for production handoff

The product is built for the creative process itself, not just for generating content.

---

Features

Feature	What it provides
Project Management	Organize screenplay projects in a single workspace.
Screenplay Editor	Write or paste scripts in a focused, autosaving editor.
AI Scene Analysis	Convert screenplay text into structured production planning data.
Executive Summary	Get a concise overview of the screenplay and planning considerations.
Character Extraction	Surface character roles and key actions for quick reference.
Scene Breakdown	Review each scene with location, timing, summary, and notes.
Shot List Generation	Turn scenes into actionable shot ideas.
Camera Planning	Receive practical camera guidance for each scene.
Lighting Planning	Get lighting suggestions tailored to the material.
Storyboard Prompt Generation	Produce visual prompts for storyboarding.
PDF Export	Export a clean production packet for crews and collaborators.
Responsive UI	Use the product comfortably on desktop and smaller screens.
Authentication	Secure access with Clerk.
Cloud Database	Persist projects and analyses in PostgreSQL.

---

Architecture

flowchart TD
  A[Frontend<br/>Next.js + React + Tailwind CSS] --> B[Backend<br/>FastAPI]
  B --> C[AI Layer<br/>IBM Granite analysis pipeline]
  B --> D[Database<br/>PostgreSQL]

Loading

---

AI Approach

AI is central to ShotFlow because the product’s job is to interpret screenplay text and transform it into useful production planning structure.

The application uses AI to:

• understand screenplay context and scene structure
• extract characters and scene-level production information
• generate practical shot, camera, and lighting guidance
• create storyboard prompts from the script
• produce a consistent planning output that can be reviewed and exported

Technically, the AI layer sits inside the analysis pipeline and returns structured planning data that the rest of the application renders into the workspace and PDF export. The goal is not to replace production judgment, but to reduce the manual work needed to prepare for it.

---

How IBM Bob Was Used

IBM Bob was the primary development tool used throughout the project.

It assisted with:

• architecture planning
• frontend implementation
• backend development
• UI refinement
• debugging
• code generation
• iterative development

IBM Bob helped move the project from concept to a polished, working application while keeping the implementation aligned with the product goals.

---

Tech Stack

Layer	Technology
Frontend	Next.js, React, TypeScript, Tailwind CSS
Backend	FastAPI, Python
Authentication	Clerk
Database	PostgreSQL
AI	IBM Granite / WatsonX
Deployment	Vercel for frontend, Railway for backend and database

---

Installation

git clone https://github.com/logitechsoumili/shotflow.git
cd shotflow

Frontend

cd frontend
cp .env.example .env.local
npm install
npm run dev

Backend

cd backend
cp .env.example .env
python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt
uvicorn app.main:app --reload

The frontend runs at http://localhost:3000 and the backend runs at http://localhost:8000.

---

Environment Variables

Frontend

Variable	Required	Purpose
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY	Yes	Clerk publishable key for authentication.
CLERK_SECRET_KEY	Yes	Clerk secret key used by server-side auth.
NEXT_PUBLIC_CLERK_SIGN_IN_URL	Yes	Sign-in route.
NEXT_PUBLIC_CLERK_SIGN_UP_URL	Yes	Sign-up route.
NEXT_PUBLIC_CLERK_AFTER_SIGN_IN_URL	Yes	Redirect after sign-in.
NEXT_PUBLIC_CLERK_AFTER_SIGN_UP_URL	Yes	Redirect after sign-up.
NEXT_PUBLIC_API_BASE_URL	Yes	Backend API base URL.

Backend

Variable	Required	Purpose
DATABASE_URL	Yes	PostgreSQL connection string.
CLERK_SECRET_KEY	Yes	Server-side Clerk integration.
GEMINI_API_KEY	Yes	AI provider key used for screenplay analysis.
GEMINI_MODEL	Yes	AI model name used by the analysis service.

---

Screenshots

Landing Page

Dashboard

Editor

Production Plan

Storyboard

---

Future Improvements

• Add richer project-level collaboration tools.
• Expand export formats for crew-specific packets.
• Add version history for screenplay drafts.
• Support more detailed production breakdown exports.
• Improve analysis feedback during long screenplay imports.

---

Acknowledgements

• IBM SkillsBuild AI Builders Challenge
• IBM Bob
• The open-source community