# marlandoj/reporeel architecture

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

- Interactive diagram: https://gitdiagram.com/marlandoj/reporeel
- Repository: https://github.com/marlandoj/reporeel

## Overview

RepoReel turns public GitHub repository, pull-request, release, or compare data into a narrated, shareable explainer video. The main flow is submission, GitHub fact collection, script generation and optional human review, local voice synthesis, composition and rendering, then publication. Separate capabilities include the web studio and watch pages, an optional Keynote renderer, and ASD-STE100 checking and rewriting tools. Pipeline and review relationships are visible in excerpts; several server routes and subsystems are documented but not shown in detail, so their connections are limited.

Main entry points: [`src/lib/pipeline.ts`](https://github.com/marlandoj/reporeel/blob/main/src/lib/pipeline.ts) (Generation pipeline), [`src/server.ts`](https://github.com/marlandoj/reporeel/blob/main/src/server.ts) (HTTP server), [`src/lib/review.ts`](https://github.com/marlandoj/reporeel/blob/main/src/lib/review.ts) (Script review), [`src/lib/script.ts`](https://github.com/marlandoj/reporeel/blob/main/src/lib/script.ts) (Script generation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User entry"]
  node_studio["Studio and UI<br/>[ui.ts]"]
  node_site["Site pages<br/>[site.ts]"]
  node_server["HTTP server<br/>[server.ts]"]
end

subgraph group_reel["Reel generation"]
  node_pipeline["Generation pipeline<br/>[pipeline.ts]"]
  node_github["GitHub ingestion<br/>[github.ts]"]
  node_script["Script generation<br/>[script.ts]"]
  node_review["Script review<br/>[review.ts]"]
  node_options["Job options<br/>[options.ts]"]
end

subgraph group_delivery["Jobs and delivery"]
  node_controls["Generation controls<br/>[controls.ts]"]
  node_queue["Job queue<br/>[queue.ts]"]
  node_db[("Job database<br/>[db.ts]")]
  node_files["Job files<br/>[files.ts]"]
  node_watch["Watch and reel pages<br/>[ui.ts]"]
end

subgraph group_language["STE100 tools"]
  node_ste_page["STE100 page<br/>[ste100page.ts]"]
  node_ste_api["STE100 API<br/>[steapi.ts]"]
  node_ste_rules["STE100 rule engine<br/>[ste100.ts]"]
  node_plain_ref["Quick reference<br/>[ste100page.ts]"]
end

subgraph group_rendering["Composition and rendering"]
  node_tts["Local voice synthesis<br/>[tts.ts]"]
  node_compose["HyperFrames composition<br/>[compose.ts]"]
  node_renderer["Video rendering<br/>[render.ts]"]
  node_captions["Caption generation<br/>[captions.ts]"]
  node_huashu["Keynote renderer<br/>[huashu.ts]"]
end

node_user(("Visitor / operator"))
node_github_api["GitHub API"]

node_user -->|"submits URL"| node_studio
node_studio -.->|"sends requests"| node_server
node_server -.->|"serves pages"| node_site
node_server -.->|"dispatches jobs"| node_queue
node_server -.->|"routes review"| node_review
node_server -.->|"routes checks"| node_ste_api
node_server -.->|"serves tool"| node_ste_page
node_pipeline -->|"fetches facts"| node_github
node_github -->|"requests repository data"| node_github_api
node_pipeline -->|"generates script"| node_script
node_pipeline -->|"synthesizes narration"| node_tts
node_pipeline -->|"builds composition"| node_compose
node_pipeline -->|"selects alternate renderer"| node_huashu
node_pipeline -->|"renders video"| node_renderer
node_pipeline -->|"cleans render files"| node_files
node_review -->|"reads and saves script"| node_pipeline
node_review -->|"rewrites scene"| node_script
node_review -->|"updates job"| node_db
node_script -->|"requests AI generation"| node_controls
node_script -->|"uses plain-language rules"| node_ste_rules
node_compose -->|"builds captions"| node_captions
node_huashu -->|"builds captions"| node_captions
node_queue -->|"stores job state"| node_db
node_queue -->|"runs generation"| node_pipeline
node_site -.->|"links to studio"| node_studio
node_watch -.->|"shows reel status"| node_db
node_ste_page -.->|"requests analysis"| node_ste_api
node_ste_api -->|"checks and rewrites text"| node_ste_rules
node_ste_page -.->|"offers download"| node_plain_ref

click node_studio "https://github.com/marlandoj/reporeel/blob/main/src/lib/ui.ts"
click node_site "https://github.com/marlandoj/reporeel/blob/main/src/lib/site.ts"
click node_server "https://github.com/marlandoj/reporeel/blob/main/src/server.ts"
click node_pipeline "https://github.com/marlandoj/reporeel/blob/main/src/lib/pipeline.ts"
click node_github "https://github.com/marlandoj/reporeel/blob/main/src/lib/github.ts"
click node_script "https://github.com/marlandoj/reporeel/blob/main/src/lib/script.ts"
click node_review "https://github.com/marlandoj/reporeel/blob/main/src/lib/review.ts"
click node_options "https://github.com/marlandoj/reporeel/blob/main/src/lib/options.ts"
click node_controls "https://github.com/marlandoj/reporeel/blob/main/src/lib/controls.ts"
click node_queue "https://github.com/marlandoj/reporeel/blob/main/src/lib/queue.ts"
click node_db "https://github.com/marlandoj/reporeel/blob/main/src/lib/db.ts"
click node_files "https://github.com/marlandoj/reporeel/blob/main/src/lib/files.ts"
click node_watch "https://github.com/marlandoj/reporeel/blob/main/src/lib/ui.ts"
click node_tts "https://github.com/marlandoj/reporeel/blob/main/src/lib/tts.ts"
click node_compose "https://github.com/marlandoj/reporeel/blob/main/src/lib/compose.ts"
click node_renderer "https://github.com/marlandoj/reporeel/blob/main/src/lib/render.ts"
click node_captions "https://github.com/marlandoj/reporeel/blob/main/src/lib/captions.ts"
click node_huashu "https://github.com/marlandoj/reporeel/blob/main/src/lib/huashu.ts"
click node_ste_page "https://github.com/marlandoj/reporeel/blob/main/src/lib/ste100page.ts"
click node_ste_api "https://github.com/marlandoj/reporeel/blob/main/src/lib/steapi.ts"
click node_ste_rules "https://github.com/marlandoj/reporeel/blob/main/src/lib/ste100.ts"
click node_plain_ref "https://github.com/marlandoj/reporeel/blob/main/src/lib/ste100page.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_studio,node_site,node_server toneBlue
class node_pipeline,node_github,node_script,node_review,node_options toneAmber
class node_controls,node_queue,node_db,node_files,node_watch,node_github_api toneMint
class node_ste_page,node_ste_api,node_ste_rules,node_plain_ref toneRose
class node_tts,node_compose,node_renderer,node_captions,node_huashu,node_user toneIndigo
```

## Components

### User entry

- [Studio and UI](https://github.com/marlandoj/reporeel/blob/main/src/lib/ui.ts): `src/lib/ui.ts`
- [Site pages](https://github.com/marlandoj/reporeel/blob/main/src/lib/site.ts): `src/lib/site.ts`
- [HTTP server](https://github.com/marlandoj/reporeel/blob/main/src/server.ts): `src/server.ts`

### Reel generation

- [Generation pipeline](https://github.com/marlandoj/reporeel/blob/main/src/lib/pipeline.ts): `src/lib/pipeline.ts`
- [GitHub ingestion](https://github.com/marlandoj/reporeel/blob/main/src/lib/github.ts): `src/lib/github.ts`
- [Script generation](https://github.com/marlandoj/reporeel/blob/main/src/lib/script.ts): `src/lib/script.ts`
- [Script review](https://github.com/marlandoj/reporeel/blob/main/src/lib/review.ts): `src/lib/review.ts`
- [Job options](https://github.com/marlandoj/reporeel/blob/main/src/lib/options.ts): `src/lib/options.ts`

### Jobs and delivery

- [Generation controls](https://github.com/marlandoj/reporeel/blob/main/src/lib/controls.ts): `src/lib/controls.ts`
- [Job queue](https://github.com/marlandoj/reporeel/blob/main/src/lib/queue.ts): `src/lib/queue.ts`
- [Job database](https://github.com/marlandoj/reporeel/blob/main/src/lib/db.ts): `src/lib/db.ts`
- [Job files](https://github.com/marlandoj/reporeel/blob/main/src/lib/files.ts): `src/lib/files.ts`
- [Watch and reel pages](https://github.com/marlandoj/reporeel/blob/main/src/lib/ui.ts): `src/lib/ui.ts`

### STE100 tools

- [STE100 page](https://github.com/marlandoj/reporeel/blob/main/src/lib/ste100page.ts): `src/lib/ste100page.ts`
- [STE100 API](https://github.com/marlandoj/reporeel/blob/main/src/lib/steapi.ts): `src/lib/steapi.ts`
- [STE100 rule engine](https://github.com/marlandoj/reporeel/blob/main/src/lib/ste100.ts): `src/lib/ste100.ts`
- [Quick reference](https://github.com/marlandoj/reporeel/blob/main/src/lib/ste100page.ts): `src/lib/ste100page.ts`

### Composition and rendering

- [Local voice synthesis](https://github.com/marlandoj/reporeel/blob/main/src/lib/tts.ts): `src/lib/tts.ts`
- [HyperFrames composition](https://github.com/marlandoj/reporeel/blob/main/src/lib/compose.ts): `src/lib/compose.ts`
- [Video rendering](https://github.com/marlandoj/reporeel/blob/main/src/lib/render.ts): `src/lib/render.ts`
- [Caption generation](https://github.com/marlandoj/reporeel/blob/main/src/lib/captions.ts): `src/lib/captions.ts`
- [Keynote renderer](https://github.com/marlandoj/reporeel/blob/main/src/lib/huashu.ts): `src/lib/huashu.ts`

### Other components

- **Visitor / operator**
- **GitHub API**

## Connections

- Visitor / operator → Studio and UI: submits URL (evidence: `README.md`)
- Studio and UI → HTTP server: sends requests (evidence: `src/server.ts`)
- HTTP server → Site pages: serves pages (evidence: `src/server.ts`)
- HTTP server → Job queue: dispatches jobs (evidence: `src/server.ts`)
- HTTP server → Script review: routes review (evidence: `src/server.ts`)
- HTTP server → STE100 API: routes checks (evidence: `src/server.ts`)
- HTTP server → STE100 page: serves tool (evidence: `src/server.ts`)
- Generation pipeline → GitHub ingestion: fetches facts (evidence: `src/lib/pipeline.ts`)
- GitHub ingestion → GitHub API: requests repository data (evidence: `src/lib/github.ts`)
- Generation pipeline → Script generation: generates script (evidence: `src/lib/pipeline.ts`)
- Generation pipeline → Local voice synthesis: synthesizes narration (evidence: `src/lib/pipeline.ts`)
- Generation pipeline → HyperFrames composition: builds composition (evidence: `src/lib/pipeline.ts`)
- Generation pipeline → Keynote renderer: selects alternate renderer (evidence: `src/lib/pipeline.ts`)
- Generation pipeline → Video rendering: renders video (evidence: `src/lib/pipeline.ts`)
- Generation pipeline → Job files: cleans render files (evidence: `src/lib/pipeline.ts`)
- Script review → Generation pipeline: reads and saves script (evidence: `src/lib/review.ts`)
- Script review → Script generation: rewrites scene (evidence: `src/lib/review.ts`)
- Script review → Job database: updates job (evidence: `src/lib/review.ts`)
- Script generation → Generation controls: requests AI generation (evidence: `src/lib/script.ts`)
- Script generation → STE100 rule engine: uses plain-language rules (evidence: `src/lib/script.ts`)
- HyperFrames composition → Caption generation: builds captions (evidence: `src/lib/compose.ts`)
- Keynote renderer → Caption generation: builds captions (evidence: `src/lib/huashu.ts`)
- Job queue → Job database: stores job state (evidence: `src/lib/queue.ts`)
- Job queue → Generation pipeline: runs generation (evidence: `src/lib/queue.ts`)
- Site pages → Studio and UI: links to studio (evidence: `src/lib/site.ts`)
- Watch and reel pages → Job database: shows reel status (evidence: `src/lib/ui.ts`)
- STE100 page → STE100 API: requests analysis (evidence: `src/lib/ste100page.ts`)
- STE100 API → STE100 rule engine: checks and rewrites text (evidence: `src/lib/steapi.ts`)
- STE100 page → Quick reference: offers download (evidence: `src/lib/ste100page.ts`)