# vishwaksen21/media-gen architecture

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

- Interactive diagram: https://gitdiagram.com/vishwaksen21/media-gen
- Repository: https://github.com/vishwaksen21/media-gen

## Overview

This is a brand-compliant image and video generation platform with explicit human approval, append-only versions, and asynchronous generation jobs. Users enter through the React workspace; image and video workflows progress through reviewable domain stages, while backend services coordinate providers, validation, media storage, persistence, and finalization. The README documents workflow stages that are not all represented by sampled source, so those relationships are cited to it; uncertain implementation details are omitted.

Main entry points: [`frontend/src/features/video/VideoWorkflowPage.tsx`](https://github.com/vishwaksen21/media-gen/blob/main/frontend/src/features/video/VideoWorkflowPage.tsx) (Video workflow), [`backend/app/application/scene_generation_service.py`](https://github.com/vishwaksen21/media-gen/blob/main/backend/app/application/scene_generation_service.py) (Scene generation service), [`backend/app/api/routes`](https://github.com/vishwaksen21/media-gen/tree/main/backend/app/api/routes) (HTTP API), [`backend/app/application/image_service.py`](https://github.com/vishwaksen21/media-gen/blob/main/backend/app/application/image_service.py) (Image workflow service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workspace["User workspace"]
  node_app["Workspace routes<br/>[App.tsx]"]
end

subgraph group_image["Image workflow"]
  node_image_ui["Image generation"]
end

subgraph group_video["Video workflow"]
  node_video_ui["Video workflow"]
  node_story["Storyline review<br/>[StorylineStep.tsx]"]
  node_scenes["Scene review<br/>[ScenesStep.tsx]"]
  node_references["Reference approval<br/>[ReferencesStep.tsx]"]
  node_scene_gen["Scene generation review"]
  node_timeline["Timeline editing<br/>[TimelineStep.tsx]"]
  node_final_video["Final video review<br/>[FinalVideoStep.tsx]"]
  node_composition["FFmpeg composition<br/>[ffmpeg.py]"]
end

subgraph group_backend["Backend services"]
  node_api["HTTP API"]
  node_image_service["Image workflow service<br/>[image_service.py]"]
  node_story_service["Story and scene services<br/>[story_service.py]"]
  node_reference_service["Reference service"]
  node_scene_generation["Scene generation service"]
  node_prompting["Prompt compilation<br/>[prompting.py]"]
  node_validation["Media validation<br/>[validators.py]"]
  node_generation["Job creation"]
  node_finalization["Video finalization"]
  node_brand["Brand guidance<br/>[projections.py]"]
end

subgraph group_runtime["Runtime infrastructure"]
  node_worker["Job execution"]
  node_provider["AI provider<br/>[base.py]"]
  node_media["Media storage"]
  node_database[("Tenant data<br/>[repositories.py]")]
  node_queue["Job queue"]
end

node_user(("Reviewer"))

node_user -->|"uses"| node_app
node_app -->|"routes to"| node_image_ui
node_app -->|"routes to"| node_video_ui
node_user -->|"submits and reviews"| node_image_ui
node_image_ui -.->|"requests workflow"| node_api
node_video_ui -.->|"presents"| node_story
node_video_ui -.->|"presents"| node_scenes
node_video_ui -.->|"presents"| node_references
node_video_ui -->|"presents"| node_scene_gen
node_video_ui -.->|"presents"| node_timeline
node_video_ui -.->|"presents"| node_final_video
node_user -->|"reviews and approves"| node_story
node_user -->|"reviews and approves"| node_scenes
node_user -->|"pins versions"| node_references
node_user -->|"reviews or regenerates"| node_scene_gen
node_user -->|"edits"| node_timeline
node_user -->|"accepts or edits"| node_final_video
node_api -.->|"dispatches"| node_image_service
node_api -.->|"dispatches"| node_story_service
node_api -.->|"dispatches"| node_reference_service
node_api -.->|"dispatches"| node_scene_generation
node_image_service -->|"creates jobs"| node_generation
node_image_service -->|"compiles prompts"| node_prompting
node_image_service -.->|"validates requests"| node_validation
node_story_service -->|"compiles prompts"| node_prompting
node_story_service -.->|"creates jobs"| node_generation
node_reference_service -->|"uses prompt tools"| node_prompting
node_reference_service -.->|"creates jobs"| node_generation
node_scene_generation -->|"compiles prompts"| node_prompting
node_scene_generation -->|"creates jobs"| node_generation
node_scene_generation -.->|"validates results"| node_validation
node_image_service -->|"uses projections"| node_brand
node_scene_generation -->|"uses projections"| node_brand
node_generation -->|"enqueues jobs"| node_queue
node_worker -.->|"runs generation"| node_provider
node_worker -->|"records job state"| node_database
node_provider -.->|"returns media"| node_media
node_scene_generation -.->|"composes approved takes"| node_composition
node_composition -->|"probes output"| node_validation
node_finalization -.->|"finalizes workflow"| node_database
node_finalization -->|"retains final video"| node_media
node_user -->|"approves asset"| node_image_ui

click node_app "https://github.com/vishwaksen21/media-gen/blob/main/frontend/src/App.tsx"
click node_image_ui "https://github.com/vishwaksen21/media-gen/blob/main/frontend/src/features/images/ImageGenerationPage.tsx"
click node_video_ui "https://github.com/vishwaksen21/media-gen/blob/main/frontend/src/features/video/VideoWorkflowPage.tsx"
click node_story "https://github.com/vishwaksen21/media-gen/blob/main/frontend/src/features/video/StorylineStep.tsx"
click node_scenes "https://github.com/vishwaksen21/media-gen/blob/main/frontend/src/features/video/ScenesStep.tsx"
click node_references "https://github.com/vishwaksen21/media-gen/blob/main/frontend/src/features/video/ReferencesStep.tsx"
click node_scene_gen "https://github.com/vishwaksen21/media-gen/blob/main/frontend/src/features/video/SceneGenerationStep.tsx"
click node_timeline "https://github.com/vishwaksen21/media-gen/blob/main/frontend/src/features/video/TimelineStep.tsx"
click node_final_video "https://github.com/vishwaksen21/media-gen/blob/main/frontend/src/features/video/FinalVideoStep.tsx"
click node_api "https://github.com/vishwaksen21/media-gen/tree/main/backend/app/api/routes"
click node_image_service "https://github.com/vishwaksen21/media-gen/blob/main/backend/app/application/image_service.py"
click node_story_service "https://github.com/vishwaksen21/media-gen/blob/main/backend/app/application/story_service.py"
click node_reference_service "https://github.com/vishwaksen21/media-gen/blob/main/backend/app/application/reference_service.py"
click node_scene_generation "https://github.com/vishwaksen21/media-gen/blob/main/backend/app/application/scene_generation_service.py"
click node_prompting "https://github.com/vishwaksen21/media-gen/blob/main/backend/app/application/prompting.py"
click node_validation "https://github.com/vishwaksen21/media-gen/blob/main/backend/app/validation/validators.py"
click node_generation "https://github.com/vishwaksen21/media-gen/blob/main/backend/app/application/generation_service.py"
click node_worker "https://github.com/vishwaksen21/media-gen/blob/main/backend/app/workers/generation_worker.py"
click node_provider "https://github.com/vishwaksen21/media-gen/blob/main/backend/app/providers/base.py"
click node_composition "https://github.com/vishwaksen21/media-gen/blob/main/backend/app/composition/ffmpeg.py"
click node_media "https://github.com/vishwaksen21/media-gen/tree/main/backend/app/storage"
click node_database "https://github.com/vishwaksen21/media-gen/blob/main/backend/app/infrastructure/db/repositories.py"
click node_queue "https://github.com/vishwaksen21/media-gen/tree/main/backend/app/infrastructure/queue"
click node_finalization "https://github.com/vishwaksen21/media-gen/blob/main/backend/app/application/finalization_service.py"
click node_brand "https://github.com/vishwaksen21/media-gen/blob/main/backend/app/brand/projections.py"

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_app,node_user toneBlue
class node_image_ui toneAmber
class node_video_ui,node_story,node_scenes,node_references,node_scene_gen,node_timeline,node_final_video,node_composition toneMint
class node_api,node_image_service,node_story_service,node_reference_service,node_scene_generation,node_prompting,node_validation,node_generation,node_finalization,node_brand toneRose
class node_worker,node_provider,node_media,node_database,node_queue toneIndigo
```

## Components

### User workspace

- [Workspace routes](https://github.com/vishwaksen21/media-gen/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`

### Image workflow

- [Image generation](https://github.com/vishwaksen21/media-gen/blob/main/frontend/src/features/images/ImageGenerationPage.tsx): `frontend/src/features/images/ImageGenerationPage.tsx`

### Video workflow

- [Video workflow](https://github.com/vishwaksen21/media-gen/blob/main/frontend/src/features/video/VideoWorkflowPage.tsx): `frontend/src/features/video/VideoWorkflowPage.tsx`
- [Storyline review](https://github.com/vishwaksen21/media-gen/blob/main/frontend/src/features/video/StorylineStep.tsx): `frontend/src/features/video/StorylineStep.tsx`
- [Scene review](https://github.com/vishwaksen21/media-gen/blob/main/frontend/src/features/video/ScenesStep.tsx): `frontend/src/features/video/ScenesStep.tsx`
- [Reference approval](https://github.com/vishwaksen21/media-gen/blob/main/frontend/src/features/video/ReferencesStep.tsx): `frontend/src/features/video/ReferencesStep.tsx`
- [Scene generation review](https://github.com/vishwaksen21/media-gen/blob/main/frontend/src/features/video/SceneGenerationStep.tsx): `frontend/src/features/video/SceneGenerationStep.tsx`
- [Timeline editing](https://github.com/vishwaksen21/media-gen/blob/main/frontend/src/features/video/TimelineStep.tsx): `frontend/src/features/video/TimelineStep.tsx`
- [Final video review](https://github.com/vishwaksen21/media-gen/blob/main/frontend/src/features/video/FinalVideoStep.tsx): `frontend/src/features/video/FinalVideoStep.tsx`
- [FFmpeg composition](https://github.com/vishwaksen21/media-gen/blob/main/backend/app/composition/ffmpeg.py): `backend/app/composition/ffmpeg.py`

### Backend services

- [HTTP API](https://github.com/vishwaksen21/media-gen/tree/main/backend/app/api/routes): `backend/app/api/routes`
- [Image workflow service](https://github.com/vishwaksen21/media-gen/blob/main/backend/app/application/image_service.py): `backend/app/application/image_service.py`
- [Story and scene services](https://github.com/vishwaksen21/media-gen/blob/main/backend/app/application/story_service.py): `backend/app/application/story_service.py`
- [Reference service](https://github.com/vishwaksen21/media-gen/blob/main/backend/app/application/reference_service.py): `backend/app/application/reference_service.py`
- [Scene generation service](https://github.com/vishwaksen21/media-gen/blob/main/backend/app/application/scene_generation_service.py): `backend/app/application/scene_generation_service.py`
- [Prompt compilation](https://github.com/vishwaksen21/media-gen/blob/main/backend/app/application/prompting.py): `backend/app/application/prompting.py`
- [Media validation](https://github.com/vishwaksen21/media-gen/blob/main/backend/app/validation/validators.py): `backend/app/validation/validators.py`
- [Job creation](https://github.com/vishwaksen21/media-gen/blob/main/backend/app/application/generation_service.py): `backend/app/application/generation_service.py`
- [Video finalization](https://github.com/vishwaksen21/media-gen/blob/main/backend/app/application/finalization_service.py): `backend/app/application/finalization_service.py`
- [Brand guidance](https://github.com/vishwaksen21/media-gen/blob/main/backend/app/brand/projections.py): `backend/app/brand/projections.py`

### Runtime infrastructure

- [Job execution](https://github.com/vishwaksen21/media-gen/blob/main/backend/app/workers/generation_worker.py): `backend/app/workers/generation_worker.py`
- [AI provider](https://github.com/vishwaksen21/media-gen/blob/main/backend/app/providers/base.py): `backend/app/providers/base.py`
- [Media storage](https://github.com/vishwaksen21/media-gen/tree/main/backend/app/storage): `backend/app/storage`
- [Tenant data](https://github.com/vishwaksen21/media-gen/blob/main/backend/app/infrastructure/db/repositories.py): `backend/app/infrastructure/db/repositories.py`
- [Job queue](https://github.com/vishwaksen21/media-gen/tree/main/backend/app/infrastructure/queue): `backend/app/infrastructure/queue`

### Other components

- **Reviewer**

## Connections

- Reviewer → Workspace routes: uses (evidence: `frontend/src/App.tsx`)
- Workspace routes → Image generation: routes to (evidence: `frontend/src/App.tsx`)
- Workspace routes → Video workflow: routes to (evidence: `frontend/src/App.tsx`)
- Reviewer → Image generation: submits and reviews (evidence: `README.md`)
- Image generation → HTTP API: requests workflow
- Video workflow → Storyline review: presents
- Video workflow → Scene review: presents
- Video workflow → Reference approval: presents
- Video workflow → Scene generation review: presents (evidence: `frontend/src/features/video/SceneGenerationStep.tsx`)
- Video workflow → Timeline editing: presents
- Video workflow → Final video review: presents
- Reviewer → Storyline review: reviews and approves (evidence: `README.md`)
- Reviewer → Scene review: reviews and approves (evidence: `README.md`)
- Reviewer → Reference approval: pins versions (evidence: `README.md`)
- Reviewer → Scene generation review: reviews or regenerates (evidence: `README.md`)
- Reviewer → Timeline editing: edits (evidence: `README.md`)
- Reviewer → Final video review: accepts or edits (evidence: `README.md`)
- HTTP API → Image workflow service: dispatches
- HTTP API → Story and scene services: dispatches
- HTTP API → Reference service: dispatches
- HTTP API → Scene generation service: dispatches
- Image workflow service → Job creation: creates jobs (evidence: `backend/app/application/image_service.py`)
- Image workflow service → Prompt compilation: compiles prompts (evidence: `backend/app/application/image_service.py`)
- Image workflow service → Media validation: validates requests (evidence: `backend/app/application/image_service.py`)
- Story and scene services → Prompt compilation: compiles prompts (evidence: `backend/app/application/prompting.py`)
- Story and scene services → Job creation: creates jobs
- Reference service → Prompt compilation: uses prompt tools (evidence: `backend/app/application/reference_service.py`)
- Reference service → Job creation: creates jobs (evidence: `backend/app/application/reference_service.py`)
- Scene generation service → Prompt compilation: compiles prompts (evidence: `backend/app/application/scene_generation_service.py`)
- Scene generation service → Job creation: creates jobs (evidence: `backend/app/application/scene_generation_service.py`)
- Scene generation service → Media validation: validates results (evidence: `backend/app/application/scene_generation_service.py`)
- Image workflow service → Brand guidance: uses projections (evidence: `backend/app/application/image_service.py`)
- Scene generation service → Brand guidance: uses projections (evidence: `backend/app/application/scene_generation_service.py`)
- Job creation → Job queue: enqueues jobs (evidence: `backend/app/application/generation_service.py`)
- Job execution → AI provider: runs generation
- Job execution → Tenant data: records job state (evidence: `backend/app/workers/generation_worker.py`)
- AI provider → Media storage: returns media
- Scene generation service → FFmpeg composition: composes approved takes (evidence: `backend/app/application/scene_generation_service.py`)
- FFmpeg composition → Media validation: probes output (evidence: `backend/app/composition/ffmpeg.py`)
- Video finalization → Tenant data: finalizes workflow
- Video finalization → Media storage: retains final video (evidence: `README.md`)
- Reviewer → Image generation: approves asset (evidence: `README.md`)
