crisng95/flowboard

Flowboard – A Local‑Only, Graph‑Based Workspace for Google Flow Media Generation

What it is – Flowboard is a desktop‑style web app that lets a single user design AI‑generated media pipelines on an infinite canvas. Nodes represent assets (characters, products), image compositions, and video renders. The app talks to Google Flow (Veo 3.1 i2v / GEM_PIX_2) through a Chrome MV3 extension, and it uses a locally‑installed LLM CLI (Claude Code, Gemini via agy, or OpenAI Codex) for vision, auto‑prompting and planning. All state lives in a local SQLite database; no cloud service is required beyond the paid Google Flow account.

---

Why it exists

• E‑commerce video creation is repetitive – the same model and product appear in many scenes.
• Flowboard treats the whole campaign as a directed graph so each reference (character, product) is uploaded once and reused automatically.
• Auto‑prompting pulls descriptions from the configured LLM CLI, generating context‑aware prompts for each downstream node.

---

Core concepts & workflow

Concept	Role	How you use it
Ref nodes (Character, Visual asset)	Anchors that store a single image and an aiBrief (LLM‑generated description).	Upload or generate once; downstream nodes read the brief automatically.
Image nodes	Compose a scene from one or more refs.	Connect refs, click Generate (or press Enter). The app sends the upstream media IDs to Google Flow and asks the LLM CLI to synthesize N pose‑distinct prompts in a single call.
Video nodes	Turn an image (or its variants) into a short clip via Veo i2v.	Connect an Image node, choose Static or Dynamic camera, tick which variants to use. One Flow batchexecute call creates a video per selected variant.
Auto‑prompt	LLM‑driven prompt generation that is aware of scene context.	The LLM reads upstream aiBriefs, decides on motion vocab (studio, street, café, outdoor) and returns a fashion‑editorial style prompt for each variant.

---

Architecture at a glance

Chrome MV3 extension  ←→  FastAPI agent (127.0.0.1:8434)
   │                     │   ├─ SQLite storage (boards, nodes, assets)
   │                     │   └─ Worker queue that shells out to the LLM CLI
   ▼                     ▼
React‑Flow canvas (Vite, TS)   ←→   Google Flow (batchexecute RPC)

• Frontend – React 18 + React‑Flow 12 renders the infinite‑canvas UI.
• Agent – FastAPI 0.115 runs locally, stores the graph, and mediates all calls to Google Flow via the extension.
• Extension – Loaded on flow.google.com; it injects a content script that signs each request with the page’s session cookie, token and a one‑time reCAPTCHA, then forwards the raw payload to the agent over a WebSocket.
• LLM CLI – Any of the supported CLIs (Claude Code, Gemini agy, OpenAI Codex) must be on the system PATH. The agent invokes it for vision (image description) and for the auto‑prompt planner.

---

Getting started (quick summary)

1. Prerequisites – Python 3.11+, Node 20+, Chrome, a paid Google Flow Pro or Ultra plan, and one of the LLM CLIs installed.
2. Clone & install – make install (or use uv/venv + npm install).
3. Load the Chrome extension – chrome://extensions/ → Load unpacked → extension/.
4. Open a signed‑in Flow tab – the extension badge turns green when it can talk to the agent.
5. Configure – copy .env.example to .env and set FLOWBOARD_FLOW_PROJECT_ID to the UUID of a Flow project you created in the UI.
6. Run – make agent (FastAPI) and make frontend (Vite). Open http://localhost:5173.
7. Create a board – add Character and Visual‑Asset nodes, connect them to Image nodes, then to Video nodes. Click Generate at each step; the LLM CLI builds prompts, the extension forwards the request to Google Flow, and results appear on the canvas.

---

Notable features

• Infinite canvas – pan/zoom without limits; every node is draggable.
• Variant batches – request N image variants or N videos in a single Flow call.
• Reusable assets – a character or product uploaded once can feed dozens of scenes.
• Local‑only storage – all boards, media files and history are kept in a SQLite DB under storage/.
• Provider‑agnostic LLM – swap Claude, Gemini or Codex via the Settings UI; the app never contacts a cloud LLM endpoint directly.
• Tests – 517 passing pytest suite (as of the README).

---

Who should consider it

• Creators of e‑commerce or fashion video ads who already have a Google Flow Pro/Ultra subscription and want a repeatable, graph‑driven workflow.
• Teams that prefer local‑only data (no cloud storage of assets) but still need the power of Google’s Veo image‑to‑video models.
• Developers comfortable with Python, Node, and Chrome extensions who want to extend the pipeline (e.g., add custom LLM prompts or extra node types).

---

Limitations

• Chrome required – the extension must run in a live flow.google.com tab; headless operation is not supported.
• Paid Flow plan – free or trial accounts cannot generate videos because Veo 3.1 i2v is gated.
• Single‑user, local only – no multi‑user collaboration or cloud sync.

---

License

MIT – see the LICENSE file in the repository.