# motion-minds/motionmind-video architecture

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

- Interactive diagram: https://gitdiagram.com/motion-minds/motionmind-video
- Repository: https://github.com/motion-minds/motionmind-video

## Overview

MotionMind is an agent-assisted video production and version-tracking tool: the agent builds HyperFrames projects, while the CLI records, measures and stages video or image outputs in a local store. Reviewers use the Studio to inspect versions, compare outputs, comment and promote. The graph preserves documented music, SFX, tracking and starter-kit capabilities. Several Studio page-to-data-layer connections are not visible in the excerpts, so those links are omitted rather than inferred.

Main entry points: [`studio/cli/main.ts`](https://github.com/motion-minds/motionmind-video/blob/main/studio/cli/main.ts) (MotionMind CLI), [`studio/core/runs.ts`](https://github.com/motion-minds/motionmind-video/blob/main/studio/core/runs.ts) (Run lifecycle), [`studio/core/store.ts`](https://github.com/motion-minds/motionmind-video/blob/main/studio/core/store.ts) (Tracking store), [`studio/core/setup.ts`](https://github.com/motion-minds/motionmind-video/blob/main/studio/core/setup.ts) (Workspace setup)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_production["Production workflow"]
  node_cli["MotionMind CLI<br/>[main.ts]"]
  node_setup["Workspace setup<br/>[setup.ts]"]
  node_render["HyperFrames engine<br/>[hyperframes.ts]"]
end

subgraph group_tracking["Version tracking"]
  node_runs["Run lifecycle<br/>[runs.ts]"]
  node_media["Media measurement<br/>[media.ts]"]
  node_qa["Loudness QA<br/>[qa.ts]"]
  node_store[("Tracking store<br/>[store.ts]")]
  node_images["Image deliverables<br/>[page.tsx]"]
end

subgraph group_studio["Studio review"]
  node_review["Timestamped review<br/>[review.ts]"]
  node_studiohub["Studio data layer<br/>[hub.ts]"]
  node_campaigns["Campaign browser<br/>[page.tsx]"]
  node_runpage["Version review page<br/>[page.tsx]"]
  node_compare["Version comparison<br/>[compare.ts]"]
  node_actions["Studio actions<br/>[actions.ts]"]
end

subgraph group_creative["Creative assets"]
  node_music["Procedural music<br/>[music.ts]"]
  node_sfx["Starter sound effects<br/>[sfx.ts]"]
  node_starter["Starter kits<br/>[StarterKit.tsx]"]
end

subgraph group_foundation["Runtime foundation"]
  node_host["Host protection<br/>[host.ts]"]
end

node_agent(("AI agent"))
node_reviewer(("Reviewer"))

node_agent -->|"runs commands"| node_cli
node_cli -->|"checks setup"| node_setup
node_cli -->|"dispatches runs"| node_runs
node_cli -->|"reads store"| node_store
node_runs -->|"renders projects"| node_render
node_runs -->|"measures outputs"| node_media
node_runs -->|"records versions"| node_store
node_runs -->|"checks metrics"| node_qa
node_setup -->|"initializes store"| node_store
node_setup -->|"checks engine"| node_render
node_cli -->|"generates beds"| node_music
node_cli -->|"uses sound pack"| node_sfx
node_cli -->|"reads reviews"| node_review
node_reviewer -->|"reviews versions"| node_runpage
node_reviewer -->|"browses campaigns"| node_campaigns
node_runpage -.->|"loads version data"| node_studiohub
node_campaigns -.->|"loads campaigns"| node_studiohub
node_reviewer -->|"compares versions"| node_compare
node_reviewer -->|"submits verdicts"| node_actions
node_actions -.->|"updates review"| node_review
node_review -->|"persists comments"| node_store
node_reviewer -->|"reviews images"| node_images
node_agent -->|"uses starter kits"| node_starter
node_host -.->|"protects requests"| node_studiohub

click node_cli "https://github.com/motion-minds/motionmind-video/blob/main/studio/cli/main.ts"
click node_setup "https://github.com/motion-minds/motionmind-video/blob/main/studio/core/setup.ts"
click node_render "https://github.com/motion-minds/motionmind-video/blob/main/studio/core/hyperframes.ts"
click node_runs "https://github.com/motion-minds/motionmind-video/blob/main/studio/core/runs.ts"
click node_media "https://github.com/motion-minds/motionmind-video/blob/main/studio/core/media.ts"
click node_qa "https://github.com/motion-minds/motionmind-video/blob/main/studio/core/qa.ts"
click node_store "https://github.com/motion-minds/motionmind-video/blob/main/studio/core/store.ts"
click node_review "https://github.com/motion-minds/motionmind-video/blob/main/studio/core/review.ts"
click node_studiohub "https://github.com/motion-minds/motionmind-video/blob/main/studio/lib/hub.ts"
click node_campaigns "https://github.com/motion-minds/motionmind-video/blob/main/studio/app/campaigns/page.tsx"
click node_runpage "https://github.com/motion-minds/motionmind-video/blob/main/studio/app/r/%5Bbrand%5D/%5Bcampaign%5D/%5Bversion%5D/page.tsx"
click node_compare "https://github.com/motion-minds/motionmind-video/blob/main/studio/lib/compare.ts"
click node_actions "https://github.com/motion-minds/motionmind-video/blob/main/studio/app/actions.ts"
click node_music "https://github.com/motion-minds/motionmind-video/blob/main/studio/core/music.ts"
click node_sfx "https://github.com/motion-minds/motionmind-video/blob/main/studio/core/sfx.ts"
click node_starter "https://github.com/motion-minds/motionmind-video/blob/main/studio/components/StarterKit.tsx"
click node_images "https://github.com/motion-minds/motionmind-video/blob/main/studio/app/images/page.tsx"
click node_host "https://github.com/motion-minds/motionmind-video/blob/main/studio/core/host.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_setup,node_render,node_reviewer toneBlue
class node_runs,node_media,node_qa,node_store,node_images toneAmber
class node_review,node_studiohub,node_campaigns,node_runpage,node_compare,node_actions toneMint
class node_music,node_sfx,node_starter toneRose
class node_host,node_agent toneIndigo
```

## Components

### Production workflow

- [MotionMind CLI](https://github.com/motion-minds/motionmind-video/blob/main/studio/cli/main.ts): `studio/cli/main.ts`
- [Workspace setup](https://github.com/motion-minds/motionmind-video/blob/main/studio/core/setup.ts): `studio/core/setup.ts`
- [HyperFrames engine](https://github.com/motion-minds/motionmind-video/blob/main/studio/core/hyperframes.ts): `studio/core/hyperframes.ts`

### Version tracking

- [Run lifecycle](https://github.com/motion-minds/motionmind-video/blob/main/studio/core/runs.ts): `studio/core/runs.ts`
- [Media measurement](https://github.com/motion-minds/motionmind-video/blob/main/studio/core/media.ts): `studio/core/media.ts`
- [Loudness QA](https://github.com/motion-minds/motionmind-video/blob/main/studio/core/qa.ts): `studio/core/qa.ts`
- [Tracking store](https://github.com/motion-minds/motionmind-video/blob/main/studio/core/store.ts): `studio/core/store.ts`
- [Image deliverables](https://github.com/motion-minds/motionmind-video/blob/main/studio/app/images/page.tsx): `studio/app/images/page.tsx`

### Studio review

- [Timestamped review](https://github.com/motion-minds/motionmind-video/blob/main/studio/core/review.ts): `studio/core/review.ts`
- [Studio data layer](https://github.com/motion-minds/motionmind-video/blob/main/studio/lib/hub.ts): `studio/lib/hub.ts`
- [Campaign browser](https://github.com/motion-minds/motionmind-video/blob/main/studio/app/campaigns/page.tsx): `studio/app/campaigns/page.tsx`
- [Version review page](https://github.com/motion-minds/motionmind-video/blob/main/studio/app/r/%5Bbrand%5D/%5Bcampaign%5D/%5Bversion%5D/page.tsx): `studio/app/r/[brand]/[campaign]/[version]/page.tsx`
- [Version comparison](https://github.com/motion-minds/motionmind-video/blob/main/studio/lib/compare.ts): `studio/lib/compare.ts`
- [Studio actions](https://github.com/motion-minds/motionmind-video/blob/main/studio/app/actions.ts): `studio/app/actions.ts`

### Creative assets

- [Procedural music](https://github.com/motion-minds/motionmind-video/blob/main/studio/core/music.ts): `studio/core/music.ts`
- [Starter sound effects](https://github.com/motion-minds/motionmind-video/blob/main/studio/core/sfx.ts): `studio/core/sfx.ts`
- [Starter kits](https://github.com/motion-minds/motionmind-video/blob/main/studio/components/StarterKit.tsx): `studio/components/StarterKit.tsx`

### Runtime foundation

- [Host protection](https://github.com/motion-minds/motionmind-video/blob/main/studio/core/host.ts): `studio/core/host.ts`

### Other components

- **AI agent**
- **Reviewer**

## Connections

- AI agent → MotionMind CLI: runs commands (evidence: `README.md`)
- MotionMind CLI → Workspace setup: checks setup (evidence: `studio/cli/main.ts`)
- MotionMind CLI → Run lifecycle: dispatches runs (evidence: `studio/cli/main.ts`)
- MotionMind CLI → Tracking store: reads store (evidence: `studio/cli/main.ts`)
- Run lifecycle → HyperFrames engine: renders projects (evidence: `studio/core/runs.ts`)
- Run lifecycle → Media measurement: measures outputs (evidence: `studio/core/runs.ts`)
- Run lifecycle → Tracking store: records versions (evidence: `studio/core/runs.ts`)
- Run lifecycle → Loudness QA: checks metrics (evidence: `studio/core/runs.ts`)
- Workspace setup → Tracking store: initializes store (evidence: `studio/core/setup.ts`)
- Workspace setup → HyperFrames engine: checks engine (evidence: `studio/core/setup.ts`)
- MotionMind CLI → Procedural music: generates beds (evidence: `README.md`)
- MotionMind CLI → Starter sound effects: uses sound pack (evidence: `README.md`)
- MotionMind CLI → Timestamped review: reads reviews (evidence: `studio/cli/main.ts`)
- Reviewer → Version review page: reviews versions (evidence: `README.md`)
- Reviewer → Campaign browser: browses campaigns (evidence: `README.md`)
- Version review page → Studio data layer: loads version data
- Campaign browser → Studio data layer: loads campaigns
- Reviewer → Version comparison: compares versions (evidence: `README.md`)
- Reviewer → Studio actions: submits verdicts (evidence: `README.md`)
- Studio actions → Timestamped review: updates review
- Timestamped review → Tracking store: persists comments (evidence: `studio/core/review.ts`)
- Reviewer → Image deliverables: reviews images (evidence: `README.md`)
- AI agent → Starter kits: uses starter kits (evidence: `README.md`)
- Host protection → Studio data layer: protects requests
