# arielletolome/overlay-text-video-editor architecture

> Architecture diagram of the GitHub repository arielletolome/overlay-text-video-editor, 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/arielletolome/overlay-text-video-editor
- Repository: https://github.com/arielletolome/overlay-text-video-editor

## Overview

This repository is an AI-assisted vertical-video production engine. Users invoke the CLI to render batches of caption/style overlays onto raw clips, or to build a UGC ad from hook, proof/demo, and CTA footage; outputs can be graded, animated, mixed, evaluated, organized, and packaged. The README documents additional caption styles, placement/timing options, music extraction, AI scoring, and persistent session memory. Those capabilities are represented where paths or sampled call wiring support them; unsampled subsystems use their existing source directory or are omitted where wiring is unclear.

Main entry points: [`src/stitcher.ts`](https://github.com/arielletolome/overlay-text-video-editor/blob/master/src/stitcher.ts) (UGC stitcher), [`src/cli.ts`](https://github.com/arielletolome/overlay-text-video-editor/blob/master/src/cli.ts) (CLI options), [`src/editor.ts`](https://github.com/arielletolome/overlay-text-video-editor/blob/master/src/editor.ts) (Batch editor), [`src/ai.ts`](https://github.com/arielletolome/overlay-text-video-editor/blob/master/src/ai.ts) (AI script and score)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User workflow"]
  node_cli["CLI options<br/>[cli.ts]"]
  node_editor["Batch editor<br/>[editor.ts]"]
end

subgraph group_captions["Caption rendering"]
  node_renderer["Overlay renderer<br/>[renderer.ts]"]
  node_templates["Style templates"]
end

subgraph group_ugc["UGC production"]
  node_stitcher["UGC stitcher<br/>[stitcher.ts]"]
  node_ai["AI script and score<br/>[ai.ts]"]
  node_reaction["Reaction hooks<br/>[types.ts]"]
end

subgraph group_media["Media finishing"]
  node_grade["Color grading<br/>[grade.ts]"]
  node_animation["Video animation<br/>[animation.ts]"]
  node_audio["Audio processing<br/>[audio.ts]"]
  node_evaluator["Video evaluation<br/>[evaluator.ts]"]
end

subgraph group_delivery["Output and memory"]
  node_utils["Media utilities<br/>[utils.ts]"]
  node_session[("Session memory<br/>[session.ts]")]
  node_output["Rendered deliverables"]
end

node_user(("Video editor"))
node_proxy["CLIProxyAPI"]
node_fish["Fish Audio service"]
node_music["TikTok / YouTube audio"]

node_user -->|"sets options"| node_cli
node_cli -->|"runs batch"| node_editor
node_editor -->|"renders overlays"| node_renderer
node_renderer -->|"loads styles"| node_templates
node_editor -->|"composites and packages"| node_utils
node_editor -->|"writes batch"| node_output
node_cli -->|"runs stitch mode"| node_stitcher
node_cli -->|"requests virality score"| node_ai
node_stitcher -->|"generates script"| node_ai
node_ai -.->|"calls API"| node_proxy
node_ai -->|"gets hook text"| node_reaction
node_stitcher -->|"selects hook presets"| node_reaction
node_stitcher -->|"grades footage"| node_grade
node_stitcher -->|"applies effects"| node_animation
node_stitcher -->|"mixes audio"| node_audio
node_stitcher -->|"evaluates output"| node_evaluator
node_stitcher -.->|"requests speech"| node_fish
node_stitcher -.->|"downloads music"| node_music
node_stitcher -->|"writes stitched video"| node_output
node_cli -->|"reads or shows memory"| node_session
node_cli -->|"records run"| node_output

click node_cli "https://github.com/arielletolome/overlay-text-video-editor/blob/master/src/cli.ts"
click node_editor "https://github.com/arielletolome/overlay-text-video-editor/blob/master/src/editor.ts"
click node_renderer "https://github.com/arielletolome/overlay-text-video-editor/blob/master/src/renderer.ts"
click node_templates "https://github.com/arielletolome/overlay-text-video-editor/tree/master/templates"
click node_stitcher "https://github.com/arielletolome/overlay-text-video-editor/blob/master/src/stitcher.ts"
click node_ai "https://github.com/arielletolome/overlay-text-video-editor/blob/master/src/ai.ts"
click node_reaction "https://github.com/arielletolome/overlay-text-video-editor/blob/master/src/types.ts"
click node_grade "https://github.com/arielletolome/overlay-text-video-editor/blob/master/src/grade.ts"
click node_animation "https://github.com/arielletolome/overlay-text-video-editor/blob/master/src/animation.ts"
click node_audio "https://github.com/arielletolome/overlay-text-video-editor/blob/master/src/audio.ts"
click node_evaluator "https://github.com/arielletolome/overlay-text-video-editor/blob/master/src/evaluator.ts"
click node_utils "https://github.com/arielletolome/overlay-text-video-editor/blob/master/src/utils.ts"
click node_session "https://github.com/arielletolome/overlay-text-video-editor/blob/master/src/session.ts"

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_cli,node_editor toneBlue
class node_renderer,node_templates toneAmber
class node_stitcher,node_ai,node_reaction,node_proxy toneMint
class node_grade,node_animation,node_audio,node_evaluator toneRose
class node_utils,node_session,node_output,node_user,node_fish,node_music toneIndigo
```

## Components

### User workflow

- [CLI options](https://github.com/arielletolome/overlay-text-video-editor/blob/master/src/cli.ts): `src/cli.ts`
- [Batch editor](https://github.com/arielletolome/overlay-text-video-editor/blob/master/src/editor.ts): `src/editor.ts`

### Caption rendering

- [Overlay renderer](https://github.com/arielletolome/overlay-text-video-editor/blob/master/src/renderer.ts): `src/renderer.ts`
- [Style templates](https://github.com/arielletolome/overlay-text-video-editor/tree/master/templates): `templates`

### UGC production

- [UGC stitcher](https://github.com/arielletolome/overlay-text-video-editor/blob/master/src/stitcher.ts): `src/stitcher.ts`
- [AI script and score](https://github.com/arielletolome/overlay-text-video-editor/blob/master/src/ai.ts): `src/ai.ts`
- [Reaction hooks](https://github.com/arielletolome/overlay-text-video-editor/blob/master/src/types.ts): `src/types.ts`

### Media finishing

- [Color grading](https://github.com/arielletolome/overlay-text-video-editor/blob/master/src/grade.ts): `src/grade.ts`
- [Video animation](https://github.com/arielletolome/overlay-text-video-editor/blob/master/src/animation.ts): `src/animation.ts`
- [Audio processing](https://github.com/arielletolome/overlay-text-video-editor/blob/master/src/audio.ts): `src/audio.ts`
- [Video evaluation](https://github.com/arielletolome/overlay-text-video-editor/blob/master/src/evaluator.ts): `src/evaluator.ts`

### Output and memory

- [Media utilities](https://github.com/arielletolome/overlay-text-video-editor/blob/master/src/utils.ts): `src/utils.ts`
- [Session memory](https://github.com/arielletolome/overlay-text-video-editor/blob/master/src/session.ts): `src/session.ts`
- **Rendered deliverables**

### Other components

- **Video editor**
- **CLIProxyAPI**
- **Fish Audio service**
- **TikTok / YouTube audio**

## Connections

- Video editor → CLI options: sets options
- CLI options → Batch editor: runs batch
- Batch editor → Overlay renderer: renders overlays
- Overlay renderer → Style templates: loads styles
- Batch editor → Media utilities: composites and packages
- Batch editor → Rendered deliverables: writes batch
- CLI options → UGC stitcher: runs stitch mode
- CLI options → AI script and score: requests virality score
- UGC stitcher → AI script and score: generates script
- AI script and score → CLIProxyAPI: calls API
- AI script and score → Reaction hooks: gets hook text
- UGC stitcher → Reaction hooks: selects hook presets
- UGC stitcher → Color grading: grades footage
- UGC stitcher → Video animation: applies effects
- UGC stitcher → Audio processing: mixes audio
- UGC stitcher → Video evaluation: evaluates output
- UGC stitcher → Fish Audio service: requests speech
- UGC stitcher → TikTok / YouTube audio: downloads music
- UGC stitcher → Rendered deliverables: writes stitched video
- CLI options → Session memory: reads or shows memory
- CLI options → Rendered deliverables: records run