# slavakuntsov/flowix architecture

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

- Interactive diagram: https://gitdiagram.com/slavakuntsov/flowix
- Repository: https://github.com/slavakuntsov/flowix

## Overview

Flowix is a self-hosted video platform whose main workflow runs from browsing or uploading in the web app through gateway routing, asynchronous transcoding, metadata readiness, and HLS playback. The README documents the service pipeline and major streaming, security, and storage capabilities; sampled code confirms gateway routing and the auth service’s internal calls. Several backend and frontend paths are unsampled, so those relationships are shown only where documented.

Main entry points: [`services/gateway/cmd/server/main.go`](https://github.com/slavakuntsov/flowix/blob/main/services/gateway/cmd/server/main.go) (Route and proxy), [`services/metadata/internal/handler/video.go`](https://github.com/slavakuntsov/flowix/blob/main/services/metadata/internal/handler/video.go) (Video metadata API), [`frontend/src/lib/api.ts`](https://github.com/slavakuntsov/flowix/blob/main/frontend/src/lib/api.ts) (API client), [`services/auth/src/routers/auth.py`](https://github.com/slavakuntsov/flowix/blob/main/services/auth/src/routers/auth.py) (Auth endpoints)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web application"]
  node_home["Video catalog<br/>[page.tsx]"]
  node_authpages["Login and registration<br/>[page.tsx]"]
  node_uploadui["Upload interface<br/>[page.tsx]"]
  node_watch["Watch page<br/>[page.tsx]"]
  node_player["HLS player<br/>[VideoPlayer.tsx]"]
  node_api["API client<br/>[api.ts]"]
end

subgraph group_edge["API gateway"]
  node_gateway["Route and proxy<br/>[main.go]"]
end

subgraph group_identity["Identity service"]
  node_authrouter["Auth endpoints<br/>[auth.py]"]
  node_authapp["Auth application<br/>[main.py]"]
  node_authsecurity["Passwords and tokens<br/>[security.py]"]
  node_tokenstore["Refresh-token store<br/>[tokenstore.py]"]
  node_authdb["User database access<br/>[db.py]"]
end

subgraph group_video["Video services"]
  node_upload["Video upload service"]
  node_publisher["Upload event publisher<br/>[publisher.go]"]
  node_transcoder["Transcoding worker<br/>[consumer.py]"]
  node_metadata["Video metadata API<br/>[video.go]"]
end

subgraph group_infra["Storage and delivery"]
  node_minio[("Object storage")]
  node_rabbitmq["Upload queue"]
  node_postgres[("Postgres")]
  node_vod["nginx-vod"]
end

node_viewer(("Viewer or uploader"))

node_viewer -->|"browses"| node_home
node_viewer -->|"signs in"| node_authpages
node_viewer -->|"uploads video"| node_uploadui
node_viewer -->|"watches video"| node_watch
node_home -.->|"requests videos"| node_api
node_authpages -.->|"requests auth"| node_api
node_uploadui -.->|"submits upload"| node_api
node_watch -.->|"requests metadata"| node_api
node_watch -.->|"renders player"| node_player
node_player -.->|"loads HLS"| node_vod
node_api -.->|"calls API"| node_gateway
node_gateway -->|"proxies auth"| node_authapp
node_gateway -->|"proxies upload"| node_upload
node_gateway -->|"proxies metadata"| node_metadata
node_gateway -->|"proxies HLS"| node_vod
node_authapp -->|"registers routes"| node_authrouter
node_authrouter -->|"queries users"| node_authdb
node_authrouter -->|"verifies and signs"| node_authsecurity
node_authrouter -->|"rotates tokens"| node_tokenstore
node_upload -->|"stores raw video"| node_minio
node_upload -->|"publishes event"| node_publisher
node_publisher -->|"sends upload event"| node_rabbitmq
node_rabbitmq -->|"dispatches event"| node_transcoder
node_transcoder -->|"writes renditions"| node_minio
node_transcoder -->|"marks ready"| node_metadata
node_metadata -->|"reads and writes"| node_postgres
node_metadata -->|"deletes objects"| node_minio
node_vod -->|"packages renditions"| node_minio
node_vod -->|"reads video mapping"| node_metadata

click node_home "https://github.com/slavakuntsov/flowix/blob/main/frontend/src/app/page.tsx"
click node_authpages "https://github.com/slavakuntsov/flowix/blob/main/frontend/src/app/login/page.tsx"
click node_uploadui "https://github.com/slavakuntsov/flowix/blob/main/frontend/src/app/upload/page.tsx"
click node_watch "https://github.com/slavakuntsov/flowix/blob/main/frontend/src/app/watch/%5Bid%5D/page.tsx"
click node_player "https://github.com/slavakuntsov/flowix/blob/main/frontend/src/components/VideoPlayer.tsx"
click node_api "https://github.com/slavakuntsov/flowix/blob/main/frontend/src/lib/api.ts"
click node_gateway "https://github.com/slavakuntsov/flowix/blob/main/services/gateway/cmd/server/main.go"
click node_authrouter "https://github.com/slavakuntsov/flowix/blob/main/services/auth/src/routers/auth.py"
click node_authapp "https://github.com/slavakuntsov/flowix/blob/main/services/auth/src/main.py"
click node_authsecurity "https://github.com/slavakuntsov/flowix/blob/main/services/auth/src/core/security.py"
click node_tokenstore "https://github.com/slavakuntsov/flowix/blob/main/services/auth/src/core/tokenstore.py"
click node_authdb "https://github.com/slavakuntsov/flowix/blob/main/services/auth/src/core/db.py"
click node_upload "https://github.com/slavakuntsov/flowix/tree/main/services/upload/internal/handler"
click node_publisher "https://github.com/slavakuntsov/flowix/blob/main/services/upload/internal/queue/publisher.go"
click node_transcoder "https://github.com/slavakuntsov/flowix/blob/main/services/transcoder/app/consumer.py"
click node_metadata "https://github.com/slavakuntsov/flowix/blob/main/services/metadata/internal/handler/video.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_home,node_authpages,node_uploadui,node_watch,node_player,node_api,node_viewer toneBlue
class node_gateway toneAmber
class node_authrouter,node_authapp,node_authsecurity,node_tokenstore,node_authdb toneMint
class node_upload,node_publisher,node_transcoder,node_metadata toneRose
class node_minio,node_rabbitmq,node_postgres,node_vod toneIndigo
```

## Components

### Web application

- [Video catalog](https://github.com/slavakuntsov/flowix/blob/main/frontend/src/app/page.tsx): `frontend/src/app/page.tsx`
- [Login and registration](https://github.com/slavakuntsov/flowix/blob/main/frontend/src/app/login/page.tsx): `frontend/src/app/login/page.tsx`
- [Upload interface](https://github.com/slavakuntsov/flowix/blob/main/frontend/src/app/upload/page.tsx): `frontend/src/app/upload/page.tsx`
- [Watch page](https://github.com/slavakuntsov/flowix/blob/main/frontend/src/app/watch/%5Bid%5D/page.tsx): `frontend/src/app/watch/[id]/page.tsx`
- [HLS player](https://github.com/slavakuntsov/flowix/blob/main/frontend/src/components/VideoPlayer.tsx): `frontend/src/components/VideoPlayer.tsx`
- [API client](https://github.com/slavakuntsov/flowix/blob/main/frontend/src/lib/api.ts): `frontend/src/lib/api.ts`

### API gateway

- [Route and proxy](https://github.com/slavakuntsov/flowix/blob/main/services/gateway/cmd/server/main.go): `services/gateway/cmd/server/main.go`

### Identity service

- [Auth endpoints](https://github.com/slavakuntsov/flowix/blob/main/services/auth/src/routers/auth.py): `services/auth/src/routers/auth.py`
- [Auth application](https://github.com/slavakuntsov/flowix/blob/main/services/auth/src/main.py): `services/auth/src/main.py`
- [Passwords and tokens](https://github.com/slavakuntsov/flowix/blob/main/services/auth/src/core/security.py): `services/auth/src/core/security.py`
- [Refresh-token store](https://github.com/slavakuntsov/flowix/blob/main/services/auth/src/core/tokenstore.py): `services/auth/src/core/tokenstore.py`
- [User database access](https://github.com/slavakuntsov/flowix/blob/main/services/auth/src/core/db.py): `services/auth/src/core/db.py`

### Video services

- [Video upload service](https://github.com/slavakuntsov/flowix/tree/main/services/upload/internal/handler): `services/upload/internal/handler`
- [Upload event publisher](https://github.com/slavakuntsov/flowix/blob/main/services/upload/internal/queue/publisher.go): `services/upload/internal/queue/publisher.go`
- [Transcoding worker](https://github.com/slavakuntsov/flowix/blob/main/services/transcoder/app/consumer.py): `services/transcoder/app/consumer.py`
- [Video metadata API](https://github.com/slavakuntsov/flowix/blob/main/services/metadata/internal/handler/video.go): `services/metadata/internal/handler/video.go`

### Storage and delivery

- **Object storage**
- **Upload queue**
- **Postgres**
- **nginx-vod**

### Other components

- **Viewer or uploader**

## Connections

- Viewer or uploader → Video catalog: browses (evidence: `README.md`)
- Viewer or uploader → Login and registration: signs in (evidence: `README.md`)
- Viewer or uploader → Upload interface: uploads video (evidence: `README.md`)
- Viewer or uploader → Watch page: watches video (evidence: `README.md`)
- Video catalog → API client: requests videos
- Login and registration → API client: requests auth
- Upload interface → API client: submits upload
- Watch page → API client: requests metadata
- Watch page → HLS player: renders player
- HLS player → nginx-vod: loads HLS (evidence: `README.md`)
- API client → Route and proxy: calls API (evidence: `README.md`)
- Route and proxy → Auth application: proxies auth (evidence: `services/gateway/cmd/server/main.go`)
- Route and proxy → Video upload service: proxies upload (evidence: `services/gateway/cmd/server/main.go`)
- Route and proxy → Video metadata API: proxies metadata (evidence: `services/gateway/cmd/server/main.go`)
- Route and proxy → nginx-vod: proxies HLS (evidence: `services/gateway/cmd/server/main.go`)
- Auth application → Auth endpoints: registers routes (evidence: `services/auth/src/main.py`)
- Auth endpoints → User database access: queries users (evidence: `services/auth/src/routers/auth.py`)
- Auth endpoints → Passwords and tokens: verifies and signs (evidence: `services/auth/src/routers/auth.py`)
- Auth endpoints → Refresh-token store: rotates tokens (evidence: `services/auth/src/routers/auth.py`)
- Video upload service → Object storage: stores raw video (evidence: `README.md`)
- Video upload service → Upload event publisher: publishes event (evidence: `README.md`)
- Upload event publisher → Upload queue: sends upload event (evidence: `README.md`)
- Upload queue → Transcoding worker: dispatches event (evidence: `README.md`)
- Transcoding worker → Object storage: writes renditions (evidence: `README.md`)
- Transcoding worker → Video metadata API: marks ready (evidence: `README.md`)
- Video metadata API → Postgres: reads and writes (evidence: `README.md`)
- Video metadata API → Object storage: deletes objects (evidence: `README.md`)
- nginx-vod → Object storage: packages renditions (evidence: `README.md`)
- nginx-vod → Video metadata API: reads video mapping (evidence: `README.md`)
