# go-masterskaya/media-service architecture

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

- Interactive diagram: https://gitdiagram.com/go-masterskaya/media-service
- Repository: https://github.com/go-masterskaya/media-service

## Overview

Media Service stores owner-associated media, streams uploads, persists metadata, and serves downloads through gRPC or an embeddable Go client. The main service path validates and stages uploads, probes media, stores originals, then queues thumbnail/transcode work; callers retrieve metadata or stream/download variants. Postgres holds metadata and jobs while MinIO holds binaries. Reconciliation, expiration cleanup, and optional Kafka event handling are separate operational branches. Relationships are limited to calls or dependencies evidenced by excerpts, the source index, or README; several unsampled internals are therefore not linked in detail.

Main entry points: [`cmd/mediaservice/main.go`](https://github.com/go-masterskaya/media-service/blob/main/cmd/mediaservice/main.go) (Service Runtime), [`internal/media/service.go`](https://github.com/go-masterskaya/media-service/blob/main/internal/media/service.go) (Media Service), [`internal/storage/minio.go`](https://github.com/go-masterskaya/media-service/blob/main/internal/storage/minio.go) (MinIO Adapter), [`internal/repo/media.go`](https://github.com/go-masterskaya/media-service/blob/main/internal/repo/media.go) (Postgres Repositories)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_access["Access Interfaces"]
  node_main["Service Runtime<br/>[main.go]"]
  node_grpc_api["gRPC API<br/>[media.go]"]
  node_grpc_upload["Upload Stream<br/>[upload.go]"]
  node_health["Health Probes<br/>[health.go]"]
  node_go_client["Go Client<br/>[client.go]"]
  node_go_media["Client Media API<br/>[media.go]"]
  node_proto["Media Contract<br/>[media.proto]"]
end

subgraph group_domain["Media Domain"]
  node_media_service["Media Service<br/>[service.go]"]
  node_media_upload["Upload Pipeline<br/>[upload.go]"]
  node_delete["Deletion<br/>[delete.go]"]
  node_reaper["Expiration Reaper<br/>[reaper.go]"]
  node_reconcile["Storage Reconciler<br/>[reconciler.go]"]
  node_temp_upload["Temporary Uploads<br/>[tempstore.go]"]
end

subgraph group_processing["Media Processing"]
  node_engine["Job Engine<br/>[engine.go]"]
  node_thumbnail["Thumbnail Handler"]
  node_transcode["Transcode Handler"]
end

subgraph group_persistence["Persistence"]
  node_postgres[("Postgres")]
  node_pg_repos["Postgres Repositories<br/>[media.go]"]
  node_minio_adapter["MinIO Adapter<br/>[minio.go]"]
end

subgraph group_operations["Operations and Events"]
  node_events_consumer["Kafka Consumer<br/>[kafka_consumer.go]"]
  node_events_handler["Event Handler<br/>[handler.go]"]
  node_config["Configuration<br/>[config.go]"]
end

node_grpc_caller(("gRPC Caller"))
node_go_app(("Embedding App"))
node_minio[("MinIO")]
node_ffmpeg["FFmpeg"]
node_kafka["Kafka"]

node_grpc_caller -->|"calls RPCs"| node_grpc_api
node_grpc_caller -->|"streams upload"| node_grpc_upload
node_grpc_api -->|"implements contract"| node_proto
node_grpc_upload -->|"calls upload"| node_media_upload
node_grpc_api -->|"calls domain"| node_media_service
node_main -->|"registers server"| node_grpc_api
node_main -.->|"starts probes"| node_health
node_main -->|"loads config"| node_config
node_main -.->|"constructs service"| node_media_service
node_main -->|"starts engine"| node_engine
node_main -->|"starts optionally"| node_events_consumer
node_main -->|"starts reaper"| node_reaper
node_main -->|"starts reconciler"| node_reconcile
node_go_app -->|"uses library"| node_go_client
node_go_client -->|"constructs core"| node_media_service
node_go_media -->|"delegates media calls"| node_media_service
node_media_service -->|"reads and writes"| node_pg_repos
node_media_service -->|"accesses objects"| node_minio_adapter
node_media_upload -->|"stages chunks"| node_temp_upload
node_media_upload -.->|"queues processing"| node_engine
node_engine -.->|"dispatches jobs"| node_thumbnail
node_engine -.->|"dispatches jobs"| node_transcode
node_thumbnail -->|"reads source"| node_minio_adapter
node_thumbnail -->|"generates thumbnail"| node_ffmpeg
node_transcode -->|"transcodes media"| node_ffmpeg
node_transcode -->|"stores derivative"| node_minio_adapter
node_events_consumer -.->|"consumes events"| node_kafka
node_events_consumer -.->|"dispatches records"| node_events_handler
node_events_handler -->|"tracks processing"| node_pg_repos
node_delete -->|"updates records"| node_pg_repos
node_delete -->|"deletes objects"| node_minio_adapter
node_reconcile -->|"checks records"| node_pg_repos
node_reconcile -->|"checks objects"| node_minio_adapter
node_reaper -.->|"expires media"| node_media_service
node_pg_repos -->|"persists metadata"| node_postgres
node_minio_adapter -->|"stores binaries"| node_minio

click node_main "https://github.com/go-masterskaya/media-service/blob/main/cmd/mediaservice/main.go"
click node_grpc_api "https://github.com/go-masterskaya/media-service/blob/main/internal/api/media.go"
click node_grpc_upload "https://github.com/go-masterskaya/media-service/blob/main/internal/api/upload.go"
click node_health "https://github.com/go-masterskaya/media-service/blob/main/internal/api/health.go"
click node_go_client "https://github.com/go-masterskaya/media-service/blob/main/pkg/mediaservice/client.go"
click node_go_media "https://github.com/go-masterskaya/media-service/blob/main/pkg/mediaservice/media.go"
click node_proto "https://github.com/go-masterskaya/media-service/blob/main/proto/media/v1/media.proto"
click node_media_service "https://github.com/go-masterskaya/media-service/blob/main/internal/media/service.go"
click node_media_upload "https://github.com/go-masterskaya/media-service/blob/main/internal/media/upload.go"
click node_delete "https://github.com/go-masterskaya/media-service/blob/main/internal/media/delete.go"
click node_reaper "https://github.com/go-masterskaya/media-service/blob/main/internal/media/reaper.go"
click node_reconcile "https://github.com/go-masterskaya/media-service/blob/main/internal/media/reconciler.go"
click node_temp_upload "https://github.com/go-masterskaya/media-service/blob/main/internal/upload/tempstore.go"
click node_engine "https://github.com/go-masterskaya/media-service/blob/main/internal/processing/engine.go"
click node_thumbnail "https://github.com/go-masterskaya/media-service/blob/main/internal/processing/handler_thumbnail.go"
click node_transcode "https://github.com/go-masterskaya/media-service/blob/main/internal/processing/handler_transcode.go"
click node_events_consumer "https://github.com/go-masterskaya/media-service/blob/main/internal/events/kafka_consumer.go"
click node_events_handler "https://github.com/go-masterskaya/media-service/blob/main/internal/events/handler.go"
click node_pg_repos "https://github.com/go-masterskaya/media-service/blob/main/internal/repo/media.go"
click node_minio_adapter "https://github.com/go-masterskaya/media-service/blob/main/internal/storage/minio.go"
click node_config "https://github.com/go-masterskaya/media-service/blob/main/internal/config/config.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_main,node_grpc_api,node_grpc_upload,node_health,node_go_client,node_go_media,node_proto toneBlue
class node_media_service,node_media_upload,node_delete,node_reaper,node_reconcile,node_temp_upload,node_minio toneAmber
class node_engine,node_thumbnail,node_transcode toneMint
class node_postgres,node_pg_repos,node_minio_adapter toneRose
class node_events_consumer,node_events_handler,node_config,node_grpc_caller,node_go_app,node_ffmpeg,node_kafka toneIndigo
```

## Components

### Access Interfaces

- [Service Runtime](https://github.com/go-masterskaya/media-service/blob/main/cmd/mediaservice/main.go): `cmd/mediaservice/main.go`
- [gRPC API](https://github.com/go-masterskaya/media-service/blob/main/internal/api/media.go): `internal/api/media.go`
- [Upload Stream](https://github.com/go-masterskaya/media-service/blob/main/internal/api/upload.go): `internal/api/upload.go`
- [Health Probes](https://github.com/go-masterskaya/media-service/blob/main/internal/api/health.go): `internal/api/health.go`
- [Go Client](https://github.com/go-masterskaya/media-service/blob/main/pkg/mediaservice/client.go): `pkg/mediaservice/client.go`
- [Client Media API](https://github.com/go-masterskaya/media-service/blob/main/pkg/mediaservice/media.go): `pkg/mediaservice/media.go`
- [Media Contract](https://github.com/go-masterskaya/media-service/blob/main/proto/media/v1/media.proto): `proto/media/v1/media.proto`

### Media Domain

- [Media Service](https://github.com/go-masterskaya/media-service/blob/main/internal/media/service.go): `internal/media/service.go`
- [Upload Pipeline](https://github.com/go-masterskaya/media-service/blob/main/internal/media/upload.go): `internal/media/upload.go`
- [Deletion](https://github.com/go-masterskaya/media-service/blob/main/internal/media/delete.go): `internal/media/delete.go`
- [Expiration Reaper](https://github.com/go-masterskaya/media-service/blob/main/internal/media/reaper.go): `internal/media/reaper.go`
- [Storage Reconciler](https://github.com/go-masterskaya/media-service/blob/main/internal/media/reconciler.go): `internal/media/reconciler.go`
- [Temporary Uploads](https://github.com/go-masterskaya/media-service/blob/main/internal/upload/tempstore.go): `internal/upload/tempstore.go`

### Media Processing

- [Job Engine](https://github.com/go-masterskaya/media-service/blob/main/internal/processing/engine.go): `internal/processing/engine.go`
- [Thumbnail Handler](https://github.com/go-masterskaya/media-service/blob/main/internal/processing/handler_thumbnail.go): `internal/processing/handler_thumbnail.go`
- [Transcode Handler](https://github.com/go-masterskaya/media-service/blob/main/internal/processing/handler_transcode.go): `internal/processing/handler_transcode.go`

### Persistence

- **Postgres**
- [Postgres Repositories](https://github.com/go-masterskaya/media-service/blob/main/internal/repo/media.go): `internal/repo/media.go`
- [MinIO Adapter](https://github.com/go-masterskaya/media-service/blob/main/internal/storage/minio.go): `internal/storage/minio.go`

### Operations and Events

- [Kafka Consumer](https://github.com/go-masterskaya/media-service/blob/main/internal/events/kafka_consumer.go): `internal/events/kafka_consumer.go`
- [Event Handler](https://github.com/go-masterskaya/media-service/blob/main/internal/events/handler.go): `internal/events/handler.go`
- [Configuration](https://github.com/go-masterskaya/media-service/blob/main/internal/config/config.go): `internal/config/config.go`

### Other components

- **gRPC Caller**
- **Embedding App**
- **MinIO**
- **FFmpeg**
- **Kafka**

## Connections

- gRPC Caller → gRPC API: calls RPCs (evidence: `README.md`)
- gRPC Caller → Upload Stream: streams upload (evidence: `README.md`)
- gRPC API → Media Contract: implements contract (evidence: `internal/api/media.go`)
- Upload Stream → Upload Pipeline: calls upload (evidence: `internal/api/upload.go`)
- gRPC API → Media Service: calls domain (evidence: `internal/api/media.go`)
- Service Runtime → gRPC API: registers server (evidence: `cmd/mediaservice/main.go`)
- Service Runtime → Health Probes: starts probes
- Service Runtime → Configuration: loads config (evidence: `cmd/mediaservice/main.go`)
- Service Runtime → Media Service: constructs service
- Service Runtime → Job Engine: starts engine (evidence: `cmd/mediaservice/main.go`)
- Service Runtime → Kafka Consumer: starts optionally (evidence: `cmd/mediaservice/main.go`)
- Service Runtime → Expiration Reaper: starts reaper (evidence: `cmd/mediaservice/main.go`)
- Service Runtime → Storage Reconciler: starts reconciler (evidence: `cmd/mediaservice/main.go`)
- Embedding App → Go Client: uses library (evidence: `README.md`)
- Go Client → Media Service: constructs core (evidence: `pkg/mediaservice/client.go`)
- Client Media API → Media Service: delegates media calls (evidence: `pkg/mediaservice/media.go`)
- Media Service → Postgres Repositories: reads and writes (evidence: `internal/media/service.go`)
- Media Service → MinIO Adapter: accesses objects (evidence: `internal/media/service.go`)
- Upload Pipeline → Temporary Uploads: stages chunks (evidence: `internal/media/upload.go`)
- Upload Pipeline → Job Engine: queues processing
- Job Engine → Thumbnail Handler: dispatches jobs
- Job Engine → Transcode Handler: dispatches jobs
- Thumbnail Handler → MinIO Adapter: reads source (evidence: `internal/processing/handler_thumbnail.go`)
- Thumbnail Handler → FFmpeg: generates thumbnail (evidence: `internal/processing/handler_thumbnail.go`)
- Transcode Handler → FFmpeg: transcodes media (evidence: `internal/processing/handler_transcode.go`)
- Transcode Handler → MinIO Adapter: stores derivative (evidence: `internal/processing/handler_transcode.go`)
- Kafka Consumer → Kafka: consumes events
- Kafka Consumer → Event Handler: dispatches records
- Event Handler → Postgres Repositories: tracks processing (evidence: `internal/events/handler.go`)
- Deletion → Postgres Repositories: updates records (evidence: `internal/media/delete.go`)
- Deletion → MinIO Adapter: deletes objects (evidence: `internal/media/delete.go`)
- Storage Reconciler → Postgres Repositories: checks records (evidence: `internal/media/reconciler.go`)
- Storage Reconciler → MinIO Adapter: checks objects (evidence: `internal/media/reconciler.go`)
- Expiration Reaper → Media Service: expires media
- Postgres Repositories → Postgres: persists metadata (evidence: `README.md`)
- MinIO Adapter → MinIO: stores binaries (evidence: `README.md`)
