# oil-oil/oil-motion architecture

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

- Interactive diagram: https://gitdiagram.com/oil-oil/oil-motion
- Repository: https://github.com/oil-oil/oil-motion

## Overview

Oil Motion is an agent-oriented toolkit for creating interactive web animation assets and integrating them into pages. Its documented workflow runs from defining the motion and confirming keyframes, through AI video generation and frame preparation, to choosing and producing a delivery format for browser interaction. The graph also shows the documented credential setup and explainer-page capability. Source excerpts are partial, so links between unsampled runtime features and asset-processing stages are omitted where their callers are unclear.

Main entry points: [`scripts/compile_scroll_video.py`](https://github.com/oil-oil/oil-motion/blob/main/scripts/compile_scroll_video.py) (Video compilation), [`references/concepts.md`](https://github.com/oil-oil/oil-motion/blob/main/references/concepts.md) (Motion contract), [`scripts/video_job.py`](https://github.com/oil-oil/oil-motion/blob/main/scripts/video_job.py) (Video generation), [`scripts/image_job.py`](https://github.com/oil-oil/oil-motion/blob/main/scripts/image_job.py) (Keyframe generation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_design["Motion design"]
  node_contract["Motion contract<br/>[concepts.md]"]
end

subgraph group_generation["Asset generation"]
  node_keyframes["Keyframe generation<br/>[image_job.py]"]
  node_video_generation["Video generation<br/>[video_job.py]"]
end

subgraph group_delivery["Asset preparation"]
  node_frame_pipeline["Frame processing<br/>[motion_pipeline.py]"]
  node_budget["Delivery selection<br/>[motion_budget.py]"]
  node_video_compile["Video compilation"]
  node_optimization["Asset optimization<br/>[optimize_motion.py]"]
  node_chroma["Chroma keying<br/>[chroma_key.py]"]
  node_production_gate["Pilot approval<br/>[production_gate.py]"]
end

subgraph group_runtime["Web integration"]
  node_runtime_motion["Interactive playback"]
  node_chroma_renderer["Chroma renderer"]
  node_gesture["Gesture input<br/>[step-gesture.ts]"]
  node_explainer["Explainer-page generator"]
  node_explainer_template["Explainer template"]
end

subgraph group_credentials["Credentials"]
  node_credential_ui["Credential setup"]
end

node_user(("Project user"))
node_image_api{{"Image service"}}
node_video_api{{"Video service"}}
node_browser(("Web page"))
node_credential_store[("System credential store")]

node_user -->|"defines motion"| node_contract
node_contract -->|"guides keyframes"| node_keyframes
node_keyframes -->|"requests images"| node_image_api
node_contract -->|"guides action"| node_video_generation
node_video_generation -->|"submits job"| node_video_api
node_budget -->|"selects route"| node_video_compile
node_video_compile -->|"checks report"| node_budget
node_video_compile -->|"prepares frames"| node_frame_pipeline
node_optimization -->|"extracts frames"| node_frame_pipeline
node_video_compile -->|"uses keying"| node_chroma
node_production_gate -->|"approves production"| node_video_generation
node_browser -->|"provides interaction"| node_runtime_motion
node_browser -->|"plays video"| node_chroma_renderer
node_browser -->|"provides gestures"| node_gesture
node_explainer -->|"fills template"| node_explainer_template
node_browser -->|"views preview"| node_explainer
node_user -->|"enters keys"| node_credential_ui
node_credential_ui -->|"stores credentials"| node_credential_store

click node_contract "https://github.com/oil-oil/oil-motion/blob/main/references/concepts.md"
click node_keyframes "https://github.com/oil-oil/oil-motion/blob/main/scripts/image_job.py"
click node_video_generation "https://github.com/oil-oil/oil-motion/blob/main/scripts/video_job.py"
click node_frame_pipeline "https://github.com/oil-oil/oil-motion/blob/main/scripts/motion_pipeline.py"
click node_budget "https://github.com/oil-oil/oil-motion/blob/main/scripts/motion_budget.py"
click node_video_compile "https://github.com/oil-oil/oil-motion/blob/main/scripts/compile_scroll_video.py"
click node_optimization "https://github.com/oil-oil/oil-motion/blob/main/scripts/optimize_motion.py"
click node_chroma "https://github.com/oil-oil/oil-motion/blob/main/scripts/chroma_key.py"
click node_production_gate "https://github.com/oil-oil/oil-motion/blob/main/scripts/production_gate.py"
click node_runtime_motion "https://github.com/oil-oil/oil-motion/blob/main/assets/interactive-motion.ts"
click node_chroma_renderer "https://github.com/oil-oil/oil-motion/blob/main/assets/chroma-video-renderer.ts"
click node_gesture "https://github.com/oil-oil/oil-motion/blob/main/assets/step-gesture.ts"
click node_explainer "https://github.com/oil-oil/oil-motion/blob/main/scripts/create_explainer.py"
click node_explainer_template "https://github.com/oil-oil/oil-motion/blob/main/assets/motion-explainer-template.html"
click node_credential_ui "https://github.com/oil-oil/oil-motion/tree/main/scripts/credential-ui"

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_contract,node_user toneBlue
class node_keyframes,node_video_generation,node_credential_store toneAmber
class node_frame_pipeline,node_budget,node_video_compile,node_optimization,node_chroma,node_production_gate toneMint
class node_runtime_motion,node_chroma_renderer,node_gesture,node_explainer,node_explainer_template toneRose
class node_credential_ui,node_image_api,node_video_api,node_browser toneIndigo
```

## Components

### Motion design

- [Motion contract](https://github.com/oil-oil/oil-motion/blob/main/references/concepts.md): `references/concepts.md`

### Asset generation

- [Keyframe generation](https://github.com/oil-oil/oil-motion/blob/main/scripts/image_job.py): `scripts/image_job.py`
- [Video generation](https://github.com/oil-oil/oil-motion/blob/main/scripts/video_job.py): `scripts/video_job.py`

### Asset preparation

- [Frame processing](https://github.com/oil-oil/oil-motion/blob/main/scripts/motion_pipeline.py): `scripts/motion_pipeline.py`
- [Delivery selection](https://github.com/oil-oil/oil-motion/blob/main/scripts/motion_budget.py): `scripts/motion_budget.py`
- [Video compilation](https://github.com/oil-oil/oil-motion/blob/main/scripts/compile_scroll_video.py): `scripts/compile_scroll_video.py`
- [Asset optimization](https://github.com/oil-oil/oil-motion/blob/main/scripts/optimize_motion.py): `scripts/optimize_motion.py`
- [Chroma keying](https://github.com/oil-oil/oil-motion/blob/main/scripts/chroma_key.py): `scripts/chroma_key.py`
- [Pilot approval](https://github.com/oil-oil/oil-motion/blob/main/scripts/production_gate.py): `scripts/production_gate.py`

### Web integration

- [Interactive playback](https://github.com/oil-oil/oil-motion/blob/main/assets/interactive-motion.ts): `assets/interactive-motion.ts`
- [Chroma renderer](https://github.com/oil-oil/oil-motion/blob/main/assets/chroma-video-renderer.ts): `assets/chroma-video-renderer.ts`
- [Gesture input](https://github.com/oil-oil/oil-motion/blob/main/assets/step-gesture.ts): `assets/step-gesture.ts`
- [Explainer-page generator](https://github.com/oil-oil/oil-motion/blob/main/scripts/create_explainer.py): `scripts/create_explainer.py`
- [Explainer template](https://github.com/oil-oil/oil-motion/blob/main/assets/motion-explainer-template.html): `assets/motion-explainer-template.html`

### Credentials

- [Credential setup](https://github.com/oil-oil/oil-motion/tree/main/scripts/credential-ui): `scripts/credential-ui`

### Other components

- **Project user**
- **Image service**
- **Video service**
- **Web page**
- **System credential store**

## Connections

- Project user → Motion contract: defines motion
- Motion contract → Keyframe generation: guides keyframes
- Keyframe generation → Image service: requests images
- Motion contract → Video generation: guides action
- Video generation → Video service: submits job
- Delivery selection → Video compilation: selects route
- Video compilation → Delivery selection: checks report
- Video compilation → Frame processing: prepares frames
- Asset optimization → Frame processing: extracts frames
- Video compilation → Chroma keying: uses keying
- Pilot approval → Video generation: approves production
- Web page → Interactive playback: provides interaction
- Web page → Chroma renderer: plays video
- Web page → Gesture input: provides gestures
- Explainer-page generator → Explainer template: fills template
- Web page → Explainer-page generator: views preview
- Project user → Credential setup: enters keys
- Credential setup → System credential store: stores credentials