Architecture

Three tiers, each shippable independently. POC proves the pipeline. On-premises adds auth, persistence, and observability. Production adds queue-based throughput and owned storage. Each tier is a superset of the previous — no rework, only additions.

Tier 0

Proof of Concept (POC)

Current

Brief in → video URL out.

Arch decisions

Concurrency blockClient-side ref blocks re-submission while a job is in flight — prevents duplicate HeyGen sessions from a double-click or fast re-submit.

60-min timeoutMAX_POLLS ceiling · relies on HeyGen's own failed signal, not a timer.

Failure handlingHeyGen failed: surfaced to UI, user re-submits. 429: Retry-After returned to client with live countdown. Transient errors: 3 retries before error banner.

Cost trackingEach video captures credit cost and render duration from the HeyGen API response, displayed per-video in the portal.

Tier 1

On-Premises

Authentication, job persistence, and direct on-premise delivery.

Arch decisions

Helios IdP (SAML / OIDC)Org-scoped sessions tied to Helios's identity provider; HeyGen API key stays server-side only.

Postgres (self-hosted)orgs · users · briefs · jobs schema; row-level security by org_id; status tracked in DB.

Webhook + auto-pushHeyGen POSTs to /api/webhook on completion; HMAC-SHA256 verified; MP4 written directly to On-Premise Blob.

IdempotencyEvery job gets a deterministic key. Worker checks Postgres before calling HeyGen — prevents duplicate renders on queue retry.

SecurityHeyGen API key: server env var only. Webhook: HMAC-SHA256 verified. Blob: private, pre-signed URLs. All data scoped by org_id (row-level security).

Tier 2

Production

Helios internal product at scale — doc ingestion, async queue, Enablement Tool delivery.

Arch decisions

Job Queue (retry + DLQ)Async dispatch decouples submission from rendering; automatic retry on transient failure; dead letter queue alerts on spike.

Doc ingestionPDF / slide deck parsed into the 6-section brief schema; knowledge base search auto-suggests content from internal docs.

Enablement Tool integrationVideo auto-published to seller's library (Highspot, Seismic, etc.) on webhook completion.

Technology decisions

Concern	Tier 0 — POC	Tier 1 — On-premises	Tier 2 — Production
Framework	Next.js + Vercel	App server (self-hosted)	--
AI / Script	HeyGen Video Agent	--	--
Auth	None	SAML / OIDC (Helios IdP)	--
Job queue	None (sync poll)	None (webhook)	Internal queue (retry + DLQ)
Metadata DB	Redis (briefs only)	Postgres (self-hosted)	--
Video storage	HeyGen CDN URL	On-Premise Blob	← same + CDN
Brief source	Manual form	Manual form	Form + doc upload / internal search
Video delivery	Manual download	Auto-push (webhook)	Enablement Tool (auto-publish)
Monitoring	Vercel Analytics	On-prem tools	--
Status delivery	REST polling (4s)	SSE + webhook	SSE + queue events