# hex-tech-lab/hex-yt-intel architecture

> Architecture diagram of the GitHub repository hex-tech-lab/hex-yt-intel, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-24). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hex-tech-lab/hex-yt-intel
- Repository: https://github.com/hex-tech-lab/hex-yt-intel

## Overview

This repository is a **hybrid edge content-intelligence platform** for YouTube analysis. The architecture is split across a **Next.js web app on Vercel**, a **Cloudflare Worker for long-running streaming work**, and a **Supabase-backed persistence layer**. The repo is organized to keep the browser-facing app, the streaming engine, and database access in separate runtime boundaries.

The **web app** in `/web` is the main user-facing shell: dashboard, landing pages, auth screens, billing pages, share pages, search, atlas/global graph views, and admin dashboards. It uses Next.js App Router, React client components, route handlers, and local state stores/hooks for analysis, chat, UI, and streaming state. This layer acts as the “bouncer” and orchestration layer rather than doing the heavy synthesis work itself.

The **Cloudflare Worker** in `/worker` is the high-throughput execution layer. It exposes routes for chat, analysis, metadata, health, and transcript-related operations using Hono. Its services handle streaming LLM synthesis, transcript extraction, Markdown reconstruction, knowledge-graph synthesis, validation, and persistence preparation. This is the part designed for long-running browser-to-edge SSE flows.

A key architectural decision is the **split between interactive requests and streaming synthesis**. The web app handles authentication, quota checks, and request initiation. For deep analysis or chat generation, the client is routed into the worker’s SSE stream so the browser stays connected directly to the edge runtime while the worker emits incremental updates.

Persistence is centered on **Supabase Postgres** with extensive migrations and row-level security. The schema includes analyses, chat conversations/messages, idempotency controls, analysis chunks, knowledge graph tables, app settings, prompt config, billing status, and quota-related columns. The DB is not just storage; it is also the enforcement point for ownership, deduplication, and secure reads/writes.

The repo strongly separates concerns using a **ports-and-adapters style**. In `/web/lib/ports` and `/worker/src/ports`, the code defines abstractions for auth, billing, persistence, ingestion, graph, vector deduplication, model resolution, and streaming-related services. Concrete adapters then connect those ports to Supabase, Redis/Upstash, OpenRouter, Stripe/Paddle, YouTube, and other infrastructure.

The **intelligence pipeline** is a major subsystem. UCIS v5.1 parsing, dimension extraction, synthesis state, knowledge-graph generation, and relation scoring are split across web libraries, worker services, and UI components. The dashboard visualizes this output through panels such as the knowledge graph canvas, processing log, word cloud, and intelligence panel.

There is a distinct **billing and entitlement boundary**. The web app contains checkout, billing portal, and billing dashboard flows, while server-side adapters and webhook handlers integrate with Stripe and related billing backends. Billing status is also persisted into the database and used alongside quota enforcement and access control.

The project also includes a **search and graph retrieval layer**. Web-side hooks and API routes expose search, graph, relations, and atlas endpoints. Under the hood, these connect to persistence and vector/graph adapters so the UI can query saved analyses, global knowledge graphs, and related content views.

Security and reliability are built into the architecture rather than added later. Authentication is handled through Supabase/Vercel auth adapters, middleware, callback routes, and signed server-to-server persistence patterns. The repo also includes rate-limit status, HMAC/token adapters, RLS hardening migrations, and webhook validation routes for external event sources.

Observability is a first-class cross-cutting concern. Sentry is wired into the web app and worker, there are health routes in both runtimes, and the repo includes verification scripts plus deployment/test workflows. This suggests the system is meant to be operated continuously across Vercel, Cloudflare, and Supabase with clear production checks.

The **documentation and design-system directories** are part of the architecture too, but as supporting assets rather than runtime services. `docs/` contains ADRs, specs, ops runbooks, and historical stabilization notes; `design-system/` contains UI patterns and theme assets used to keep the console consistent across marketing and dashboard surfaces.

In diagram terms, the important flows are:
- **User browser → web app → auth/quota check → worker streaming SSE → Supabase persistence**
- **User browser → web app route handlers → Supabase/Stripe/Sentry/Redis integrations**
- **Worker synthesis/validation → HMAC-signed writes → Supabase database**
- **Saved analyses / chats → web graph/search/share pages → Supabase read models**

The main boundaries to show are:
1. **Presentation layer** in Next.js
2. **Streaming compute layer** in Cloudflare Worker
3. **Persistence/entitlements layer** in Supabase plus billing providers
4. **Cross-cutting support** for auth, observability, rate limiting, and vector/graph intelligence

Main entry points: [`web/app/api`](https://github.com/hex-tech-lab/hex-yt-intel/tree/main/web/app/api) (Web APIs), [`worker/src/routes`](https://github.com/hex-tech-lab/hex-yt-intel/tree/main/worker/src/routes) (Worker routes), [`supabase/migrations`](https://github.com/hex-tech-lab/hex-yt-intel/tree/main/supabase/migrations) (Supabase DB), [`web/lib/adapters`](https://github.com/hex-tech-lab/hex-yt-intel/tree/main/web/lib/adapters) (Web adapters)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_web["Next.js web app"]
  node_web_shell["Web shell<br/>next app router"]
  node_web_api["Web APIs<br/>route handlers"]
  node_web_dashboard["Dashboard UI<br/>console UI"]
  node_web_hooks["Client hooks<br/>state/hooks"]
  node_web_adapters["Web adapters<br/>ports adapters"]
  node_web_usecases["Use cases<br/>application services"]
  node_web_ports["Ports<br/>abstractions"]
end

subgraph group_grp_worker["Cloudflare Worker"]
  node_worker_routes["Worker routes<br/>hono routes"]
  node_worker_stream["Chat stream<br/>sse engine<br/>[chat-stream.ts]"]
  node_worker_services["Synthesis services<br/>edge services"]
  node_worker_persist["Persist service<br/>durable write prep<br/>[PersistService.ts]"]
  node_worker_ports["Worker ports<br/>service contracts"]
end

subgraph group_grp_data["Persistence and entitlements"]
  node_supabase_db[("Supabase DB<br/>postgres schema")]
  node_billing_ext["Billing providers<br/>external billing"]
end

subgraph group_grp_support["Cross-cutting support"]
  node_auth_ext["Auth layer<br/>auth adapters"]
  node_observability["Observability<br/>monitoring"]
  node_intelligence_core["Intelligence core<br/>graph and synthesis"]
  node_rate_limit["Traffic guard<br/>quota and rate limit<br/>[traffic.ts]"]
end

node_web_shell -->|"calls"| node_web_api
node_web_shell -->|"renders"| node_web_dashboard
node_web_shell -->|"uses"| node_web_hooks
node_web_hooks -->|"reads/writes"| node_web_adapters
node_web_api -->|"reads/writes"| node_supabase_db
node_web_api -->|"integrates"| node_billing_ext
node_web_api -->|"authenticates"| node_auth_ext
node_web_api -->|"reports"| node_observability
node_web_api -->|"checks"| node_rate_limit
node_web_api -->|"routes to"| node_worker_routes
node_web_usecases -->|"depends on"| node_web_ports
node_web_usecases -->|"implemented by"| node_web_adapters
node_web_adapters -->|"persists"| node_supabase_db
node_web_adapters -->|"integrates"| node_billing_ext
node_worker_routes -->|"starts"| node_worker_stream
node_worker_routes -->|"invokes"| node_worker_services
node_worker_services -->|"depends on"| node_worker_ports
node_worker_services -->|"prepares writes"| node_worker_persist
node_worker_persist -->|"writes"| node_supabase_db
node_worker_stream -->|"streams state"| node_supabase_db
node_intelligence_core -->|"drives UI"| node_web_dashboard
node_intelligence_core -->|"feeds"| node_worker_services
node_rate_limit -->|"guards"| node_worker_routes
node_auth_ext -->|"authorizes"| node_supabase_db
node_observability -->|"monitors"| node_worker_routes
node_observability -->|"monitors"| node_web_api

click node_web_shell "https://github.com/hex-tech-lab/hex-yt-intel/tree/main/web/app"
click node_web_api "https://github.com/hex-tech-lab/hex-yt-intel/tree/main/web/app/api"
click node_web_dashboard "https://github.com/hex-tech-lab/hex-yt-intel/tree/main/web/components/templates/console"
click node_web_hooks "https://github.com/hex-tech-lab/hex-yt-intel/tree/main/web/hooks"
click node_web_adapters "https://github.com/hex-tech-lab/hex-yt-intel/tree/main/web/lib/adapters"
click node_web_usecases "https://github.com/hex-tech-lab/hex-yt-intel/tree/main/web/lib/usecases"
click node_web_ports "https://github.com/hex-tech-lab/hex-yt-intel/tree/main/web/lib/ports"
click node_worker_routes "https://github.com/hex-tech-lab/hex-yt-intel/tree/main/worker/src/routes"
click node_worker_stream "https://github.com/hex-tech-lab/hex-yt-intel/blob/main/worker/src/chat-stream.ts"
click node_worker_services "https://github.com/hex-tech-lab/hex-yt-intel/tree/main/worker/src/services"
click node_worker_persist "https://github.com/hex-tech-lab/hex-yt-intel/blob/main/worker/src/services/PersistService.ts"
click node_worker_ports "https://github.com/hex-tech-lab/hex-yt-intel/tree/main/worker/src/ports"
click node_supabase_db "https://github.com/hex-tech-lab/hex-yt-intel/tree/main/supabase/migrations"
click node_billing_ext "https://github.com/hex-tech-lab/hex-yt-intel/tree/main/web/lib/stripe"
click node_auth_ext "https://github.com/hex-tech-lab/hex-yt-intel/tree/main/web/lib/auth"
click node_observability "https://github.com/hex-tech-lab/hex-yt-intel/tree/main/web/lib/monitoring"
click node_intelligence_core "https://github.com/hex-tech-lab/hex-yt-intel/tree/main/web/lib/intelligence"
click node_rate_limit "https://github.com/hex-tech-lab/hex-yt-intel/blob/main/web/lib/services/traffic.ts"

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_web_shell,node_web_api,node_web_dashboard,node_web_hooks,node_web_adapters,node_web_usecases,node_web_ports toneBlue
class node_worker_routes,node_worker_stream,node_worker_services,node_worker_persist,node_worker_ports toneAmber
class node_supabase_db,node_billing_ext toneMint
class node_auth_ext,node_observability,node_intelligence_core,node_rate_limit toneRose
```

## Components

### Next.js web app

Browser-facing console, routes, hooks, and client-side orchestration.

- [Web shell](https://github.com/hex-tech-lab/hex-yt-intel/tree/main/web/app): next app router · Main Next.js presentation layer for dashboard, landing, auth, billing, share, search, and admin surfaces. · `web/app`
- [Web APIs](https://github.com/hex-tech-lab/hex-yt-intel/tree/main/web/app/api): route handlers · Browser-facing endpoints for analyses, chat, search, billing, webhooks, health, and graph reads. · `web/app/api`
- [Dashboard UI](https://github.com/hex-tech-lab/hex-yt-intel/tree/main/web/components/templates/console): console UI · Interactive analysis workspace with panels for intelligence, graph canvas, streaming log, and metadata. · `web/components/templates/console`
- [Client hooks](https://github.com/hex-tech-lab/hex-yt-intel/tree/main/web/hooks): state/hooks · Browser state and data hooks for auth, search, SSE streaming, graph, relations, and analysis history. · `web/hooks`
- [Web adapters](https://github.com/hex-tech-lab/hex-yt-intel/tree/main/web/lib/adapters): ports adapters · Concrete integrations for Supabase, Stripe, Redis, Upstash vector, worker ingestion, YouTube, and stream tokens. · `web/lib/adapters`
- [Use cases](https://github.com/hex-tech-lab/hex-yt-intel/tree/main/web/lib/usecases): application services · Coordination layer for analysis creation, chat processing, and global graph aggregation. · `web/lib/usecases`
- [Ports](https://github.com/hex-tech-lab/hex-yt-intel/tree/main/web/lib/ports): abstractions · Repository boundary contracts for auth, billing, persistence, graph, ingestion, quota, and tokens. · `web/lib/ports`

### Cloudflare Worker

Edge streaming and synthesis runtime for long-running analysis/chat work.

- [Worker routes](https://github.com/hex-tech-lab/hex-yt-intel/tree/main/worker/src/routes): hono routes · Edge endpoints for chat, analysis, metadata, transcript, and health operations. · `worker/src/routes`
- [Chat stream](https://github.com/hex-tech-lab/hex-yt-intel/blob/main/worker/src/chat-stream.ts): sse engine · Streaming request lifecycle and incremental event emission for browser-connected synthesis. · `worker/src/chat-stream.ts`
- [Synthesis services](https://github.com/hex-tech-lab/hex-yt-intel/tree/main/worker/src/services): edge services · LLM cascade, prompt building, markdown reconstruction, reasoning, validation, and persistence preparation. · `worker/src/services`
- [Persist service](https://github.com/hex-tech-lab/hex-yt-intel/blob/main/worker/src/services/PersistService.ts): durable write prep · Atomic persistence and repository handoff layer used by worker synthesis flows. · `worker/src/services/PersistService.ts`
- [Worker ports](https://github.com/hex-tech-lab/hex-yt-intel/tree/main/worker/src/ports): service contracts · Interfaces for LLM cascade, persistence repository, prompt building, reasoning, and transcript providers. · `worker/src/ports`

### Persistence and entitlements

Supabase schema, billing state, quotas, and durable read models.

- [Supabase DB](https://github.com/hex-tech-lab/hex-yt-intel/tree/main/supabase/migrations): postgres schema · Analyses, chats, chunks, knowledge graph tables, settings, billing status, idempotency, and RLS rules. · `supabase/migrations`
- [Billing providers](https://github.com/hex-tech-lab/hex-yt-intel/tree/main/web/lib/stripe): external billing · Stripe and related checkout/webhook flows used to enforce entitlements and status updates. · `web/lib/stripe`

### Cross-cutting support

Auth, observability, rate limiting, and shared intelligence primitives.

- [Auth layer](https://github.com/hex-tech-lab/hex-yt-intel/tree/main/web/lib/auth): auth adapters · Supabase/Vercel auth, callbacks, middleware, and signed server-side request handling. · `web/lib/auth`
- [Observability](https://github.com/hex-tech-lab/hex-yt-intel/tree/main/web/lib/monitoring): monitoring · Sentry wiring plus health and verification routes/scripts across web and worker runtimes. · `web/lib/monitoring`
- [Intelligence core](https://github.com/hex-tech-lab/hex-yt-intel/tree/main/web/lib/intelligence): graph and synthesis · UCIS v5.1 parsing, dimension extraction, knowledge graph logic, and relation scoring. · `web/lib/intelligence`
- [Traffic guard](https://github.com/hex-tech-lab/hex-yt-intel/blob/main/web/lib/services/traffic.ts): quota and rate limit · Rate limit status, traffic adapters, and quota enforcement used before streaming or persistence. · `web/lib/services/traffic.ts`

## Connections

- Web shell → Web APIs: calls · Pages initiate server actions and route-handler requests.
- Web shell → Dashboard UI: renders · The app shell mounts the console and related views.
- Web shell → Client hooks: uses · Client components rely on shared browser state and data hooks.
- Client hooks → Web adapters: reads/writes · Hooks ultimately consume adapter-backed data and streaming state.
- Web APIs → Supabase DB: reads/writes · Route handlers persist and query application state.
- Web APIs → Billing providers: integrates · Checkout and webhook routes connect to billing providers.
- Web APIs → Auth layer: authenticates · Auth routes and middleware establish user identity.
- Web APIs → Observability: reports · API routes emit logs and error telemetry.
- Web APIs → Traffic guard: checks · Inbound requests are gated by traffic and quota rules.
- Web APIs → Worker routes: routes to · Analysis and chat initiation hand off to the edge runtime.
- Use cases → Ports: depends on · Application services speak through abstract repository and service ports.
- Use cases → Web adapters: implemented by · Use cases are realized through concrete Supabase, Redis, and provider adapters.
- Web adapters → Supabase DB: persists · Adapters implement durable reads and writes against Postgres.
- Web adapters → Billing providers: integrates · Billing adapters bridge checkout and subscription state.
- Worker routes → Chat stream: starts · Chat and analysis routes create SSE stream lifecycles.
- Worker routes → Synthesis services: invokes · Route handlers delegate synthesis and validation work.
- Synthesis services → Worker ports: depends on · Edge services are built around explicit provider and repository contracts.
- Synthesis services → Persist service: prepares writes · Synthesis output is packaged for atomic persistence.
- Persist service → Supabase DB: writes · Worker persistence commits analyses, chats, graphs, and chunks.
- Chat stream → Supabase DB: streams state · Incremental synthesis is associated with durable conversation and analysis records.
- Intelligence core → Dashboard UI: drives UI · Graph, dimension, and relation outputs power the console panels.
- Intelligence core → Synthesis services: feeds · UCIS parsing and relation logic inform edge synthesis and validation.
- Traffic guard → Worker routes: guards · Streaming and heavy requests are constrained by quota and traffic policy.
- Auth layer → Supabase DB: authorizes · Ownership and RLS-aware identity flows map users to stored data.
- Observability → Worker routes: monitors · Health and telemetry cover worker execution paths.
- Observability → Web APIs: monitors · Health and telemetry cover web route handlers.