# synctv-org/synctv architecture

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

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

## Overview

SyncTV is a real-time synchronized video-watching platform. A client or administrator uses its HTTP, gRPC, or WebSocket surfaces to authenticate, manage rooms and media, and coordinate playback; realtime services distribute room events, while provider integrations supply playable media. The product also supports live publishing and playback, file storage, and clustered operation. The graph combines documented capabilities with relationships visible in sampled source references; several feature implementations were not sampled, so their connections are shown only where documented or left unlinked.

Main entry points: [`synctv-api-common/src/impls/admin.rs`](https://github.com/synctv-org/synctv/blob/main/synctv-api-common/src/impls/admin.rs) (API implementations), [`synctv/src/app.rs`](https://github.com/synctv-org/synctv/blob/main/synctv/src/app.rs) (Application startup), [`synctv-api-http/src/http/mod.rs`](https://github.com/synctv-org/synctv/blob/main/synctv-api-http/src/http/mod.rs) (HTTP API), [`synctv-api-grpc/src/grpc/mod.rs`](https://github.com/synctv-org/synctv/blob/main/synctv-api-grpc/src/grpc/mod.rs) (gRPC API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["API surfaces"]
  node_http["HTTP API<br/>[mod.rs]"]
  node_grpc["gRPC API<br/>[mod.rs]"]
  node_common["API implementations<br/>[admin.rs]"]
end

subgraph group_domain["Room and media"]
  node_room["Room operations<br/>[room.rs]"]
  node_playback["Playback operations<br/>[playback.rs]"]
  node_media["Media operations<br/>[media.rs]"]
  node_media_model["Media models<br/>[media.rs]"]
end

subgraph group_realtime["Realtime and live"]
  node_realtime_api["Messaging<br/>[messaging.rs]"]
  node_realtime["Realtime manager"]
  node_connections["Connection manager"]
  node_livestream["Livestream services"]
  node_rtmp["RTMP session<br/>[client_session.rs]"]
end

subgraph group_infra["Runtime and storage"]
  node_app["Application startup<br/>[app.rs]"]
  node_server["Server lifecycle<br/>[server.rs]"]
  node_cluster["Cluster discovery<br/>[node_registry.rs]"]
  node_cache["Tiered cache<br/>[tiered.rs]"]
  node_storage["File storage<br/>[file_storage.rs]"]
  node_file_repo[("File repository<br/>[file_storage.rs]")]
end

subgraph group_integrations["Providers"]
  node_providers["Provider adapters<br/>[mod.rs]"]
end

node_client(("Client"))
node_admin(("Administrator"))

node_client -->|"uses"| node_http
node_client -->|"uses"| node_grpc
node_admin -->|"uses"| node_http
node_admin -->|"uses"| node_grpc
node_http -.->|"dispatches"| node_common
node_grpc -.->|"dispatches"| node_common
node_common -.->|"delegates"| node_room
node_common -.->|"delegates"| node_playback
node_common -->|"delegates"| node_media
node_media -.->|"uses"| node_providers
node_room -.->|"publishes events"| node_realtime_api
node_realtime_api -->|"dispatches"| node_realtime
node_realtime -->|"manages connections"| node_connections
node_playback -.->|"uses"| node_media_model
node_app -->|"starts"| node_server
node_app -->|"initializes"| node_cluster
node_app -.->|"initializes"| node_cache
node_storage -.->|"persists metadata"| node_file_repo
node_client -->|"publishes or watches"| node_livestream
node_rtmp -.->|"feeds streams"| node_livestream

click node_http "https://github.com/synctv-org/synctv/blob/main/synctv-api-http/src/http/mod.rs"
click node_grpc "https://github.com/synctv-org/synctv/blob/main/synctv-api-grpc/src/grpc/mod.rs"
click node_common "https://github.com/synctv-org/synctv/blob/main/synctv-api-common/src/impls/admin.rs"
click node_room "https://github.com/synctv-org/synctv/blob/main/synctv-api-common/src/impls/client/room.rs"
click node_playback "https://github.com/synctv-org/synctv/blob/main/synctv-api-common/src/impls/playback.rs"
click node_media "https://github.com/synctv-org/synctv/blob/main/synctv-api-common/src/impls/client/media.rs"
click node_providers "https://github.com/synctv-org/synctv/blob/main/synctv-core/src/provider/mod.rs"
click node_realtime_api "https://github.com/synctv-org/synctv/blob/main/synctv-api-common/src/impls/messaging.rs"
click node_realtime "https://github.com/synctv-org/synctv/blob/main/synctv-realtime/src/sync/realtime_manager.rs"
click node_connections "https://github.com/synctv-org/synctv/blob/main/synctv-realtime/src/sync/connection_manager.rs"
click node_livestream "https://github.com/synctv-org/synctv/blob/main/synctv-livestream/src/livestream/external_publish_manager.rs"
click node_rtmp "https://github.com/synctv-org/synctv/blob/main/synctv-xiu/src/rtmp/session/client_session.rs"
click node_app "https://github.com/synctv-org/synctv/blob/main/synctv/src/app.rs"
click node_server "https://github.com/synctv-org/synctv/blob/main/synctv/src/server.rs"
click node_cluster "https://github.com/synctv-org/synctv/blob/main/synctv-cluster/src/discovery/node_registry.rs"
click node_cache "https://github.com/synctv-org/synctv/blob/main/synctv-core/src/cache/tiered.rs"
click node_storage "https://github.com/synctv-org/synctv/blob/main/synctv-core/src/service/file_storage.rs"
click node_file_repo "https://github.com/synctv-org/synctv/blob/main/synctv-core/src/repository/file_storage.rs"
click node_media_model "https://github.com/synctv-org/synctv/blob/main/synctv-core/src/models/media.rs"

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_http,node_grpc,node_common,node_client toneBlue
class node_room,node_playback,node_media,node_media_model toneAmber
class node_realtime_api,node_realtime,node_connections,node_livestream,node_rtmp toneMint
class node_app,node_server,node_cluster,node_cache,node_storage,node_file_repo toneRose
class node_providers,node_admin toneIndigo
```

## Components

### API surfaces

- [HTTP API](https://github.com/synctv-org/synctv/blob/main/synctv-api-http/src/http/mod.rs): `synctv-api-http/src/http/mod.rs`
- [gRPC API](https://github.com/synctv-org/synctv/blob/main/synctv-api-grpc/src/grpc/mod.rs): `synctv-api-grpc/src/grpc/mod.rs`
- [API implementations](https://github.com/synctv-org/synctv/blob/main/synctv-api-common/src/impls/admin.rs): `synctv-api-common/src/impls/admin.rs`

### Room and media

- [Room operations](https://github.com/synctv-org/synctv/blob/main/synctv-api-common/src/impls/client/room.rs): `synctv-api-common/src/impls/client/room.rs`
- [Playback operations](https://github.com/synctv-org/synctv/blob/main/synctv-api-common/src/impls/playback.rs): `synctv-api-common/src/impls/playback.rs`
- [Media operations](https://github.com/synctv-org/synctv/blob/main/synctv-api-common/src/impls/client/media.rs): `synctv-api-common/src/impls/client/media.rs`
- [Media models](https://github.com/synctv-org/synctv/blob/main/synctv-core/src/models/media.rs): `synctv-core/src/models/media.rs`

### Realtime and live

- [Messaging](https://github.com/synctv-org/synctv/blob/main/synctv-api-common/src/impls/messaging.rs): `synctv-api-common/src/impls/messaging.rs`
- [Realtime manager](https://github.com/synctv-org/synctv/blob/main/synctv-realtime/src/sync/realtime_manager.rs): `synctv-realtime/src/sync/realtime_manager.rs`
- [Connection manager](https://github.com/synctv-org/synctv/blob/main/synctv-realtime/src/sync/connection_manager.rs): `synctv-realtime/src/sync/connection_manager.rs`
- [Livestream services](https://github.com/synctv-org/synctv/blob/main/synctv-livestream/src/livestream/external_publish_manager.rs): `synctv-livestream/src/livestream/external_publish_manager.rs`
- [RTMP session](https://github.com/synctv-org/synctv/blob/main/synctv-xiu/src/rtmp/session/client_session.rs): `synctv-xiu/src/rtmp/session/client_session.rs`

### Runtime and storage

- [Application startup](https://github.com/synctv-org/synctv/blob/main/synctv/src/app.rs): `synctv/src/app.rs`
- [Server lifecycle](https://github.com/synctv-org/synctv/blob/main/synctv/src/server.rs): `synctv/src/server.rs`
- [Cluster discovery](https://github.com/synctv-org/synctv/blob/main/synctv-cluster/src/discovery/node_registry.rs): `synctv-cluster/src/discovery/node_registry.rs`
- [Tiered cache](https://github.com/synctv-org/synctv/blob/main/synctv-core/src/cache/tiered.rs): `synctv-core/src/cache/tiered.rs`
- [File storage](https://github.com/synctv-org/synctv/blob/main/synctv-core/src/service/file_storage.rs): `synctv-core/src/service/file_storage.rs`
- [File repository](https://github.com/synctv-org/synctv/blob/main/synctv-core/src/repository/file_storage.rs): `synctv-core/src/repository/file_storage.rs`

### Providers

- [Provider adapters](https://github.com/synctv-org/synctv/blob/main/synctv-core/src/provider/mod.rs): `synctv-core/src/provider/mod.rs`

### Other components

- **Client**
- **Administrator**

## Connections

- Client → HTTP API: uses (evidence: `README.md`)
- Client → gRPC API: uses (evidence: `README.md`)
- Administrator → HTTP API: uses (evidence: `README.md`)
- Administrator → gRPC API: uses (evidence: `README.md`)
- HTTP API → API implementations: dispatches
- gRPC API → API implementations: dispatches
- API implementations → Room operations: delegates
- API implementations → Playback operations: delegates (evidence: `synctv-api-common/src/impls/admin.rs`)
- API implementations → Media operations: delegates (evidence: `synctv-api-common/src/impls/admin.rs`)
- Media operations → Provider adapters: uses
- Room operations → Messaging: publishes events
- Messaging → Realtime manager: dispatches
- Realtime manager → Connection manager: manages connections (evidence: `synctv-realtime/src/sync/realtime_manager.rs`)
- Playback operations → Media models: uses
- Application startup → Server lifecycle: starts (evidence: `synctv/src/app.rs`)
- Application startup → Cluster discovery: initializes (evidence: `synctv/src/app.rs`)
- Application startup → Tiered cache: initializes
- File storage → File repository: persists metadata
- Client → Livestream services: publishes or watches (evidence: `README.md`)
- RTMP session → Livestream services: feeds streams
