# antar-project/truenas-orchestrator-api-poc architecture

> Architecture diagram of the GitHub repository antar-project/truenas-orchestrator-api-poc, 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/antar-project/truenas-orchestrator-api-poc
- Repository: https://github.com/antar-project/truenas-orchestrator-api-poc

## Overview

This is a six-service video ingestion, transcoding, and adaptive-streaming platform backed by TrueNAS. The main workflow authenticates a client, uploads a workspace-scoped video through video-service, encodes it asynchronously, indexes the resulting playlists, and serves playlists and segments. nas-orchestrator is the storage gateway; auth-service supplies JWTs and token validation, while notification-service delivers playlist-ready events. The README documents cross-service protocols and capabilities; unsampled service internals are represented only at the directory level, so some subsystem links are documented rather than source-verified.

Main entry points: [`auth-service/src/main/java/com/tamojit/authservice/service/AuthService.java`](https://github.com/antar-project/truenas-orchestrator-api-poc/blob/main/auth-service/src/main/java/com/tamojit/authservice/service/AuthService.java) (Identity service), [`video-service/src/main/java/com/tamojit/videoservice/service/VideoService.java`](https://github.com/antar-project/truenas-orchestrator-api-poc/blob/main/video-service/src/main/java/com/tamojit/videoservice/service/VideoService.java) (Upload workflow), [`encoding-service/src/main/java/com/tamojit/encodingservice/service/EncodingService.java`](https://github.com/antar-project/truenas-orchestrator-api-poc/blob/main/encoding-service/src/main/java/com/tamojit/encodingservice/service/EncodingService.java) (Encoding jobs), [`streaming-service/src/main/java/com/tamojit/streamingservice/service/PlaylistService.java`](https://github.com/antar-project/truenas-orchestrator-api-poc/blob/main/streaming-service/src/main/java/com/tamojit/streamingservice/service/PlaylistService.java) (Playlist index)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_identity["Identity"]
  node_auth_api["Auth endpoints"]
  node_auth_logic["Identity service<br/>[AuthService.java]"]
  node_jwt["JWT signing<br/>[JwtService.java]"]
  node_users["User records<br/>[User.java]"]
  node_auth_db[("Auth PostgreSQL")]
end

subgraph group_ingest["Ingest and Encode"]
  node_video_api["Video upload API"]
  node_video_work["Upload workflow<br/>[VideoService.java]"]
  node_video_nas["Video gRPC client"]
  node_encoder["Encoding jobs"]
  node_encode_nas["Encoder gRPC client"]
end

subgraph group_storage["NAS Storage"]
  node_nas_files["File operations<br/>[FileService.java]"]
  node_nas_file_api["File API"]
  node_nas_stream["Playlist and segment proxy"]
  node_smb["SMB storage client<br/>[SmbFileClient.java]"]
  node_truenas_api["TrueNAS provisioning"]
  node_bootstrap["Storage bootstrap"]
end

subgraph group_playback["Streaming"]
  node_stream_api["Stream endpoints"]
  node_stream_proxy["Playlist gRPC proxy"]
  node_playlist_index["Playlist index"]
  node_playlist_db[("Playlist PostgreSQL")]
end

subgraph group_notify["Notifications"]
  node_notifications["WebSocket delivery"]
  node_notify_consumer["Ready-event consumer"]
end

node_client(("Client / Player"))
node_redis[("Redis")]
node_kafka["Kafka"]
node_truenas[("TrueNAS / SMB")]

node_client -->|"register / login"| node_auth_api
node_auth_api -->|"handles auth"| node_auth_logic
node_auth_logic -->|"creates users"| node_users
node_auth_logic -->|"persists identity"| node_auth_db
node_auth_logic -->|"issues tokens"| node_jwt
node_client -->|"uploads video"| node_video_api
node_video_api -->|"delegates upload"| node_video_work
node_video_work -->|"uploads file"| node_video_nas
node_video_nas -->|"streams file"| node_nas_files
node_video_work -->|"publishes uploaded"| node_kafka
node_kafka -->|"delivers upload event"| node_encoder
node_encoder -->|"downloads / uploads"| node_encode_nas
node_encode_nas -->|"transfers encoded files"| node_nas_files
node_encoder -->|"publishes encoded"| node_kafka
node_nas_file_api -->|"handles file requests"| node_nas_files
node_nas_files -.->|"reads / writes"| node_smb
node_smb -->|"transfers files"| node_truenas
node_bootstrap -->|"provisions storage"| node_truenas_api
node_truenas_api -->|"configures pool / share"| node_truenas
node_bootstrap -->|"creates shared workspace"| node_smb
node_client -->|"requests playback"| node_stream_api
node_stream_api -->|"resolves playlist path"| node_redis
node_stream_api -->|"requests playlist"| node_stream_proxy
node_stream_proxy -->|"gets rewritten playlist"| node_nas_stream
node_nas_stream -->|"reads playlist / segments"| node_smb
node_kafka -->|"delivers encoded event"| node_playlist_index
node_playlist_index -->|"indexes playlist paths"| node_redis
node_playlist_index -->|"upserts / queries"| node_playlist_db
node_playlist_index -->|"publishes ready"| node_kafka
node_kafka -->|"delivers ready event"| node_notify_consumer
node_notify_consumer -.->|"pushes notification"| node_notifications
node_client -->|"opens WebSocket"| node_notifications
node_client -->|"fetches segments directly"| node_nas_stream
node_video_work -->|"fetches service token"| node_auth_api
node_encoder -->|"fetches service token"| node_auth_api

click node_auth_api "https://github.com/antar-project/truenas-orchestrator-api-poc/blob/main/auth-service/src/main/java/com/tamojit/authservice/controller/AuthController.java"
click node_auth_logic "https://github.com/antar-project/truenas-orchestrator-api-poc/blob/main/auth-service/src/main/java/com/tamojit/authservice/service/AuthService.java"
click node_jwt "https://github.com/antar-project/truenas-orchestrator-api-poc/blob/main/auth-service/src/main/java/com/tamojit/authservice/security/JwtService.java"
click node_users "https://github.com/antar-project/truenas-orchestrator-api-poc/blob/main/auth-service/src/main/java/com/tamojit/authservice/model/User.java"
click node_video_api "https://github.com/antar-project/truenas-orchestrator-api-poc/blob/main/video-service/src/main/java/com/tamojit/videoservice/controller/VideoController.java"
click node_video_work "https://github.com/antar-project/truenas-orchestrator-api-poc/blob/main/video-service/src/main/java/com/tamojit/videoservice/service/VideoService.java"
click node_video_nas "https://github.com/antar-project/truenas-orchestrator-api-poc/blob/main/video-service/src/main/java/com/tamojit/videoservice/client/NasOrchestratorClient.java"
click node_encoder "https://github.com/antar-project/truenas-orchestrator-api-poc/blob/main/encoding-service/src/main/java/com/tamojit/encodingservice/service/EncodingService.java"
click node_encode_nas "https://github.com/antar-project/truenas-orchestrator-api-poc/blob/main/encoding-service/src/main/java/com/tamojit/encodingservice/client/NasOrchestratorClient.java"
click node_nas_files "https://github.com/antar-project/truenas-orchestrator-api-poc/blob/main/nas-orchestrator/src/main/java/com/tamojit/nasorchestrator/service/FileService.java"
click node_nas_file_api "https://github.com/antar-project/truenas-orchestrator-api-poc/blob/main/nas-orchestrator/src/main/java/com/tamojit/nasorchestrator/controller/FileController.java"
click node_nas_stream "https://github.com/antar-project/truenas-orchestrator-api-poc/blob/main/nas-orchestrator/src/main/java/com/tamojit/nasorchestrator/service/StreamingService.java"
click node_smb "https://github.com/antar-project/truenas-orchestrator-api-poc/blob/main/nas-orchestrator/src/main/java/com/tamojit/nasorchestrator/client/SmbFileClient.java"
click node_truenas_api "https://github.com/antar-project/truenas-orchestrator-api-poc/blob/main/nas-orchestrator/src/main/java/com/tamojit/nasorchestrator/client/TrueNasStorageClient.java"
click node_bootstrap "https://github.com/antar-project/truenas-orchestrator-api-poc/blob/main/nas-orchestrator/src/main/java/com/tamojit/nasorchestrator/service/StorageBoostrapService.java"
click node_stream_api "https://github.com/antar-project/truenas-orchestrator-api-poc/blob/main/streaming-service/src/main/java/com/tamojit/streamingservice/controller/StreamingController.java"
click node_stream_proxy "https://github.com/antar-project/truenas-orchestrator-api-poc/blob/main/streaming-service/src/main/java/com/tamojit/streamingservice/service/StreamingService.java"
click node_playlist_index "https://github.com/antar-project/truenas-orchestrator-api-poc/blob/main/streaming-service/src/main/java/com/tamojit/streamingservice/service/PlaylistService.java"
click node_notifications "https://github.com/antar-project/truenas-orchestrator-api-poc/blob/main/notification-service/src/main/java/com/tamojit/notificationservice/websocket/NotificationWebSocketHandler.java"
click node_notify_consumer "https://github.com/antar-project/truenas-orchestrator-api-poc/blob/main/notification-service/src/main/java/com/tamojit/notificationservice/service/PlaylistReadyConsumer.java"

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_auth_api,node_auth_logic,node_jwt,node_users,node_auth_db,node_client toneBlue
class node_video_api,node_video_work,node_video_nas,node_encoder,node_encode_nas,node_redis,node_truenas toneAmber
class node_nas_files,node_nas_file_api,node_nas_stream,node_smb,node_truenas_api,node_bootstrap toneMint
class node_stream_api,node_stream_proxy,node_playlist_index,node_playlist_db toneRose
class node_notifications,node_notify_consumer,node_kafka toneIndigo
```

## Components

### Identity

- [Auth endpoints](https://github.com/antar-project/truenas-orchestrator-api-poc/blob/main/auth-service/src/main/java/com/tamojit/authservice/controller/AuthController.java): `auth-service/src/main/java/com/tamojit/authservice/controller/AuthController.java`
- [Identity service](https://github.com/antar-project/truenas-orchestrator-api-poc/blob/main/auth-service/src/main/java/com/tamojit/authservice/service/AuthService.java): `auth-service/src/main/java/com/tamojit/authservice/service/AuthService.java`
- [JWT signing](https://github.com/antar-project/truenas-orchestrator-api-poc/blob/main/auth-service/src/main/java/com/tamojit/authservice/security/JwtService.java): `auth-service/src/main/java/com/tamojit/authservice/security/JwtService.java`
- [User records](https://github.com/antar-project/truenas-orchestrator-api-poc/blob/main/auth-service/src/main/java/com/tamojit/authservice/model/User.java): `auth-service/src/main/java/com/tamojit/authservice/model/User.java`
- **Auth PostgreSQL**

### Ingest and Encode

- [Video upload API](https://github.com/antar-project/truenas-orchestrator-api-poc/blob/main/video-service/src/main/java/com/tamojit/videoservice/controller/VideoController.java): `video-service/src/main/java/com/tamojit/videoservice/controller/VideoController.java`
- [Upload workflow](https://github.com/antar-project/truenas-orchestrator-api-poc/blob/main/video-service/src/main/java/com/tamojit/videoservice/service/VideoService.java): `video-service/src/main/java/com/tamojit/videoservice/service/VideoService.java`
- [Video gRPC client](https://github.com/antar-project/truenas-orchestrator-api-poc/blob/main/video-service/src/main/java/com/tamojit/videoservice/client/NasOrchestratorClient.java): `video-service/src/main/java/com/tamojit/videoservice/client/NasOrchestratorClient.java`
- [Encoding jobs](https://github.com/antar-project/truenas-orchestrator-api-poc/blob/main/encoding-service/src/main/java/com/tamojit/encodingservice/service/EncodingService.java): `encoding-service/src/main/java/com/tamojit/encodingservice/service/EncodingService.java`
- [Encoder gRPC client](https://github.com/antar-project/truenas-orchestrator-api-poc/blob/main/encoding-service/src/main/java/com/tamojit/encodingservice/client/NasOrchestratorClient.java): `encoding-service/src/main/java/com/tamojit/encodingservice/client/NasOrchestratorClient.java`

### NAS Storage

- [File operations](https://github.com/antar-project/truenas-orchestrator-api-poc/blob/main/nas-orchestrator/src/main/java/com/tamojit/nasorchestrator/service/FileService.java): `nas-orchestrator/src/main/java/com/tamojit/nasorchestrator/service/FileService.java`
- [File API](https://github.com/antar-project/truenas-orchestrator-api-poc/blob/main/nas-orchestrator/src/main/java/com/tamojit/nasorchestrator/controller/FileController.java): `nas-orchestrator/src/main/java/com/tamojit/nasorchestrator/controller/FileController.java`
- [Playlist and segment proxy](https://github.com/antar-project/truenas-orchestrator-api-poc/blob/main/nas-orchestrator/src/main/java/com/tamojit/nasorchestrator/service/StreamingService.java): `nas-orchestrator/src/main/java/com/tamojit/nasorchestrator/service/StreamingService.java`
- [SMB storage client](https://github.com/antar-project/truenas-orchestrator-api-poc/blob/main/nas-orchestrator/src/main/java/com/tamojit/nasorchestrator/client/SmbFileClient.java): `nas-orchestrator/src/main/java/com/tamojit/nasorchestrator/client/SmbFileClient.java`
- [TrueNAS provisioning](https://github.com/antar-project/truenas-orchestrator-api-poc/blob/main/nas-orchestrator/src/main/java/com/tamojit/nasorchestrator/client/TrueNasStorageClient.java): `nas-orchestrator/src/main/java/com/tamojit/nasorchestrator/client/TrueNasStorageClient.java`
- [Storage bootstrap](https://github.com/antar-project/truenas-orchestrator-api-poc/blob/main/nas-orchestrator/src/main/java/com/tamojit/nasorchestrator/service/StorageBoostrapService.java): `nas-orchestrator/src/main/java/com/tamojit/nasorchestrator/service/StorageBoostrapService.java`

### Streaming

- [Stream endpoints](https://github.com/antar-project/truenas-orchestrator-api-poc/blob/main/streaming-service/src/main/java/com/tamojit/streamingservice/controller/StreamingController.java): `streaming-service/src/main/java/com/tamojit/streamingservice/controller/StreamingController.java`
- [Playlist gRPC proxy](https://github.com/antar-project/truenas-orchestrator-api-poc/blob/main/streaming-service/src/main/java/com/tamojit/streamingservice/service/StreamingService.java): `streaming-service/src/main/java/com/tamojit/streamingservice/service/StreamingService.java`
- [Playlist index](https://github.com/antar-project/truenas-orchestrator-api-poc/blob/main/streaming-service/src/main/java/com/tamojit/streamingservice/service/PlaylistService.java): `streaming-service/src/main/java/com/tamojit/streamingservice/service/PlaylistService.java`
- **Playlist PostgreSQL**

### Notifications

- [WebSocket delivery](https://github.com/antar-project/truenas-orchestrator-api-poc/blob/main/notification-service/src/main/java/com/tamojit/notificationservice/websocket/NotificationWebSocketHandler.java): `notification-service/src/main/java/com/tamojit/notificationservice/websocket/NotificationWebSocketHandler.java`
- [Ready-event consumer](https://github.com/antar-project/truenas-orchestrator-api-poc/blob/main/notification-service/src/main/java/com/tamojit/notificationservice/service/PlaylistReadyConsumer.java): `notification-service/src/main/java/com/tamojit/notificationservice/service/PlaylistReadyConsumer.java`

### Other components

- **Client / Player**
- **Redis**
- **Kafka**
- **TrueNAS / SMB**

## Connections

- Client / Player → Auth endpoints: register / login
- Auth endpoints → Identity service: handles auth (evidence: `auth-service/src/main/java/com/tamojit/authservice/controller/AuthController.java`)
- Identity service → User records: creates users (evidence: `auth-service/src/main/java/com/tamojit/authservice/service/AuthService.java`)
- Identity service → Auth PostgreSQL: persists identity
- Identity service → JWT signing: issues tokens (evidence: `auth-service/src/main/java/com/tamojit/authservice/service/AuthService.java`)
- Client / Player → Video upload API: uploads video
- Video upload API → Upload workflow: delegates upload (evidence: `video-service/src/main/java/com/tamojit/videoservice/controller/VideoController.java`)
- Upload workflow → Video gRPC client: uploads file (evidence: `video-service/src/main/java/com/tamojit/videoservice/service/VideoService.java`)
- Video gRPC client → File operations: streams file
- Upload workflow → Kafka: publishes uploaded (evidence: `video-service/src/main/java/com/tamojit/videoservice/service/VideoService.java`)
- Kafka → Encoding jobs: delivers upload event
- Encoding jobs → Encoder gRPC client: downloads / uploads (evidence: `encoding-service/src/main/java/com/tamojit/encodingservice/service/EncodingService.java`)
- Encoder gRPC client → File operations: transfers encoded files
- Encoding jobs → Kafka: publishes encoded
- File API → File operations: handles file requests (evidence: `nas-orchestrator/src/main/java/com/tamojit/nasorchestrator/controller/FileController.java`)
- File operations → SMB storage client: reads / writes (evidence: `nas-orchestrator/src/main/java/com/tamojit/nasorchestrator/service/FileService.java`)
- SMB storage client → TrueNAS / SMB: transfers files
- Storage bootstrap → TrueNAS provisioning: provisions storage (evidence: `nas-orchestrator/src/main/java/com/tamojit/nasorchestrator/service/StorageBoostrapService.java`)
- TrueNAS provisioning → TrueNAS / SMB: configures pool / share
- Storage bootstrap → SMB storage client: creates shared workspace (evidence: `nas-orchestrator/src/main/java/com/tamojit/nasorchestrator/service/StorageBoostrapService.java`)
- Client / Player → Stream endpoints: requests playback
- Stream endpoints → Redis: resolves playlist path (evidence: `streaming-service/src/main/java/com/tamojit/streamingservice/controller/StreamingController.java`)
- Stream endpoints → Playlist gRPC proxy: requests playlist (evidence: `streaming-service/src/main/java/com/tamojit/streamingservice/controller/StreamingController.java`)
- Playlist gRPC proxy → Playlist and segment proxy: gets rewritten playlist (evidence: `streaming-service/src/main/java/com/tamojit/streamingservice/service/StreamingService.java`)
- Playlist and segment proxy → SMB storage client: reads playlist / segments (evidence: `nas-orchestrator/src/main/java/com/tamojit/nasorchestrator/service/StreamingService.java`)
- Kafka → Playlist index: delivers encoded event
- Playlist index → Redis: indexes playlist paths
- Playlist index → Playlist PostgreSQL: upserts / queries (evidence: `streaming-service/src/main/java/com/tamojit/streamingservice/service/PlaylistService.java`)
- Playlist index → Kafka: publishes ready
- Kafka → Ready-event consumer: delivers ready event
- Ready-event consumer → WebSocket delivery: pushes notification
- Client / Player → WebSocket delivery: opens WebSocket
- Client / Player → Playlist and segment proxy: fetches segments directly
- Upload workflow → Auth endpoints: fetches service token
- Encoding jobs → Auth endpoints: fetches service token
