# iv-org/invidious architecture

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

- Interactive diagram: https://gitdiagram.com/iv-org/invidious
- Repository: https://github.com/iv-org/invidious

## Overview

Invidious is a self-hostable alternative front end to YouTube. A visitor requests video, channel, search, or account features through the web application; the application presents results and can persist user data such as subscriptions and preferences. The README also documents comments, playlists, feeds and notifications, imports/exports, embedded playback, and a developer API. The tree identifies likely implementation areas, but the supplied source excerpts cover only a release script, so internal runtime calls and data flow cannot be verified; those relationships are omitted rather than inferred.

Main entry points: [`src/invidious/routes`](https://github.com/iv-org/invidious/tree/master/src/invidious/routes) (Web routes), [`src/invidious/user`](https://github.com/iv-org/invidious/tree/master/src/invidious/user) (Accounts and preferences), [`src/invidious/jobs`](https://github.com/iv-org/invidious/tree/master/src/invidious/jobs) (Background jobs), [`assets/js/player.js`](https://github.com/iv-org/invidious/blob/master/assets/js/player.js) (Video player)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web experience"]
  node_web_routes["Web routes"]
  node_frontend["Page rendering"]
  node_views["Page templates"]
  node_browser_player["Video player<br/>[player.js]"]
end

subgraph group_youtube["YouTube content"]
  node_search["Search"]
  node_video_content["Video content"]
  node_youtube_backend["YouTube access"]
  node_channels["Channels"]
  node_comments["Comments"]
  node_playlists["Playlists"]
end

subgraph group_accounts["User data"]
  node_database[("PostgreSQL")]
  node_user_data["Accounts and preferences"]
  node_imports_exports["Data import/export<br/>[imports.cr]"]
  node_subscriptions["Subscriptions<br/>[subscriptions.cr]"]
end

subgraph group_background["Feeds and API"]
  node_jobs["Background jobs"]
  node_feeds["Feeds and notifications"]
  node_api["Developer API"]
end

node_visitor(("Visitor"))
node_youtube_service(("YouTube"))

node_visitor -->|"requests pages"| node_web_routes
node_web_routes -.->|"serves YouTube content"| node_youtube_service
node_visitor -->|"uses API"| node_api
node_visitor -->|"plays embedded video"| node_browser_player
node_visitor -->|"manages preferences"| node_user_data
node_visitor -->|"subscribes to channels"| node_subscriptions
node_visitor -->|"imports or exports data"| node_imports_exports
node_visitor -->|"reads comments"| node_comments
node_visitor -->|"searches videos"| node_search
node_visitor -.->|"uses playlists"| node_playlists
node_jobs -.->|"refreshes feeds"| node_feeds
node_user_data -.->|"stores user data"| node_database

click node_web_routes "https://github.com/iv-org/invidious/tree/master/src/invidious/routes"
click node_frontend "https://github.com/iv-org/invidious/tree/master/src/invidious/frontend"
click node_views "https://github.com/iv-org/invidious/tree/master/src/invidious/views"
click node_browser_player "https://github.com/iv-org/invidious/blob/master/assets/js/player.js"
click node_search "https://github.com/iv-org/invidious/tree/master/src/invidious/search"
click node_video_content "https://github.com/iv-org/invidious/tree/master/src/invidious/videos"
click node_youtube_backend "https://github.com/iv-org/invidious/tree/master/src/invidious/yt_backend"
click node_channels "https://github.com/iv-org/invidious/tree/master/src/invidious/channels"
click node_comments "https://github.com/iv-org/invidious/tree/master/src/invidious/comments"
click node_playlists "https://github.com/iv-org/invidious/tree/master/src/invidious/playlists"
click node_database "https://github.com/iv-org/invidious/tree/master/src/invidious/database"
click node_user_data "https://github.com/iv-org/invidious/tree/master/src/invidious/user"
click node_imports_exports "https://github.com/iv-org/invidious/blob/master/src/invidious/user/imports.cr"
click node_subscriptions "https://github.com/iv-org/invidious/blob/master/src/invidious/routes/subscriptions.cr"
click node_jobs "https://github.com/iv-org/invidious/tree/master/src/invidious/jobs"
click node_feeds "https://github.com/iv-org/invidious/tree/master/src/invidious/feeds"
click node_api "https://github.com/iv-org/invidious/tree/master/src/invidious/routes/api/v1"

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_web_routes,node_frontend,node_views,node_browser_player toneBlue
class node_search,node_video_content,node_youtube_backend,node_channels,node_comments,node_playlists toneAmber
class node_database,node_user_data,node_imports_exports,node_subscriptions toneMint
class node_jobs,node_feeds,node_api toneRose
class node_visitor,node_youtube_service toneIndigo
```

## Components

### Web experience

- [Web routes](https://github.com/iv-org/invidious/tree/master/src/invidious/routes): `src/invidious/routes`
- [Page rendering](https://github.com/iv-org/invidious/tree/master/src/invidious/frontend): `src/invidious/frontend`
- [Page templates](https://github.com/iv-org/invidious/tree/master/src/invidious/views): `src/invidious/views`
- [Video player](https://github.com/iv-org/invidious/blob/master/assets/js/player.js): `assets/js/player.js`

### YouTube content

- [Search](https://github.com/iv-org/invidious/tree/master/src/invidious/search): `src/invidious/search`
- [Video content](https://github.com/iv-org/invidious/tree/master/src/invidious/videos): `src/invidious/videos`
- [YouTube access](https://github.com/iv-org/invidious/tree/master/src/invidious/yt_backend): `src/invidious/yt_backend`
- [Channels](https://github.com/iv-org/invidious/tree/master/src/invidious/channels): `src/invidious/channels`
- [Comments](https://github.com/iv-org/invidious/tree/master/src/invidious/comments): `src/invidious/comments`
- [Playlists](https://github.com/iv-org/invidious/tree/master/src/invidious/playlists): `src/invidious/playlists`

### User data

- [PostgreSQL](https://github.com/iv-org/invidious/tree/master/src/invidious/database): `src/invidious/database`
- [Accounts and preferences](https://github.com/iv-org/invidious/tree/master/src/invidious/user): `src/invidious/user`
- [Data import/export](https://github.com/iv-org/invidious/blob/master/src/invidious/user/imports.cr): `src/invidious/user/imports.cr`
- [Subscriptions](https://github.com/iv-org/invidious/blob/master/src/invidious/routes/subscriptions.cr): `src/invidious/routes/subscriptions.cr`

### Feeds and API

- [Background jobs](https://github.com/iv-org/invidious/tree/master/src/invidious/jobs): `src/invidious/jobs`
- [Feeds and notifications](https://github.com/iv-org/invidious/tree/master/src/invidious/feeds): `src/invidious/feeds`
- [Developer API](https://github.com/iv-org/invidious/tree/master/src/invidious/routes/api/v1): `src/invidious/routes/api/v1`

### Other components

- **Visitor**
- **YouTube**

## Connections

- Visitor → Web routes: requests pages (evidence: `README.md`)
- Web routes → YouTube: serves YouTube content
- Visitor → Developer API: uses API (evidence: `README.md`)
- Visitor → Video player: plays embedded video (evidence: `README.md`)
- Visitor → Accounts and preferences: manages preferences (evidence: `README.md`)
- Visitor → Subscriptions: subscribes to channels (evidence: `README.md`)
- Visitor → Data import/export: imports or exports data (evidence: `README.md`)
- Visitor → Comments: reads comments (evidence: `README.md`)
- Visitor → Search: searches videos (evidence: `README.md`)
- Visitor → Playlists: uses playlists
- Background jobs → Feeds and notifications: refreshes feeds
- Accounts and preferences → PostgreSQL: stores user data
