VisualStoryWriting - Moses Yebei

The Problem

Authors who want to edit narrative text by rearranging visual timelines must manually keep story events, character locations, and actions in sync. Maintaining that consistency is error‑prone and slows iterative writing or user‑study design.

What This Does

The repo implements a browser‑based editor that visualizes a story’s chronology, characters, and actions, then drives GPT‑4o prompts to rewrite the underlying text. Core UI lives in src/App.tsx and src/view/VisualWritingInterface.tsx, while the domain model lives in src/model/Model.tsx and related prompt files such as src/model/prompts/textExtractors/SentenceActionsExtractor.tsx. Study‑specific flows (e.g., baseline or reading tasks) are in src/study/StudyInterface.tsx and the data files under src/study/data/.

How It Is Wired

Execution starts from index.html, which loads the Vite bundle generated from src/main.tsx. main.tsx mounts <App /> (in src/App.tsx) onto the DOM. <App /> creates a Model instance (src/model/Model.tsx) and passes it to the VisualWritingInterface.

Model (src/model/Model.tsx) – the central hub (42 inbound imports, 9 outbound). It holds the story state, orchestrates prompt execution, and exposes methods used by UI components and study modules.
StudyModel (src/study/StudyModel.tsx) – secondary hub (19 inbound, 8 outbound) that wraps Model for experimental protocols.
Prompt extractors (e.g., SentenceActionsExtractor.tsx, EntitiesExtractor.tsx) are invoked by Model to turn text into visual elements; they call OpenAI via the generic BasePrompt utilities.
View components (src/view/*) render the timeline, entity nodes, and editors. They call back into Model for mutations, which then trigger GPT‑4o calls and update the UI.

Circular imports link Model.tsx, StudyModel.tsx, and HistoryModel.tsx, meaning each module both imports and is imported by the others. This inflates the blast radius: a change in any of these three ripples through 42 dependent modules. Deeply nested functions (up to 14 levels) appear in EntityNodeComponent.tsx and SentenceActionsExtractor.tsx, making the control flow hard to trace. Large data files (src/study/data/TextF.tsx, TextG.tsx) each exceed 650 lines, bundling many story variants in a single module.

How To Use It

# Clone the repo
git clone https://github.com/moses-y/VisualStoryWriting
cd VisualStoryWriting

# Install dependencies
npm install

# Run the development server
npm run dev

The UI prompts for an OpenAI API key; enter it in the launch dialog—no environment variable is required. The application runs entirely in the browser; no backend server or database is started.

Real‑World Use

A research team can embed this UI in a participant‑facing web app, load a story script via the src/study/data/ files, and run a controlled study where users reorder timeline nodes. Each reorder triggers a GPT‑4o prompt (through the BasePrompt utilities) that suggests textual edits, which are then displayed instantly in the text editor pane.

Code Health & Issues

HIGH – Import cycles – 24 modules, e.g., src/model/Model.tsx, src/study/StudyModel.tsx, src/model/HistoryModel.tsx.
HIGH – Hub modules – src/model/Model.tsx and src/study/StudyModel.tsx have the highest inbound import counts.
HIGH – Deep nesting – Up to 14‑level indentation in src/view/entityActionView/EntityNodeComponent.tsx and related files.
MED – High branching density – 47 branches across 144 lines in src/model/TextUtils.tsx, src/model/SlateUtils.tsx, src/view/locationView/LocationsEditor.tsx.
MED – Duplicated code – Repeated 6‑line block in src/study/BaselineInterface.tsx and src/view/TextEditor.tsx.
MED – Oversized files – src/study/data/TextF.tsx and src/study/data/TextG.tsx each contain >650 lines.

Health audit findings

HIGH – Pin third‑party GitHub Actions to a commit SHA (.github/workflows/deploy.yml).
HIGH – No test suite; 60 source files lack any test files.
MED – Declare least‑privilege GITHUB_TOKEN permissions (.github/workflows/deploy.yml).
MED – Enable Dependabot or Renovate for dependency updates.
MED – Add a dependency‑vulnerability scan step in CI.
MED – Move large video assets (public/videos/*.mp4) to Git LFS or external storage.
LOW – Set explicit timeout-minutes on workflow jobs.
LOW – Add conventional files (.editorconfig, .gitattributes, formatter config).

The Bottom Line

The project delivers a functional, GPT‑augmented visual story editor with a clear UI‑to‑model flow, but the core model is a large, highly coupled hub surrounded by import cycles and deep nesting, which raises maintenance risk. Adding automated tests, breaking the hub into smaller services, and addressing the listed CI and repository hygiene issues would make it safer for production or research use. Engineers comfortable with React, TypeScript, and prompt engineering will find the codebase usable after these improvements.

What the analyser found

Deployment readiness

5/7

Container image
CI pipeline
Lockfile committed
Test suite
README
License
No committed secrets

Composition

76 files

TSX55
JSON5
JavaScript3
TypeScript2
YAML1
Markdown1

ReactExpressTailwind

Module dependencies

The 10 most depended-upon modules of 60, from static import analysis. Red outline marks a module in an import cycle.

graph LR n0_src_model_Model["Model"] n1_src_study_StudyModel["StudyModel"] n2_src_model_LayoutUtils["LayoutUtils"] n3_del_prompts_utils_BasePrompt["BasePrompt"] n4_ors_SentenceActionsExtractor["SentenceActionsExtractor"] n5_src_model_HistoryModel["HistoryModel"] n6_xtExtractors_VisualRefresher["VisualRefresher"] n7_extEditors_TargettedTextEdit["TargettedTextEdit"] n8_src_model_ViewModel["ViewModel"] n9_s_textEditors_TextEditPrompt["TextEditPrompt"] n5_src_model_HistoryModel --> n1_src_study_StudyModel n5_src_model_HistoryModel --> n0_src_model_Model n5_src_model_HistoryModel --> n6_xtExtractors_VisualRefresher n0_src_model_Model --> n1_src_study_StudyModel n0_src_model_Model --> n5_src_model_HistoryModel n0_src_model_Model --> n4_ors_SentenceActionsExtractor n7_extEditors_TargettedTextEdit --> n0_src_model_Model n7_extEditors_TargettedTextEdit --> n9_s_textEditors_TextEditPrompt n9_s_textEditors_TextEditPrompt --> n5_src_model_HistoryModel n9_s_textEditors_TextEditPrompt --> n0_src_model_Model n9_s_textEditors_TextEditPrompt --> n8_src_model_ViewModel n9_s_textEditors_TextEditPrompt --> n6_xtExtractors_VisualRefresher n4_ors_SentenceActionsExtractor --> n0_src_model_Model n4_ors_SentenceActionsExtractor --> n3_del_prompts_utils_BasePrompt n6_xtExtractors_VisualRefresher --> n2_src_model_LayoutUtils n6_xtExtractors_VisualRefresher --> n0_src_model_Model n6_xtExtractors_VisualRefresher --> n4_ors_SentenceActionsExtractor n1_src_study_StudyModel --> n5_src_model_HistoryModel classDef cyc stroke:#ef4444,stroke-width:2px; class n0_src_model_Model,n1_src_study_StudyModel,n4_ors_SentenceActionsExtractor,n5_src_model_HistoryModel,n6_xtExtractors_VisualRefresher,n7_extEditors_TargettedTextEdit,n9_s_textEditors_TextEditPrompt cyc;

Findings

MediumNo test files detected - untested code paths repository-wide

What would stop me shipping this

Ranked by severity × confidence × production reach. Reach is the honest discriminator across a collection that is mostly other people's code: the same finding matters more in something that ships.

high2

medium4

low2

Pin third-party GitHub Actions to a commit SHAhigh

.github/workflows

s0/git-publish-subdir-action@develop

A tag can be moved, so the action running with your token and secrets is whatever its owner last pushed; this is how tj-actions/changed-files leaked secrets from thousands of repos.

Fix: Replace each @vN with the 40-character commit SHA, keep # vN as a comment, and let Dependabot bump the SHAs.

Add a test suite; this repository has nonehigh60 occurrences

60 source files, no test files

Any change ships with no signal that existing behaviour still holds, so a regression reaches production undetected.

Fix: Add one test per public entry point, then a CI step that runs them.

Declare least-privilege permissions for GITHUB_TOKENmedium

.github/workflows/deploy.yml

1 workflow(s) declare no permissions, 1 of them reference secrets

With no declaration the token inherits the repository default, so any injected step can push commits or mint releases from inside your own CI.

Fix: Add permissions: contents: read at the top of the workflow and widen per job only where needed.

Enable Dependabot or Renovatemedium

1 manifest(s), no update bot configured

Without a bot a published advisory sits unpatched until someone audits by hand, which across 1,322 repositories means never.

Fix: Commit .github/dependabot.yml covering the repo ecosystems plus github-actions.

Gate pull requests on a dependency vulnerability scanmedium

.github/workflows

no dependency scan in CI

This is the one gate that would catch a known-vulnerable package before it reaches a build, and no repository in the sample had it.

Fix: Add dependency-review-action on pull_request, or osv-scanner on push and a schedule.

Move large binaries to Git LFS or out of the repositorymedium6 occurrences

public/videos/Entities.mp4

6 blobs over 5MB: Entities.mp4 9.3MB, Locations.mp4 6.3MB, Reading.mp4 5.5MB

One repository here carries twenty blobs over 5MB including a 10.9MB spreadsheet, so every clone and every CI checkout pays for data nobody diffs.

Fix: Track those extensions with LFS, or move datasets to object storage and fetch them in a setup step.

Set timeout-minutes on the workflow jobslow

.github/workflows/deploy.yml

1 workflow(s) declare no job timeout

A wedged step runs to the six-hour platform default, which on a two-hourly schedule means three runs overlap behind it.

Fix: Add timeout-minutes with a realistic bound to each job.

Add the repository convention files this project lackslow3 occurrences

missing .editorconfig, .gitattributes, a formatter config

Without them one contributor's editor writes tabs into a Python file, a shell script commits with CRLF and fails in the container, and a notebook diff is unreviewable.

Fix: Add .editorconfig, .gitattributes with text=auto eol=lf, and a formatter config.

Checked deterministically against the repository tree and a bounded set of its files: committed credentials, unpinned actions and base images, missing lockfiles and update bots, workflows that discard failures, published advisories against the declared dependencies, runtime configuration, licensing and notebook reproducibility. No language model is involved in this section.