# koioio/video-embedding architecture

> Architecture diagram of the GitHub repository koioio/video-embedding, 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/koioio/video-embedding
- Repository: https://github.com/koioio/video-embedding

## Overview

This repository’s main product is a video-embedding and recommendation service, with a Vue debugging client and offline recommendation training projects. The main workflow runs from video upload through HLS transcoding and AI-based transcription, segmentation, summaries, and embeddings; users can then play videos, retrieve relevant segments by question, and receive personalized recommendations. Interaction events also support recommendation training. The graph preserves the README’s documented capabilities; source excerpts were limited, so some subsystem links reflect that documentation rather than inspected call sites. The historical `legacy-video` project is excluded.

Main entry points: [`embedding-video/video-service/internal/application/videoapp/service.go`](https://github.com/koioio/video-embedding/blob/main/embedding-video/video-service/internal/application/videoapp/service.go) (Video application), [`embedding-video/video-service/internal/worker/vectorworker/app.go`](https://github.com/koioio/video-embedding/blob/main/embedding-video/video-service/internal/worker/vectorworker/app.go) (Vector worker), [`embedding-video/video-service/internal/http/handler`](https://github.com/koioio/video-embedding/tree/main/embedding-video/video-service/internal/http/handler) (API handlers), [`embedding-video/video-service/internal/infrastructure/objectstorage/rustfs.go`](https://github.com/koioio/video-embedding/blob/main/embedding-video/video-service/internal/infrastructure/objectstorage/rustfs.go) (Object storage)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client"]
  node_hls_web["Debug client<br/>[App.vue]"]
  node_short_web["Short-video client<br/>[App.vue]"]
end

subgraph group_service["HTTP service"]
  node_api["HTTP API<br/>[main.go]"]
  node_router["HTTP router<br/>[router.go]"]
  node_handlers["API handlers"]
  node_video_app["Video application<br/>[service.go]"]
  node_knowledge["Knowledge video<br/>[service.go]"]
  node_social["Social features<br/>[service.go]"]
end

subgraph group_media["Media processing"]
  node_upload["Upload workflow<br/>[service.go]"]
  node_transcode_worker["Transcode worker<br/>[app.go]"]
  node_transcoder["FFmpeg transcoder"]
  node_vector_worker["Vector worker<br/>[app.go]"]
  node_ai_tasks["AI segment tasks<br/>[hierarchical.go]"]
end

subgraph group_recsys["Recommendation"]
  node_recommend["Recommendation service<br/>[service.go]"]
  node_gorse{{"Gorse"}}
  node_two_tower["Two-tower training<br/>[train.py]"]
  node_recbole["RecBole training<br/>[train.py]"]
  node_export_data["Dataset export<br/>[main.go]"]
  node_import_embeddings["Embedding import<br/>[main.go]"]
end

subgraph group_data["State and integrations"]
  node_storage["Object storage<br/>[rustfs.go]"]
  node_postgres[("PostgreSQL")]
  node_redis["Redis queues"]
  node_ai_services{{"AI providers"}}
end

node_uploader(("Uploader / viewer"))

node_uploader -->|"uses"| node_hls_web
node_uploader -->|"uses"| node_short_web
node_hls_web -->|"calls API"| node_api
node_short_web -->|"calls API"| node_api
node_api -->|"starts"| node_router
node_router -->|"dispatches"| node_handlers
node_handlers -->|"invokes"| node_video_app
node_handlers -->|"invokes"| node_knowledge
node_handlers -->|"invokes"| node_social
node_video_app -->|"delegates upload"| node_upload
node_upload -->|"stores source"| node_storage
node_upload -->|"queues work"| node_redis
node_transcode_worker -->|"consumes jobs"| node_redis
node_transcode_worker -->|"transcodes"| node_transcoder
node_transcoder -->|"writes HLS"| node_storage
node_transcode_worker -->|"updates status"| node_postgres
node_vector_worker -->|"consumes jobs"| node_redis
node_vector_worker -->|"reads media"| node_storage
node_vector_worker -->|"runs stages"| node_ai_tasks
node_ai_tasks -.->|"uses AI"| node_ai_services
node_vector_worker -->|"persists results"| node_postgres
node_video_app -->|"reads and writes"| node_postgres
node_knowledge -->|"manages media"| node_storage
node_knowledge -->|"persists records"| node_postgres
node_video_app -->|"requests recommendations"| node_recommend
node_recommend -.->|"gets candidates"| node_gorse
node_recommend -->|"loads recommendation data"| node_postgres
node_uploader -->|"records interactions"| node_video_app
node_export_data -->|"reads events and items"| node_postgres
node_export_data -->|"exports dataset"| node_recbole
node_export_data -->|"supplies training data"| node_two_tower
node_two_tower -->|"exports embeddings"| node_import_embeddings
node_import_embeddings -->|"upserts embeddings"| node_postgres

click node_hls_web "https://github.com/koioio/video-embedding/blob/main/embedding-video/hls-web/src/App.vue"
click node_short_web "https://github.com/koioio/video-embedding/blob/main/embedding-video/short-video-web/src/App.vue"
click node_api "https://github.com/koioio/video-embedding/blob/main/embedding-video/video-service/cmd/httpapi/main.go"
click node_router "https://github.com/koioio/video-embedding/blob/main/embedding-video/video-service/internal/http/router/router.go"
click node_handlers "https://github.com/koioio/video-embedding/tree/main/embedding-video/video-service/internal/http/handler"
click node_video_app "https://github.com/koioio/video-embedding/blob/main/embedding-video/video-service/internal/application/videoapp/service.go"
click node_knowledge "https://github.com/koioio/video-embedding/blob/main/embedding-video/video-service/internal/application/knowledgevideo/service.go"
click node_social "https://github.com/koioio/video-embedding/blob/main/embedding-video/video-service/internal/application/userfollow/service.go"
click node_upload "https://github.com/koioio/video-embedding/blob/main/embedding-video/video-service/internal/application/videoapp/upload/service.go"
click node_transcode_worker "https://github.com/koioio/video-embedding/blob/main/embedding-video/video-service/internal/worker/transcodeworker/app.go"
click node_transcoder "https://github.com/koioio/video-embedding/blob/main/embedding-video/video-service/internal/infrastructure/transcode/ffmpeg_transcoder.go"
click node_vector_worker "https://github.com/koioio/video-embedding/blob/main/embedding-video/video-service/internal/worker/vectorworker/app.go"
click node_ai_tasks "https://github.com/koioio/video-embedding/blob/main/embedding-video/video-service/internal/worker/vectorworker/tasks/hierarchical.go"
click node_storage "https://github.com/koioio/video-embedding/blob/main/embedding-video/video-service/internal/infrastructure/objectstorage/rustfs.go"
click node_recommend "https://github.com/koioio/video-embedding/blob/main/embedding-video/video-service/internal/application/videoapp/recommendation/service.go"
click node_two_tower "https://github.com/koioio/video-embedding/blob/main/embedding-video/two-tower-training/src/two_tower_training/train.py"
click node_recbole "https://github.com/koioio/video-embedding/blob/main/embedding-video/recbole-training/src/recbole_recommendation/train.py"
click node_export_data "https://github.com/koioio/video-embedding/blob/main/embedding-video/video-service/tools/export_recbole_dataset/main.go"
click node_import_embeddings "https://github.com/koioio/video-embedding/blob/main/embedding-video/video-service/tools/import_recsys_embeddings/main.go"

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_hls_web,node_short_web,node_uploader toneBlue
class node_api,node_router,node_handlers,node_video_app,node_knowledge,node_social toneAmber
class node_upload,node_transcode_worker,node_transcoder,node_vector_worker,node_ai_tasks toneMint
class node_recommend,node_gorse,node_two_tower,node_recbole,node_export_data,node_import_embeddings toneRose
class node_storage,node_postgres,node_redis,node_ai_services toneIndigo
```

## Components

### Client

- [Debug client](https://github.com/koioio/video-embedding/blob/main/embedding-video/hls-web/src/App.vue): `embedding-video/hls-web/src/App.vue`
- [Short-video client](https://github.com/koioio/video-embedding/blob/main/embedding-video/short-video-web/src/App.vue): `embedding-video/short-video-web/src/App.vue`

### HTTP service

- [HTTP API](https://github.com/koioio/video-embedding/blob/main/embedding-video/video-service/cmd/httpapi/main.go): `embedding-video/video-service/cmd/httpapi/main.go`
- [HTTP router](https://github.com/koioio/video-embedding/blob/main/embedding-video/video-service/internal/http/router/router.go): `embedding-video/video-service/internal/http/router/router.go`
- [API handlers](https://github.com/koioio/video-embedding/tree/main/embedding-video/video-service/internal/http/handler): `embedding-video/video-service/internal/http/handler`
- [Video application](https://github.com/koioio/video-embedding/blob/main/embedding-video/video-service/internal/application/videoapp/service.go): `embedding-video/video-service/internal/application/videoapp/service.go`
- [Knowledge video](https://github.com/koioio/video-embedding/blob/main/embedding-video/video-service/internal/application/knowledgevideo/service.go): `embedding-video/video-service/internal/application/knowledgevideo/service.go`
- [Social features](https://github.com/koioio/video-embedding/blob/main/embedding-video/video-service/internal/application/userfollow/service.go): `embedding-video/video-service/internal/application/userfollow/service.go`

### Media processing

- [Upload workflow](https://github.com/koioio/video-embedding/blob/main/embedding-video/video-service/internal/application/videoapp/upload/service.go): `embedding-video/video-service/internal/application/videoapp/upload/service.go`
- [Transcode worker](https://github.com/koioio/video-embedding/blob/main/embedding-video/video-service/internal/worker/transcodeworker/app.go): `embedding-video/video-service/internal/worker/transcodeworker/app.go`
- [FFmpeg transcoder](https://github.com/koioio/video-embedding/blob/main/embedding-video/video-service/internal/infrastructure/transcode/ffmpeg_transcoder.go): `embedding-video/video-service/internal/infrastructure/transcode/ffmpeg_transcoder.go`
- [Vector worker](https://github.com/koioio/video-embedding/blob/main/embedding-video/video-service/internal/worker/vectorworker/app.go): `embedding-video/video-service/internal/worker/vectorworker/app.go`
- [AI segment tasks](https://github.com/koioio/video-embedding/blob/main/embedding-video/video-service/internal/worker/vectorworker/tasks/hierarchical.go): `embedding-video/video-service/internal/worker/vectorworker/tasks/hierarchical.go`

### Recommendation

- [Recommendation service](https://github.com/koioio/video-embedding/blob/main/embedding-video/video-service/internal/application/videoapp/recommendation/service.go): `embedding-video/video-service/internal/application/videoapp/recommendation/service.go`
- **Gorse**
- [Two-tower training](https://github.com/koioio/video-embedding/blob/main/embedding-video/two-tower-training/src/two_tower_training/train.py): `embedding-video/two-tower-training/src/two_tower_training/train.py`
- [RecBole training](https://github.com/koioio/video-embedding/blob/main/embedding-video/recbole-training/src/recbole_recommendation/train.py): `embedding-video/recbole-training/src/recbole_recommendation/train.py`
- [Dataset export](https://github.com/koioio/video-embedding/blob/main/embedding-video/video-service/tools/export_recbole_dataset/main.go): `embedding-video/video-service/tools/export_recbole_dataset/main.go`
- [Embedding import](https://github.com/koioio/video-embedding/blob/main/embedding-video/video-service/tools/import_recsys_embeddings/main.go): `embedding-video/video-service/tools/import_recsys_embeddings/main.go`

### State and integrations

- [Object storage](https://github.com/koioio/video-embedding/blob/main/embedding-video/video-service/internal/infrastructure/objectstorage/rustfs.go): `embedding-video/video-service/internal/infrastructure/objectstorage/rustfs.go`
- **PostgreSQL**
- **Redis queues**
- **AI providers**

### Other components

- **Uploader / viewer**

## Connections

- Uploader / viewer → Debug client: uses
- Uploader / viewer → Short-video client: uses
- Debug client → HTTP API: calls API
- Short-video client → HTTP API: calls API
- HTTP API → HTTP router: starts
- HTTP router → API handlers: dispatches
- API handlers → Video application: invokes
- API handlers → Knowledge video: invokes
- API handlers → Social features: invokes
- Video application → Upload workflow: delegates upload
- Upload workflow → Object storage: stores source
- Upload workflow → Redis queues: queues work
- Transcode worker → Redis queues: consumes jobs
- Transcode worker → FFmpeg transcoder: transcodes
- FFmpeg transcoder → Object storage: writes HLS
- Transcode worker → PostgreSQL: updates status
- Vector worker → Redis queues: consumes jobs
- Vector worker → Object storage: reads media
- Vector worker → AI segment tasks: runs stages
- AI segment tasks → AI providers: uses AI
- Vector worker → PostgreSQL: persists results
- Video application → PostgreSQL: reads and writes
- Knowledge video → Object storage: manages media
- Knowledge video → PostgreSQL: persists records
- Video application → Recommendation service: requests recommendations
- Recommendation service → Gorse: gets candidates
- Recommendation service → PostgreSQL: loads recommendation data
- Uploader / viewer → Video application: records interactions
- Dataset export → PostgreSQL: reads events and items
- Dataset export → RecBole training: exports dataset
- Dataset export → Two-tower training: supplies training data
- Two-tower training → Embedding import: exports embeddings
- Embedding import → PostgreSQL: upserts embeddings