How yuorei/yuovision-server works
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: ports.go Ports · video.go Video Use Cases · resolver.go Resolvers · user.go User Use Cases
Components 22
API / Presentation
GraphQL edge, routing, and auth middleware
- Auth Middleware · Verifies requests before they reach resolvers
app/adapter/middleware/auth.go - GraphQL Schema · Public schema for auth, user, video, comment, and node operations
graph/schema/schema.graphqls - Resolvers · Thin GraphQL orchestration layer delegating to application use cases
app/adapter/presentation/resolver/resolver.go
Application
Use cases and ports
- App Setup · Builds the application with its ports and adapters
app/application/app.go - User Use Cases · User-related business flows
app/application/user.go - Video Use Cases · Video upload, listing, and retrieval workflows
app/application/video.go - Comment Use Cases · Comment creation and query workflows
app/application/comment.go - Image Use Cases · Image-related application workflows
app/application/image.go - Ports · Outbound interfaces used by use cases
app/application/port/ports.go
Domain
Core entities and value types
- User Model · Core user entity and related domain logic
app/domain/user.go - Video Model · Core video entity and media metadata
app/domain/video.go - Comment Model · Core comment entity and relationships
app/domain/comment.go - IDs & UUIDs · Domain identifier and UUID helpers
app/domain/id.go
Infrastructure / Drivers
Persistence, storage, processing, and runtime wiring
- Main · Service bootstrap and runtime startup
main.go - HTTP Router · Connects HTTP server, middleware, and GraphQL handlers
app/driver/router/http_router.go - Firestore Adapters · Concrete persistence adapters for user, video, and comment documents
app/adapter/infrastructure/firestore/video.go - R2 Storage · Video and image binary storage integration
app/driver/storage/r2.go - Media Pipeline · Video processing and HLS asset generation
app/adapter/infrastructure/firestore/video_processing.go - Observability · Logging, Sentry, and New Relic drivers
app/driver/log/slog.go - Pub/Sub · Eventing and background-work support
app/driver/pubsub/client.go
External Systems
Outside services and managed resources
- Firebase Auth · Token verification and identity integration
app/driver/firebase/auth.go - MongoDB · Document database collections for persistence
app/driver/db/mongodb/collection/video.go
Connections 31
- 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