# vfarcic/youtube-automation architecture

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

- Interactive diagram: https://gitdiagram.com/vfarcic/youtube-automation
- Repository: https://github.com/vfarcic/youtube-automation

## Overview

#### Purpose and Entry Points
YouTube Automation is a Go service and embedded React SPA for managing a YouTube video lifecycle from planning through publishing and post-publish work. The executable starts the HTTP server from `cmd/youtube-automation/main.go`; API contract is defined in `openapi.yaml`. The production server serves the built frontend embedded through `internal/frontend/embed.go`.

#### HTTP/API Boundary
`internal/api/server.go` composes routing, middleware, services, SPA fallback, and health handling. Resource handlers expose video CRUD, lifecycle phases, aspect metadata, AI actions, Drive operations, publishing, and social actions under authenticated `/api/*` paths. `internal/api/middleware_auth.go` applies optional Bearer-token authentication while health remains public. API handlers are the boundary between browser clients and domain/integration services.

#### Video Workflow and Persistence
Videos are represented as YAML-backed workflow records, with lifecycle phases and typed aspects driving progress and editing. `internal/video/manager.go` owns video-level management; `internal/storage/yaml.go` reads and writes persisted manifests; `internal/workflow/types.go` and `internal/workflow/constants.go` define workflow state. The service layer in `internal/service/video_service.go` and `internal/data/video_service.go` coordinates API-facing operations over this local data store, rooted at `DATA_DIR`.

#### Metadata-Driven UI and Forms
The aspect subsystem describes editable fields, mapping, setters, and completion calculations rather than hard-coding each video form. `internal/aspect/service.go`, `internal/aspect/types.go`, and `internal/aspect/completion.go` supply metadata and progress to API consumers. The React client renders that contract dynamically through `web/src/pages/VideoDetail.tsx`, `web/src/components/forms/DynamicForm.tsx`, and `web/src/api/client.ts`; the backend’s embedded build lives in `internal/frontend/dist/index.html`.

#### AI Content and Thumbnail Pipeline
AI adapters generate and analyze titles, descriptions, tags, tweets, shorts, AMA material, timing, and thumbnail prompts. `internal/ai/provider.go` establishes the provider boundary, while feature-specific operations include `internal/ai/titles.go` and `internal/ai/analyze_timing.go`. Thumbnail generation is a separate orchestration pipeline: `internal/thumbnail/orchestrator.go` coordinates prompts, generation providers, resolution, and image storage via `internal/thumbnail/service.go` and `internal/thumbnail/image_store.go`. AI credentials are externally configured (`AI_KEY`); Gemini/GPT image implementations are isolated in this layer.

#### Publishing and External Integrations
Publishing adapters turn video metadata and assets into external side effects. `internal/publishing/youtube.go` handles YouTube uploads, updates, captions, playlists, and analytics support; `internal/publishing/hugo.go` produces Hugo content/assets; `internal/publishing/scheduler.go` supports publish timing. Google OAuth and Drive are encapsulated by `internal/auth/oauth.go` and `internal/gdrive/service.go`. Social distribution is separated into platform adapters such as `internal/platform/bluesky/bluesky.go`, `internal/platform/linkedin.go`, and `internal/platform/hackernews.go`; Slack and email notifications use `internal/slack/service.go` and `internal/notification/email.go`.

#### Scheduled and Operational Runtime
AMA automation and notifications execute through an internal scheduler, centered on `internal/scheduler/scheduler.go` and `internal/scheduler/ama_job.go`. Runtime configuration comes from `settings.yaml` and `internal/configuration/settings.go`. Deployment supports a containerized Go binary (`Dockerfile`) and Kubernetes/Helm (`helm/youtube-automation/templates/deployment.yaml`), with the SPA built separately from the Vite React project under `web/`.

Main entry points: [`internal/api/server.go`](https://github.com/vfarcic/youtube-automation/blob/main/internal/api/server.go) (API server), [`web/src/pages/VideoDetail.tsx`](https://github.com/vfarcic/youtube-automation/blob/main/web/src/pages/VideoDetail.tsx) (React video UI), [`internal/video/manager.go`](https://github.com/vfarcic/youtube-automation/blob/main/internal/video/manager.go) (Video manager), [`internal/thumbnail/orchestrator.go`](https://github.com/vfarcic/youtube-automation/blob/main/internal/thumbnail/orchestrator.go) (Thumbnail pipeline)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_entry["Go executable<br/>entrypoint<br/>[main.go]"]
  node_server["API server<br/>HTTP composition<br/>[server.go]"]
  node_auth_middleware["Bearer auth<br/>middleware<br/>[middleware_auth.go]"]
  node_api_contract["OpenAPI contract<br/>API specification<br/>[openapi.yaml]"]
  node_embedded_spa["Embedded SPA<br/>frontend bundle<br/>[embed.go]"]
  node_react_client["React video UI<br/>browser client<br/>[VideoDetail.tsx]"]
  node_scheduler["AMA scheduler<br/>background scheduler<br/>[scheduler.go]"]
  node_settings["Runtime settings<br/>configuration<br/>[settings.go]"]
end

subgraph group_workflow["Workflow &amp; Data"]
  node_video_service["Video service<br/>application service<br/>[video_service.go]"]
  node_video_manager["Video manager<br/>domain manager<br/>[manager.go]"]
  node_workflow_model["Workflow model<br/>lifecycle state<br/>[types.go]"]
  node_yaml_store[("YAML manifests<br/>local persistence<br/>[yaml.go]")]
  node_aspect_service["Aspect metadata<br/>metadata service<br/>[service.go]"]
end

subgraph group_content["Content Generation"]
  node_ai_provider{{"AI provider boundary<br/>AI adapter<br/>[provider.go]"}}
  node_thumbnail_pipeline["Thumbnail pipeline<br/>orchestrator<br/>[orchestrator.go]"]
  node_image_store[("Thumbnail images<br/>image storage<br/>[image_store.go]")]
end

subgraph group_integrations["External Delivery"]
  node_oauth{{"Google OAuth<br/>authentication adapter<br/>[oauth.go]"}}
  node_drive["Google Drive<br/>asset integration<br/>[service.go]"]
  node_youtube["YouTube publishing<br/>publishing adapter<br/>[youtube.go]"]
  node_social["Social platforms<br/>distribution adapters<br/>[bluesky.go]"]
  node_notifications["Notifications<br/>notification adapter<br/>[service.go]"]
end

node_entry -->|"starts"| node_server
node_server -->|"applies"| node_auth_middleware
node_server -.->|"implements"| node_api_contract
node_server -->|"serves"| node_embedded_spa
node_react_client -->|"calls /api"| node_server
node_embedded_spa -.->|"contains build"| node_react_client
node_server -->|"video API operations"| node_video_service
node_server -->|"aspect metadata API"| node_aspect_service
node_video_service -->|"manages"| node_video_manager
node_video_manager -->|"uses lifecycle"| node_workflow_model
node_video_manager -->|"reads and writes"| node_yaml_store
node_aspect_service -->|"describes aspects"| node_workflow_model
node_react_client -->|"renders metadata-driven forms"| node_aspect_service
node_server -->|"AI actions"| node_ai_provider
node_server -->|"thumbnail actions"| node_thumbnail_pipeline
node_thumbnail_pipeline -->|"generates prompts and images"| node_ai_provider
node_thumbnail_pipeline -->|"stores images"| node_image_store
node_server -->|"authorizes Google operations"| node_oauth
node_oauth -->|"authenticates"| node_drive
node_server -->|"Drive operations"| node_drive
node_server -->|"publishing actions"| node_youtube
node_server -->|"social actions"| node_social
node_scheduler -->|"scheduled distribution"| node_social
node_scheduler -->|"sends alerts"| node_notifications
node_settings -.->|"configures"| node_server
node_settings -.->|"configures"| node_scheduler

click node_entry "https://github.com/vfarcic/youtube-automation/blob/main/cmd/youtube-automation/main.go"
click node_server "https://github.com/vfarcic/youtube-automation/blob/main/internal/api/server.go"
click node_auth_middleware "https://github.com/vfarcic/youtube-automation/blob/main/internal/api/middleware_auth.go"
click node_api_contract "https://github.com/vfarcic/youtube-automation/blob/main/openapi.yaml"
click node_embedded_spa "https://github.com/vfarcic/youtube-automation/blob/main/internal/frontend/embed.go"
click node_react_client "https://github.com/vfarcic/youtube-automation/blob/main/web/src/pages/VideoDetail.tsx"
click node_video_service "https://github.com/vfarcic/youtube-automation/blob/main/internal/service/video_service.go"
click node_video_manager "https://github.com/vfarcic/youtube-automation/blob/main/internal/video/manager.go"
click node_workflow_model "https://github.com/vfarcic/youtube-automation/blob/main/internal/workflow/types.go"
click node_yaml_store "https://github.com/vfarcic/youtube-automation/blob/main/internal/storage/yaml.go"
click node_aspect_service "https://github.com/vfarcic/youtube-automation/blob/main/internal/aspect/service.go"
click node_ai_provider "https://github.com/vfarcic/youtube-automation/blob/main/internal/ai/provider.go"
click node_thumbnail_pipeline "https://github.com/vfarcic/youtube-automation/blob/main/internal/thumbnail/orchestrator.go"
click node_image_store "https://github.com/vfarcic/youtube-automation/blob/main/internal/thumbnail/image_store.go"
click node_oauth "https://github.com/vfarcic/youtube-automation/blob/main/internal/auth/oauth.go"
click node_drive "https://github.com/vfarcic/youtube-automation/blob/main/internal/gdrive/service.go"
click node_youtube "https://github.com/vfarcic/youtube-automation/blob/main/internal/publishing/youtube.go"
click node_social "https://github.com/vfarcic/youtube-automation/blob/main/internal/platform/bluesky/bluesky.go"
click node_scheduler "https://github.com/vfarcic/youtube-automation/blob/main/internal/scheduler/scheduler.go"
click node_notifications "https://github.com/vfarcic/youtube-automation/blob/main/internal/slack/service.go"
click node_settings "https://github.com/vfarcic/youtube-automation/blob/main/internal/configuration/settings.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_entry,node_server,node_auth_middleware,node_api_contract,node_embedded_spa,node_react_client,node_scheduler,node_settings toneBlue
class node_video_service,node_video_manager,node_workflow_model,node_yaml_store,node_aspect_service toneAmber
class node_ai_provider,node_thumbnail_pipeline,node_image_store toneMint
class node_oauth,node_drive,node_youtube,node_social,node_notifications toneRose
```

## Components

### Runtime

- [Go executable](https://github.com/vfarcic/youtube-automation/blob/main/cmd/youtube-automation/main.go): entrypoint · Starts the HTTP server. · `cmd/youtube-automation/main.go`
- [API server](https://github.com/vfarcic/youtube-automation/blob/main/internal/api/server.go): HTTP composition · Routes API requests, middleware, health, and SPA fallback. · `internal/api/server.go`
- [Bearer auth](https://github.com/vfarcic/youtube-automation/blob/main/internal/api/middleware_auth.go): middleware · Protects API routes while leaving health public. · `internal/api/middleware_auth.go`
- [OpenAPI contract](https://github.com/vfarcic/youtube-automation/blob/main/openapi.yaml): API specification · `openapi.yaml`
- [Embedded SPA](https://github.com/vfarcic/youtube-automation/blob/main/internal/frontend/embed.go): frontend bundle · Production frontend served by the Go server. · `internal/frontend/embed.go`
- [React video UI](https://github.com/vfarcic/youtube-automation/blob/main/web/src/pages/VideoDetail.tsx): browser client · Dynamically renders video details and editable aspect forms. · `web/src/pages/VideoDetail.tsx`
- [AMA scheduler](https://github.com/vfarcic/youtube-automation/blob/main/internal/scheduler/scheduler.go): background scheduler · Runs AMA automation and scheduled notifications. · `internal/scheduler/scheduler.go`
- [Runtime settings](https://github.com/vfarcic/youtube-automation/blob/main/internal/configuration/settings.go): configuration · Supplies runtime configuration and external credentials. · `internal/configuration/settings.go`

### Workflow & Data

- [Video service](https://github.com/vfarcic/youtube-automation/blob/main/internal/service/video_service.go): application service · Coordinates API-facing video operations. · `internal/service/video_service.go`
- [Video manager](https://github.com/vfarcic/youtube-automation/blob/main/internal/video/manager.go): domain manager · Owns video-level workflow management. · `internal/video/manager.go`
- [Workflow model](https://github.com/vfarcic/youtube-automation/blob/main/internal/workflow/types.go): lifecycle state · Phases and typed aspects define video progress. · `internal/workflow/types.go`
- [YAML manifests](https://github.com/vfarcic/youtube-automation/blob/main/internal/storage/yaml.go): local persistence · Workflow records persisted under DATA_DIR. · `internal/storage/yaml.go`
- [Aspect metadata](https://github.com/vfarcic/youtube-automation/blob/main/internal/aspect/service.go): metadata service · Provides fields, setters, mappings, and completion. · `internal/aspect/service.go`

### Content Generation

- [AI provider boundary](https://github.com/vfarcic/youtube-automation/blob/main/internal/ai/provider.go): AI adapter · Externally credentialed AI generation and analysis. · `internal/ai/provider.go`
- [Thumbnail pipeline](https://github.com/vfarcic/youtube-automation/blob/main/internal/thumbnail/orchestrator.go): orchestrator · Coordinates prompts, image generation, resolution, and storage. · `internal/thumbnail/orchestrator.go`
- [Thumbnail images](https://github.com/vfarcic/youtube-automation/blob/main/internal/thumbnail/image_store.go): image storage · `internal/thumbnail/image_store.go`

### External Delivery

- [Google OAuth](https://github.com/vfarcic/youtube-automation/blob/main/internal/auth/oauth.go): authentication adapter · `internal/auth/oauth.go`
- [Google Drive](https://github.com/vfarcic/youtube-automation/blob/main/internal/gdrive/service.go): asset integration · `internal/gdrive/service.go`
- [YouTube publishing](https://github.com/vfarcic/youtube-automation/blob/main/internal/publishing/youtube.go): publishing adapter · Uploads, updates, captions, playlists, and analytics. · `internal/publishing/youtube.go`
- [Social platforms](https://github.com/vfarcic/youtube-automation/blob/main/internal/platform/bluesky/bluesky.go): distribution adapters · Bluesky, LinkedIn, and Hacker News distribution. · `internal/platform/bluesky/bluesky.go`
- [Notifications](https://github.com/vfarcic/youtube-automation/blob/main/internal/slack/service.go): notification adapter · Slack and email delivery. · `internal/slack/service.go`

## Connections

- Go executable → API server: starts
- API server → Bearer auth: applies
- API server → OpenAPI contract: implements
- API server → Embedded SPA: serves
- React video UI → API server: calls /api
- Embedded SPA → React video UI: contains build
- API server → Video service: video API operations
- API server → Aspect metadata: aspect metadata API
- Video service → Video manager: manages
- Video manager → Workflow model: uses lifecycle
- Video manager → YAML manifests: reads and writes
- Aspect metadata → Workflow model: describes aspects
- React video UI → Aspect metadata: renders metadata-driven forms
- API server → AI provider boundary: AI actions
- API server → Thumbnail pipeline: thumbnail actions
- Thumbnail pipeline → AI provider boundary: generates prompts and images
- Thumbnail pipeline → Thumbnail images: stores images
- API server → Google OAuth: authorizes Google operations
- Google OAuth → Google Drive: authenticates
- API server → Google Drive: Drive operations
- API server → YouTube publishing: publishing actions
- API server → Social platforms: social actions
- AMA scheduler → Social platforms: scheduled distribution
- AMA scheduler → Notifications: sends alerts
- Runtime settings → API server: configures
- Runtime settings → AMA scheduler: configures