# yuorei/yuovision-server architecture

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

- Interactive diagram: https://gitdiagram.com/yuorei/yuovision-server
- Repository: https://github.com/yuorei/yuovision-server

## Overview

1. **High-level shape**
   - This is a Go backend for a video platform (“YuoVision”) built around **Clean Architecture**.
   - The main request path is **GraphQL API → application use cases → domain models → outbound ports → infrastructure adapters**.

2. **Primary entrypoints**
   - `main.go` is the process entry.
   - `app/driver/router` wires the HTTP server and routes, while `app/adapter/presentation/resolver` exposes the GraphQL surface generated by `gqlgen`.
   - The API is not a REST app; GraphQL is the main client-facing boundary.

3. **Presentation layer**
   - `graph/schema/*.graphqls` defines the public API contract for user, video, comment, auth, and node queries/mutations.
   - `app/adapter/presentation/resolver/*` contains the GraphQL resolvers that translate API requests into application calls.
   - This layer should be treated as thin orchestration: request parsing, response shaping, and resolver-to-usecase delegation.

4. **Application layer**
   - `app/application/*` contains the business workflows for users, videos, comments, and images.
   - `app/application/port/*` defines the interfaces the use cases depend on, so the application does not know concrete DB/storage implementations.
   - This is where upload flows, listing, retrieval, and content-related rules are coordinated.

5. **Domain layer**
   - `app/domain/*` holds core entities and value types such as user, video, comment, IDs, and UUID helpers.
   - `app/domain/models/models_gen.go` suggests generated model definitions are used to keep domain data structures consistent.
   - The domain layer is the dependency anchor: it should not depend on transport, DB, or cloud services.

6. **Infrastructure adapters**
   - `app/adapter/infrastructure/*` contains concrete implementations for external systems:
     - `firestore/*` for document-style persistence,
     - `image_r2.go` for object storage interaction,
     - `video_processing.go` and related files for media processing.
   - The tree also includes `app/driver/storage/r2.go`, `app/driver/firebase/*`, and `app/driver/pubsub/*`, indicating cloud/service clients are wrapped behind drivers and adapters.

7. **Persistence and storage boundaries**
   - The repository includes both `mongodb` collections under `app/driver/db/mongodb/collection` and Firestore adapters under `app/adapter/infrastructure/firestore`.
   - That suggests either multiple persistence backends or an evolution from one datastore to another; for diagramming, treat persistence as an interchangeable infrastructure boundary behind ports.
   - Object storage is separate from metadata storage: video/image binaries go to S3-compatible storage, while entity metadata is stored in databases.

8. **Video upload and streaming pipeline**
   - The README and filenames indicate a media pipeline centered on **upload → processing → HLS delivery**.
   - FFmpeg is used to transform uploaded video into streaming assets, and HLS is the delivery format for playback.
   - Files such as `video_processing.go`, `upload_video_for_storage.go`, and the test media files under `app/adapter/infrastructure/` support this pipeline.

9. **Authentication and authorization**
   - Authentication is handled in `app/adapter/middleware/auth.go` and `app/driver/firebase/auth.go`.
   - The presence of `public_key.pem` and Keycloak in the README suggests token verification / SSO-style identity integration at the edge.
   - Auth is a cross-cutting concern applied before resolvers invoke application logic.

10. **Operational drivers**
   - `app/driver/log/slog.go`, `app/driver/newrelic/newrelic.go`, and `app/driver/sentry/sentry.go` show observability concerns are centralized in drivers.
   - `app/driver/db/db.go`, `app/driver/router/http_router.go`, and `app/driver/storage/r2.go` are the runtime wiring layer for infrastructure clients.
   - These drivers are not business logic; they assemble external dependencies used by the application layer.

11. **Caching and async support**
   - The README mentions Redis caching for video lists, and the tree includes `app/driver/pubsub/client.go`.
   - That points to a design where expensive list/read operations can be cached, and some workflows may be event-driven or background-assisted.
   - For architecture diagrams, cache/pubsub should sit beside persistence as auxiliary infrastructure, not inside the domain.

12. **Build, deploy, and runtime packaging**
   - `Dockerfile`, `Dockerfile.dev`, `compose.yaml`, `kubernetes/*`, and GitHub Actions workflows indicate the service is containerized and deployable to both local Compose and Kubernetes.
   - The repo also includes CI/CD automation for tests, Docker image publishing, and deployment manifest updates.
   - This is important because the application is intended to run in a self-hosted/on-prem environment with external access via Cloudflare Tunnel, as described in the README.

13. **How the main data flow works**
   - A GraphQL request enters the router, passes middleware/auth, reaches a resolver, then calls an application use case through a port.
   - The use case reads/writes domain entities and delegates persistence, storage, or external service calls to infrastructure implementations.
   - For video upload, the flow extends to object storage plus processing, then the resulting playback assets are exposed back through GraphQL.

14. **Key diagram boundaries**
   - Draw four major zones: **API/presentation**, **application/use cases**, **domain**, and **infrastructure/drivers**.
   - Show external systems separately: **database**, **object storage**, **auth provider**, **observability**, and **media processing**.
   - The most important dependency rule is that inward layers do not depend on concrete infrastructure; only ports/interfaces point outward.

Main entry points: [`app/application/port/ports.go`](https://github.com/yuorei/yuovision-server/blob/main/app/application/port/ports.go) (Ports), [`app/application/video.go`](https://github.com/yuorei/yuovision-server/blob/main/app/application/video.go) (Video Use Cases), [`app/adapter/presentation/resolver/resolver.go`](https://github.com/yuorei/yuovision-server/blob/main/app/adapter/presentation/resolver/resolver.go) (Resolvers), [`app/application/user.go`](https://github.com/yuorei/yuovision-server/blob/main/app/application/user.go) (User Use Cases)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_presentation["API / Presentation"]
  node_auth_middleware["Auth Middleware<br/>edge auth<br/>[auth.go]"]
  node_graphql_schema["GraphQL Schema<br/>api contract<br/>[schema.graphqls]"]
  node_resolvers["Resolvers<br/>graphql handlers<br/>[resolver.go]"]
end

subgraph group_application["Application"]
  node_app_boot["App Setup<br/>composition root<br/>[app.go]"]
  node_user_uc["User Use Cases<br/>workflow<br/>[user.go]"]
  node_video_uc["Video Use Cases<br/>workflow<br/>[video.go]"]
  node_comment_uc["Comment Use Cases<br/>workflow<br/>[comment.go]"]
  node_image_uc["Image Use Cases<br/>workflow<br/>[image.go]"]
  node_ports["Ports<br/>interfaces<br/>[ports.go]"]
end

subgraph group_domain["Domain"]
  node_user_domain(("User Model<br/>entity<br/>[user.go]"))
  node_video_domain(("Video Model<br/>entity<br/>[video.go]"))
  node_comment_domain(("Comment Model<br/>entity<br/>[comment.go]"))
  node_ids{{"IDs & UUIDs<br/>value types<br/>[id.go]"}}
end

subgraph group_infrastructure["Infrastructure / Drivers"]
  node_main(("Main<br/>process entry<br/>[main.go]"))
  node_router["HTTP Router<br/>http wiring<br/>[http_router.go]"]
  node_firestore[("Firestore Adapters<br/>document persistence<br/>[video.go]")]
  node_object_storage[("R2 Storage<br/>object storage<br/>[r2.go]")]
  node_media_pipeline["Media Pipeline<br/>processing"]
  node_observability["Observability<br/>telemetry<br/>[slog.go]"]
  node_pubsub["Pub/Sub<br/>async bus<br/>[client.go]"]
end

subgraph group_external["External Systems"]
  node_firebase_auth{{"Firebase Auth<br/>identity provider<br/>[auth.go]"}}
  node_mongodb[("MongoDB<br/>database backend<br/>[video.go]")]
end

node_main -->|"starts"| node_router
node_main -->|"initializes"| node_app_boot
node_router -->|"applies"| node_auth_middleware
node_router -->|"serves"| node_resolvers
node_resolvers -.->|"implements"| node_graphql_schema
node_resolvers -->|"calls"| node_user_uc
node_resolvers -->|"calls"| node_video_uc
node_resolvers -->|"calls"| node_comment_uc
node_resolvers -->|"calls"| node_image_uc
node_app_boot -->|"wires"| node_ports
node_user_uc -->|"depends on"| node_ports
node_video_uc -->|"depends on"| node_ports
node_comment_uc -->|"depends on"| node_ports
node_image_uc -->|"depends on"| node_ports
node_ports -.->|"shares"| node_user_domain
node_ports -.->|"shares"| node_video_domain
node_ports -.->|"shares"| node_comment_domain
node_user_uc -->|"uses"| node_user_domain
node_video_uc -->|"uses"| node_video_domain
node_comment_uc -->|"uses"| node_comment_domain
node_user_uc -->|"persists"| node_firestore
node_video_uc -->|"persists"| node_firestore
node_comment_uc -->|"persists"| node_firestore
node_firestore -.->|"backed by"| node_mongodb
node_video_uc -->|"stores media"| node_object_storage
node_image_uc -->|"stores images"| node_object_storage
node_video_uc -->|"processes"| node_media_pipeline
node_auth_middleware -->|"verifies"| node_firebase_auth
node_router -->|"emits"| node_observability
node_app_boot -->|"configures"| node_observability
node_video_uc -->|"publishes"| node_pubsub

click node_main "https://github.com/yuorei/yuovision-server/blob/main/main.go"
click node_router "https://github.com/yuorei/yuovision-server/blob/main/app/driver/router/http_router.go"
click node_auth_middleware "https://github.com/yuorei/yuovision-server/blob/main/app/adapter/middleware/auth.go"
click node_graphql_schema "https://github.com/yuorei/yuovision-server/blob/main/graph/schema/schema.graphqls"
click node_resolvers "https://github.com/yuorei/yuovision-server/blob/main/app/adapter/presentation/resolver/resolver.go"
click node_app_boot "https://github.com/yuorei/yuovision-server/blob/main/app/application/app.go"
click node_user_uc "https://github.com/yuorei/yuovision-server/blob/main/app/application/user.go"
click node_video_uc "https://github.com/yuorei/yuovision-server/blob/main/app/application/video.go"
click node_comment_uc "https://github.com/yuorei/yuovision-server/blob/main/app/application/comment.go"
click node_image_uc "https://github.com/yuorei/yuovision-server/blob/main/app/application/image.go"
click node_ports "https://github.com/yuorei/yuovision-server/blob/main/app/application/port/ports.go"
click node_user_domain "https://github.com/yuorei/yuovision-server/blob/main/app/domain/user.go"
click node_video_domain "https://github.com/yuorei/yuovision-server/blob/main/app/domain/video.go"
click node_comment_domain "https://github.com/yuorei/yuovision-server/blob/main/app/domain/comment.go"
click node_ids "https://github.com/yuorei/yuovision-server/blob/main/app/domain/id.go"
click node_firestore "https://github.com/yuorei/yuovision-server/blob/main/app/adapter/infrastructure/firestore/video.go"
click node_object_storage "https://github.com/yuorei/yuovision-server/blob/main/app/driver/storage/r2.go"
click node_media_pipeline "https://github.com/yuorei/yuovision-server/blob/main/app/adapter/infrastructure/firestore/video_processing.go"
click node_firebase_auth "https://github.com/yuorei/yuovision-server/blob/main/app/driver/firebase/auth.go"
click node_observability "https://github.com/yuorei/yuovision-server/blob/main/app/driver/log/slog.go"
click node_pubsub "https://github.com/yuorei/yuovision-server/blob/main/app/driver/pubsub/client.go"
click node_mongodb "https://github.com/yuorei/yuovision-server/blob/main/app/driver/db/mongodb/collection/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_auth_middleware,node_graphql_schema,node_resolvers toneBlue
class node_app_boot,node_user_uc,node_video_uc,node_comment_uc,node_image_uc,node_ports toneAmber
class node_user_domain,node_video_domain,node_comment_domain,node_ids toneMint
class node_main,node_router,node_firestore,node_object_storage,node_media_pipeline,node_observability,node_pubsub toneRose
class node_firebase_auth,node_mongodb toneIndigo
```

## Components

### API / Presentation

GraphQL edge, routing, and auth middleware

- [Auth Middleware](https://github.com/yuorei/yuovision-server/blob/main/app/adapter/middleware/auth.go): edge auth · Verifies requests before they reach resolvers · `app/adapter/middleware/auth.go`
- [GraphQL Schema](https://github.com/yuorei/yuovision-server/blob/main/graph/schema/schema.graphqls): api contract · Public schema for auth, user, video, comment, and node operations · `graph/schema/schema.graphqls`
- [Resolvers](https://github.com/yuorei/yuovision-server/blob/main/app/adapter/presentation/resolver/resolver.go): graphql handlers · Thin GraphQL orchestration layer delegating to application use cases · `app/adapter/presentation/resolver/resolver.go`

### Application

Use cases and ports

- [App Setup](https://github.com/yuorei/yuovision-server/blob/main/app/application/app.go): composition root · Builds the application with its ports and adapters · `app/application/app.go`
- [User Use Cases](https://github.com/yuorei/yuovision-server/blob/main/app/application/user.go): workflow · User-related business flows · `app/application/user.go`
- [Video Use Cases](https://github.com/yuorei/yuovision-server/blob/main/app/application/video.go): workflow · Video upload, listing, and retrieval workflows · `app/application/video.go`
- [Comment Use Cases](https://github.com/yuorei/yuovision-server/blob/main/app/application/comment.go): workflow · Comment creation and query workflows · `app/application/comment.go`
- [Image Use Cases](https://github.com/yuorei/yuovision-server/blob/main/app/application/image.go): workflow · Image-related application workflows · `app/application/image.go`
- [Ports](https://github.com/yuorei/yuovision-server/blob/main/app/application/port/ports.go): interfaces · Outbound interfaces used by use cases · `app/application/port/ports.go`

### Domain

Core entities and value types

- [User Model](https://github.com/yuorei/yuovision-server/blob/main/app/domain/user.go): entity · Core user entity and related domain logic · `app/domain/user.go`
- [Video Model](https://github.com/yuorei/yuovision-server/blob/main/app/domain/video.go): entity · Core video entity and media metadata · `app/domain/video.go`
- [Comment Model](https://github.com/yuorei/yuovision-server/blob/main/app/domain/comment.go): entity · Core comment entity and relationships · `app/domain/comment.go`
- [IDs & UUIDs](https://github.com/yuorei/yuovision-server/blob/main/app/domain/id.go): value types · Domain identifier and UUID helpers · `app/domain/id.go`

### Infrastructure / Drivers

Persistence, storage, processing, and runtime wiring

- [Main](https://github.com/yuorei/yuovision-server/blob/main/main.go): process entry · Service bootstrap and runtime startup · `main.go`
- [HTTP Router](https://github.com/yuorei/yuovision-server/blob/main/app/driver/router/http_router.go): http wiring · Connects HTTP server, middleware, and GraphQL handlers · `app/driver/router/http_router.go`
- [Firestore Adapters](https://github.com/yuorei/yuovision-server/blob/main/app/adapter/infrastructure/firestore/video.go): document persistence · Concrete persistence adapters for user, video, and comment documents · `app/adapter/infrastructure/firestore/video.go`
- [R2 Storage](https://github.com/yuorei/yuovision-server/blob/main/app/driver/storage/r2.go): object storage · Video and image binary storage integration · `app/driver/storage/r2.go`
- [Media Pipeline](https://github.com/yuorei/yuovision-server/blob/main/app/adapter/infrastructure/firestore/video_processing.go): processing · Video processing and HLS asset generation · `app/adapter/infrastructure/firestore/video_processing.go`
- [Observability](https://github.com/yuorei/yuovision-server/blob/main/app/driver/log/slog.go): telemetry · Logging, Sentry, and New Relic drivers · `app/driver/log/slog.go`
- [Pub/Sub](https://github.com/yuorei/yuovision-server/blob/main/app/driver/pubsub/client.go): async bus · Eventing and background-work support · `app/driver/pubsub/client.go`

### External Systems

Outside services and managed resources

- [Firebase Auth](https://github.com/yuorei/yuovision-server/blob/main/app/driver/firebase/auth.go): identity provider · Token verification and identity integration · `app/driver/firebase/auth.go`
- [MongoDB](https://github.com/yuorei/yuovision-server/blob/main/app/driver/db/mongodb/collection/video.go): database backend · Document database collections for persistence · `app/driver/db/mongodb/collection/video.go`

## Connections

- Main → HTTP Router: starts · Process bootstrap wires the HTTP runtime
- Main → App Setup: initializes · Creates the application composition root
- HTTP Router → Auth Middleware: applies · Requests pass through auth before handlers
- HTTP Router → Resolvers: serves · Routes GraphQL traffic to the resolver layer
- Resolvers → GraphQL Schema: implements · Resolvers conform to the GraphQL contract
- Resolvers → User Use Cases: calls · User queries and mutations delegate to use cases
- Resolvers → Video Use Cases: calls · Video operations delegate to use cases
- Resolvers → Comment Use Cases: calls · Comment operations delegate to use cases
- Resolvers → Image Use Cases: calls · Image-related operations delegate to use cases
- App Setup → Ports: wires · Composition root binds ports to adapters
- User Use Cases → Ports: depends on · User workflows use outbound interfaces
- Video Use Cases → Ports: depends on · Video workflows use outbound interfaces
- Comment Use Cases → Ports: depends on · Comment workflows use outbound interfaces
- Image Use Cases → Ports: depends on · Image workflows use outbound interfaces
- Ports → User Model: shares · Ports move domain user data
- Ports → Video Model: shares · Ports move domain video data
- Ports → Comment Model: shares · Ports move domain comment data
- User Use Cases → User Model: uses · User workflows manipulate user entities
- Video Use Cases → Video Model: uses · Video workflows manipulate video entities
- Comment Use Cases → Comment Model: uses · Comment workflows manipulate comment entities
- User Use Cases → Firestore Adapters: persists · User data can be stored through document adapters
- Video Use Cases → Firestore Adapters: persists · Video metadata can be stored through document adapters
- Comment Use Cases → Firestore Adapters: persists · Comment data can be stored through document adapters
- Firestore Adapters → MongoDB: backed by · Document persistence boundary maps to a database backend
- Video Use Cases → R2 Storage: stores media · Uploads and retrieves binary video assets
- Image Use Cases → R2 Storage: stores images · Image workflows persist binary assets
- Video Use Cases → Media Pipeline: processes · Video workflows trigger transcoding and HLS generation
- Auth Middleware → Firebase Auth: verifies · Edge authentication uses token/identity provider integration
- HTTP Router → Observability: emits · Request handling is instrumented with telemetry
- App Setup → Observability: configures · Runtime wiring installs logging and monitoring
- Video Use Cases → Pub/Sub: publishes · Video workflows may emit async events
