# ccallazans/ai-video-generator architecture

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

- Interactive diagram: https://gitdiagram.com/ccallazans/ai-video-generator
- Repository: https://github.com/ccallazans/ai-video-generator

## Overview

The product is an API-backed AI video story generator. A request supplies a prompt; the API validates it, the use case orchestrates text generation, speech synthesis, and video assembly, and the result is a captioned video. The README also documents background-video selection and captioning. The sampled Go and Python sources show the main calls; external model/tool connections are shown only where the excerpts establish them.

Main entry points: [`internal/usecases/generate.go`](https://github.com/ccallazans/ai-video-generator/blob/main/internal/usecases/generate.go) (Generation use case), [`internal/processes/video.go`](https://github.com/ccallazans/ai-video-generator/blob/main/internal/processes/video.go) (Video assembly), [`internal/server/routes.go`](https://github.com/ccallazans/ai-video-generator/blob/main/internal/server/routes.go) (API routes), [`internal/server/handlers/generate.go`](https://github.com/ccallazans/ai-video-generator/blob/main/internal/server/handlers/generate.go) (Generate handler)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API"]
  node_server["HTTP server<br/>[server.go]"]
  node_routes["API routes<br/>[routes.go]"]
  node_handler["Generate handler<br/>[generate.go]"]
end

subgraph group_generation["Generation"]
  node_usecase["Generation use case<br/>[generate.go]"]
  node_context["Generation context<br/>[process.go]"]
  node_text["Story generation<br/>[text2text.go]"]
  node_ollama["Ollama"]
end

subgraph group_media["Media production"]
  node_speech["Speech generation<br/>[text2speech.go]"]
  node_tts["TTS script<br/>[tts.py]"]
  node_video["Video assembly<br/>[video.go]"]
  node_backgrounds["Background videos"]
  node_media_tools["FFmpeg tools"]
  node_captions["Caption generation<br/>[captions.py]"]
end

subgraph group_outputs["Video output"]
  node_output["Generated video"]
end

node_user(("Prompt user"))

node_user -->|"submits prompt"| node_routes
node_server -->|"registers routes"| node_routes
node_routes -->|"routes POST"| node_handler
node_handler -->|"calls generation"| node_usecase
node_usecase -->|"starts pipeline"| node_text
node_usecase -->|"sets next stage"| node_speech
node_usecase -->|"sets next stage"| node_video
node_usecase -->|"creates context"| node_context
node_text -->|"requests completion"| node_ollama
node_speech -->|"runs script"| node_tts
node_video -->|"selects background"| node_backgrounds
node_video -->|"runs ffmpeg"| node_media_tools
node_video -->|"runs caption script"| node_captions
node_captions -->|"writes video"| node_output

click node_server "https://github.com/ccallazans/ai-video-generator/blob/main/internal/server/server.go"
click node_routes "https://github.com/ccallazans/ai-video-generator/blob/main/internal/server/routes.go"
click node_handler "https://github.com/ccallazans/ai-video-generator/blob/main/internal/server/handlers/generate.go"
click node_usecase "https://github.com/ccallazans/ai-video-generator/blob/main/internal/usecases/generate.go"
click node_context "https://github.com/ccallazans/ai-video-generator/blob/main/internal/processes/process.go"
click node_text "https://github.com/ccallazans/ai-video-generator/blob/main/internal/processes/text2text.go"
click node_speech "https://github.com/ccallazans/ai-video-generator/blob/main/internal/processes/text2speech.go"
click node_tts "https://github.com/ccallazans/ai-video-generator/blob/main/scripts/tts.py"
click node_video "https://github.com/ccallazans/ai-video-generator/blob/main/internal/processes/video.go"
click node_backgrounds "https://github.com/ccallazans/ai-video-generator/tree/main/resources/videos"
click node_captions "https://github.com/ccallazans/ai-video-generator/blob/main/scripts/captions.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_server,node_routes,node_handler,node_user toneBlue
class node_usecase,node_context,node_text,node_ollama toneAmber
class node_speech,node_tts,node_video,node_backgrounds,node_media_tools,node_captions toneMint
class node_output toneRose
```

## Components

### API

- [HTTP server](https://github.com/ccallazans/ai-video-generator/blob/main/internal/server/server.go): `internal/server/server.go`
- [API routes](https://github.com/ccallazans/ai-video-generator/blob/main/internal/server/routes.go): `internal/server/routes.go`
- [Generate handler](https://github.com/ccallazans/ai-video-generator/blob/main/internal/server/handlers/generate.go): `internal/server/handlers/generate.go`

### Generation

- [Generation use case](https://github.com/ccallazans/ai-video-generator/blob/main/internal/usecases/generate.go): `internal/usecases/generate.go`
- [Generation context](https://github.com/ccallazans/ai-video-generator/blob/main/internal/processes/process.go): `internal/processes/process.go`
- [Story generation](https://github.com/ccallazans/ai-video-generator/blob/main/internal/processes/text2text.go): `internal/processes/text2text.go`
- **Ollama**

### Media production

- [Speech generation](https://github.com/ccallazans/ai-video-generator/blob/main/internal/processes/text2speech.go): `internal/processes/text2speech.go`
- [TTS script](https://github.com/ccallazans/ai-video-generator/blob/main/scripts/tts.py): `scripts/tts.py`
- [Video assembly](https://github.com/ccallazans/ai-video-generator/blob/main/internal/processes/video.go): `internal/processes/video.go`
- [Background videos](https://github.com/ccallazans/ai-video-generator/tree/main/resources/videos): `resources/videos`
- **FFmpeg tools**
- [Caption generation](https://github.com/ccallazans/ai-video-generator/blob/main/scripts/captions.py): `scripts/captions.py`

### Video output

- **Generated video**

### Other components

- **Prompt user**

## Connections

- Prompt user → API routes: submits prompt (evidence: `README.md`)
- HTTP server → API routes: registers routes (evidence: `internal/server/server.go`)
- API routes → Generate handler: routes POST (evidence: `internal/server/routes.go`)
- Generate handler → Generation use case: calls generation (evidence: `internal/server/handlers/generate.go`)
- Generation use case → Story generation: starts pipeline (evidence: `internal/usecases/generate.go`)
- Generation use case → Speech generation: sets next stage (evidence: `internal/usecases/generate.go`)
- Generation use case → Video assembly: sets next stage (evidence: `internal/usecases/generate.go`)
- Generation use case → Generation context: creates context (evidence: `internal/usecases/generate.go`)
- Story generation → Ollama: requests completion (evidence: `internal/processes/text2text.go`)
- Speech generation → TTS script: runs script (evidence: `internal/processes/text2speech.go`)
- Video assembly → Background videos: selects background (evidence: `internal/processes/video.go`)
- Video assembly → FFmpeg tools: runs ffmpeg (evidence: `internal/processes/video.go`)
- Video assembly → Caption generation: runs caption script (evidence: `internal/processes/video.go`)
- Caption generation → Generated video: writes video (evidence: `scripts/captions.py`)