# lynh-drill/flowkit architecture

> Architecture diagram of the GitHub repository lynh-drill/flowkit, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/lynh-drill/flowkit
- Repository: https://github.com/lynh-drill/flowkit

## Overview

FLOW KIT turns story projects into AI-generated, narrated videos through a FastAPI agent, a signed-in Chrome Flow bridge, background generation and review services, and a persistent project pipeline. The dashboard drives and monitors that workflow, while the extension supplies browser-authenticated Flow requests. README capabilities include reference and scene images, video modes, upscale, TTS, final assembly, thumbnails, and YouTube-ready metadata; several internals are represented at their documented subsystem path because their source was not sampled. Edges follow sampled calls or explicit README descriptions.

Main entry points: [`agent/worker/processor.py`](https://github.com/lynh-drill/flowkit/blob/main/agent/worker/processor.py) (Request worker), [`agent/db/crud.py`](https://github.com/lynh-drill/flowkit/blob/main/agent/db/crud.py) (Project data access), [`agent/main.py`](https://github.com/lynh-drill/flowkit/blob/main/agent/main.py) (FastAPI server), [`extension/background.js`](https://github.com/lynh-drill/flowkit/blob/main/extension/background.js) (Chrome browser bridge)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Dashboard"]
  node_dashboard["Ops dashboard<br/>[App.tsx]"]
  node_pipeline_view["Scene pipeline<br/>[PipelineView.tsx]"]
  node_dash_api["Dashboard API client<br/>[client.ts]"]
  node_dash_ws["Dashboard live events<br/>[useWebSocket.ts]"]
end

subgraph group_api["Agent API"]
  node_api_app["FastAPI server<br/>[main.py]"]
  node_api_projects["Project endpoints<br/>[projects.py]"]
  node_api_scenes["Scene endpoints<br/>[scenes.py]"]
  node_api_requests["Generation requests<br/>[requests.py]"]
  node_api_reviews["Review endpoints<br/>[reviews.py]"]
  node_dashboard_ws_endpoint["Dashboard WebSocket<br/>[main.py]"]
  node_event_bus["Event bus<br/>[event_bus.py]"]
end

subgraph group_pipeline["Generation Pipeline"]
  node_worker["Request worker<br/>[processor.py]"]
  node_flow_batch["Batch orchestration<br/>[flow_batch.py]"]
  node_scene_chain["Scene chaining<br/>[scene_chain.py]"]
  node_tts["Narration TTS<br/>[tts.py]"]
  node_postprocess["Video assembly<br/>[post_process.py]"]
  node_reviewer["AI video review<br/>[video_reviewer.py]"]
  node_sdk_result["Result handling<br/>[result_handler.py]"]
end

subgraph group_storage["Project State"]
  node_db[("SQLite project state<br/>[schema.py]")]
  node_crud["Project data access<br/>[crud.py]"]
end

subgraph group_bridge["Flow Integration"]
  node_flow_client["Flow client<br/>[flow_client.py]"]
  node_extension["Chrome browser bridge<br/>[background.js]"]
end

node_creator(("Project creator"))
node_google_flow{{"Google Flow"}}
node_youtube{{"YouTube publishing"}}
node_ai_review_model{{"Claude Vision"}}

node_creator -->|"drives"| node_dashboard
node_dashboard -->|"renders"| node_pipeline_view
node_pipeline_view -->|"fetches data"| node_dash_api
node_dash_api -->|"HTTP requests"| node_api_app
node_api_app -->|"routes"| node_api_projects
node_api_app -->|"routes"| node_api_scenes
node_api_app -->|"routes"| node_api_requests
node_api_app -->|"routes"| node_api_reviews
node_api_projects -->|"reads/writes"| node_crud
node_api_scenes -->|"reads/writes"| node_crud
node_api_requests -->|"queues"| node_crud
node_crud -->|"reads/writes"| node_db
node_api_requests -->|"dispatches"| node_worker
node_worker -->|"loads jobs"| node_crud
node_worker -->|"executes generation"| node_flow_batch
node_worker -->|"applies results"| node_sdk_result
node_flow_batch -->|"requests media"| node_flow_client
node_flow_batch -->|"chains scenes"| node_scene_chain
node_scene_chain -->|"requests generation"| node_flow_client
node_sdk_result -->|"updates assets"| node_crud
node_flow_client -->|"dispatches RPC"| node_extension
node_extension -->|"executes RPC"| node_google_flow
node_google_flow -->|"returns media"| node_extension
node_extension -->|"delivers response"| node_flow_client
node_worker -.->|"generates narration"| node_tts
node_worker -.->|"assembles video"| node_postprocess
node_postprocess -.->|"publishes output"| node_youtube
node_api_reviews -->|"reviews scenes"| node_reviewer
node_reviewer -->|"analyzes frames"| node_ai_review_model
node_dashboard -->|"subscribes"| node_dash_ws
node_dash_ws -->|"connects"| node_dashboard_ws_endpoint
node_dashboard_ws_endpoint -->|"subscribes"| node_event_bus
node_worker -->|"emits updates"| node_event_bus
node_event_bus -->|"streams events"| node_dashboard_ws_endpoint

click node_dashboard "https://github.com/lynh-drill/flowkit/blob/main/dashboard/src/App.tsx"
click node_pipeline_view "https://github.com/lynh-drill/flowkit/blob/main/dashboard/src/components/pipeline/PipelineView.tsx"
click node_dash_api "https://github.com/lynh-drill/flowkit/blob/main/dashboard/src/api/client.ts"
click node_dash_ws "https://github.com/lynh-drill/flowkit/blob/main/dashboard/src/api/useWebSocket.ts"
click node_api_app "https://github.com/lynh-drill/flowkit/blob/main/agent/main.py"
click node_api_projects "https://github.com/lynh-drill/flowkit/blob/main/agent/api/projects.py"
click node_api_scenes "https://github.com/lynh-drill/flowkit/blob/main/agent/api/scenes.py"
click node_api_requests "https://github.com/lynh-drill/flowkit/blob/main/agent/api/requests.py"
click node_api_reviews "https://github.com/lynh-drill/flowkit/blob/main/agent/api/reviews.py"
click node_worker "https://github.com/lynh-drill/flowkit/blob/main/agent/worker/processor.py"
click node_flow_batch "https://github.com/lynh-drill/flowkit/blob/main/agent/services/flow_batch.py"
click node_scene_chain "https://github.com/lynh-drill/flowkit/blob/main/agent/services/scene_chain.py"
click node_tts "https://github.com/lynh-drill/flowkit/blob/main/agent/services/tts.py"
click node_postprocess "https://github.com/lynh-drill/flowkit/blob/main/agent/services/post_process.py"
click node_reviewer "https://github.com/lynh-drill/flowkit/blob/main/agent/services/video_reviewer.py"
click node_sdk_result "https://github.com/lynh-drill/flowkit/blob/main/agent/sdk/services/result_handler.py"
click node_db "https://github.com/lynh-drill/flowkit/blob/main/agent/db/schema.py"
click node_crud "https://github.com/lynh-drill/flowkit/blob/main/agent/db/crud.py"
click node_flow_client "https://github.com/lynh-drill/flowkit/blob/main/agent/services/flow_client.py"
click node_extension "https://github.com/lynh-drill/flowkit/blob/main/extension/background.js"
click node_dashboard_ws_endpoint "https://github.com/lynh-drill/flowkit/blob/main/agent/main.py"
click node_event_bus "https://github.com/lynh-drill/flowkit/blob/main/agent/services/event_bus.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_dashboard,node_pipeline_view,node_dash_api,node_dash_ws toneBlue
class node_api_app,node_api_projects,node_api_scenes,node_api_requests,node_api_reviews,node_dashboard_ws_endpoint,node_event_bus toneAmber
class node_worker,node_flow_batch,node_scene_chain,node_tts,node_postprocess,node_reviewer,node_sdk_result toneMint
class node_db,node_crud toneRose
class node_flow_client,node_extension,node_creator,node_google_flow,node_youtube,node_ai_review_model toneIndigo
```

## Components

### Dashboard

- [Ops dashboard](https://github.com/lynh-drill/flowkit/blob/main/dashboard/src/App.tsx): `dashboard/src/App.tsx`
- [Scene pipeline](https://github.com/lynh-drill/flowkit/blob/main/dashboard/src/components/pipeline/PipelineView.tsx): `dashboard/src/components/pipeline/PipelineView.tsx`
- [Dashboard API client](https://github.com/lynh-drill/flowkit/blob/main/dashboard/src/api/client.ts): `dashboard/src/api/client.ts`
- [Dashboard live events](https://github.com/lynh-drill/flowkit/blob/main/dashboard/src/api/useWebSocket.ts): `dashboard/src/api/useWebSocket.ts`

### Agent API

- [FastAPI server](https://github.com/lynh-drill/flowkit/blob/main/agent/main.py): `agent/main.py`
- [Project endpoints](https://github.com/lynh-drill/flowkit/blob/main/agent/api/projects.py): `agent/api/projects.py`
- [Scene endpoints](https://github.com/lynh-drill/flowkit/blob/main/agent/api/scenes.py): `agent/api/scenes.py`
- [Generation requests](https://github.com/lynh-drill/flowkit/blob/main/agent/api/requests.py): `agent/api/requests.py`
- [Review endpoints](https://github.com/lynh-drill/flowkit/blob/main/agent/api/reviews.py): `agent/api/reviews.py`
- [Dashboard WebSocket](https://github.com/lynh-drill/flowkit/blob/main/agent/main.py): `agent/main.py`
- [Event bus](https://github.com/lynh-drill/flowkit/blob/main/agent/services/event_bus.py): `agent/services/event_bus.py`

### Generation Pipeline

- [Request worker](https://github.com/lynh-drill/flowkit/blob/main/agent/worker/processor.py): `agent/worker/processor.py`
- [Batch orchestration](https://github.com/lynh-drill/flowkit/blob/main/agent/services/flow_batch.py): `agent/services/flow_batch.py`
- [Scene chaining](https://github.com/lynh-drill/flowkit/blob/main/agent/services/scene_chain.py): `agent/services/scene_chain.py`
- [Narration TTS](https://github.com/lynh-drill/flowkit/blob/main/agent/services/tts.py): `agent/services/tts.py`
- [Video assembly](https://github.com/lynh-drill/flowkit/blob/main/agent/services/post_process.py): `agent/services/post_process.py`
- [AI video review](https://github.com/lynh-drill/flowkit/blob/main/agent/services/video_reviewer.py): `agent/services/video_reviewer.py`
- [Result handling](https://github.com/lynh-drill/flowkit/blob/main/agent/sdk/services/result_handler.py): `agent/sdk/services/result_handler.py`

### Project State

- [SQLite project state](https://github.com/lynh-drill/flowkit/blob/main/agent/db/schema.py): `agent/db/schema.py`
- [Project data access](https://github.com/lynh-drill/flowkit/blob/main/agent/db/crud.py): `agent/db/crud.py`

### Flow Integration

- [Flow client](https://github.com/lynh-drill/flowkit/blob/main/agent/services/flow_client.py): `agent/services/flow_client.py`
- [Chrome browser bridge](https://github.com/lynh-drill/flowkit/blob/main/extension/background.js): `extension/background.js`

### Other components

- **Project creator**
- **Google Flow**
- **YouTube publishing**
- **Claude Vision**

## Connections

- Project creator → Ops dashboard: drives
- Ops dashboard → Scene pipeline: renders
- Scene pipeline → Dashboard API client: fetches data
- Dashboard API client → FastAPI server: HTTP requests
- FastAPI server → Project endpoints: routes
- FastAPI server → Scene endpoints: routes
- FastAPI server → Generation requests: routes
- FastAPI server → Review endpoints: routes
- Project endpoints → Project data access: reads/writes
- Scene endpoints → Project data access: reads/writes
- Generation requests → Project data access: queues
- Project data access → SQLite project state: reads/writes
- Generation requests → Request worker: dispatches
- Request worker → Project data access: loads jobs
- Request worker → Batch orchestration: executes generation
- Request worker → Result handling: applies results
- Batch orchestration → Flow client: requests media
- Batch orchestration → Scene chaining: chains scenes
- Scene chaining → Flow client: requests generation
- Result handling → Project data access: updates assets
- Flow client → Chrome browser bridge: dispatches RPC
- Chrome browser bridge → Google Flow: executes RPC
- Google Flow → Chrome browser bridge: returns media
- Chrome browser bridge → Flow client: delivers response
- Request worker → Narration TTS: generates narration
- Request worker → Video assembly: assembles video
- Video assembly → YouTube publishing: publishes output
- Review endpoints → AI video review: reviews scenes
- AI video review → Claude Vision: analyzes frames
- Ops dashboard → Dashboard live events: subscribes
- Dashboard live events → Dashboard WebSocket: connects
- Dashboard WebSocket → Event bus: subscribes
- Request worker → Event bus: emits updates
- Event bus → Dashboard WebSocket: streams events