# token-hoarder/video-to-script-mvp architecture

> Architecture diagram of the GitHub repository token-hoarder/video-to-script-mvp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/token-hoarder/video-to-script-mvp
- Repository: https://github.com/token-hoarder/video-to-script-mvp

## Overview

1. This is a Next.js App Router application deployed as a Vercel-style serverless app. The main executable surface is `app/`, with UI pages, server actions, and API route handlers split by route segment.

2. The core product flow appears to be “sign in, upload content, generate scripts, and browse resulting script cards.” The root page (`app/page.tsx`) is likely the main workspace, while `components/script-cards.tsx` suggests a dashboard/list view of generated outputs.

3. Authentication is a first-class boundary. The presence of `app/login/page.tsx`, `app/login/actions.ts`, and `utils/supabase/*` indicates Supabase-backed auth with both client and server helpers. Login is handled through a server action, not a separate backend.

4. Session enforcement and request protection are implemented at the edge/middleware layer. `proxy.ts` plus `utils/supabase/middleware.ts` imply route guarding or session refresh before requests reach page handlers, which is important for diagramming the auth boundary.

5. The backend is split into two API route handlers under `app/api/`:
   - `app/api/upload-url/route.ts` produces a signed upload URL or similar upload token.
   - `app/api/generate-script/route.ts` performs script generation, likely an AI or templated generation step.
   These are server-side entry points distinct from the UI.

6. The upload path is intentionally decoupled from the application server. `components/upload-zone.tsx` likely requests an upload URL first, then uploads directly to storage using that URL. That means the Next.js app orchestrates uploads, but does not necessarily proxy the file bytes itself.

7. Shared Supabase integration lives in `utils/supabase/client.ts`, `server.ts`, and `middleware.ts`. This separation shows three execution contexts: browser client, server runtime, and middleware/edge runtime. It is a useful architectural boundary to preserve in a diagram.

8. The UI layer is a mix of app pages and reusable components. `components/ui/*` contains the design-system primitives (button, card, input, label, toast), while `components/upload-zone.tsx` and `components/script-cards.tsx` are feature components that compose those primitives.

9. Global styling and layout are handled conventionally with `app/layout.tsx` and `app/globals.css`, so the visual shell is centralized rather than duplicated per page. `components/ui/sonner.tsx` indicates toast notifications are part of the interaction flow.

10. The repo also has build/deploy and automation concerns:
   - `next.config.ts`, `vercel.json`, and `package.json` define the runtime/build behavior.
   - `.github/workflows/ai-pipeline.yml` and `pr-reviewer.yml` indicate CI automation, with at least one workflow tied to AI-related processing or checks and another for PR review assistance.

11. From an architecture perspective, the main data flow is: authenticated user → UI page/component → server action or API route → Supabase/session/storage-backed service → generated scripts returned to the UI. The upload and generation steps are separated so the browser can interact with storage and generation independently.

12. Overall, the important diagram boundaries are:
   - browser/client UI
   - Next.js server actions and route handlers
   - auth/session middleware
   - Supabase-backed identity/data layer
   - external storage/upload target via signed URL
   - CI/automation workflows in GitHub Actions

Main entry points: [`components/upload-zone.tsx`](https://github.com/token-hoarder/video-to-script-mvp/blob/main/components/upload-zone.tsx) (Upload zone), [`app/page.tsx`](https://github.com/token-hoarder/video-to-script-mvp/blob/main/app/page.tsx) (Workspace), [`app/login/page.tsx`](https://github.com/token-hoarder/video-to-script-mvp/blob/main/app/login/page.tsx) (Login page), [`components/script-cards.tsx`](https://github.com/token-hoarder/video-to-script-mvp/blob/main/components/script-cards.tsx) (Script cards)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client UI"]
  node_script_cards["Script cards<br/>feature component<br/>[script-cards.tsx]"]
  node_upload_zone["Upload zone<br/>feature component<br/>[upload-zone.tsx]"]
  node_ui_button["Button<br/>ui primitive<br/>[button.tsx]"]
  node_ui_card["Card<br/>ui primitive<br/>[card.tsx]"]
  node_ui_input["Input<br/>ui primitive<br/>[input.tsx]"]
  node_ui_label["Label<br/>ui primitive<br/>[label.tsx]"]
  node_ui_toast["Toasts<br/>ui primitive<br/>[sonner.tsx]"]
end

subgraph group_server["Next.js Server"]
  node_app_layout["App shell<br/>layout<br/>[layout.tsx]"]
  node_app_styles["Global styles<br/>[globals.css]"]
  node_home_page["Workspace<br/>page<br/>[page.tsx]"]
  node_login_page["Login page<br/>[page.tsx]"]
  node_login_actions["Login action<br/>server action<br/>[actions.ts]"]
  node_upload_url_api["Upload URL<br/>route handler<br/>[route.ts]"]
  node_generate_api["Generate script<br/>route handler<br/>[route.ts]"]
end

subgraph group_auth["Auth & Data"]
  node_proxy_middleware["Proxy<br/>middleware<br/>[proxy.ts]"]
  node_supabase_mw["Middleware auth<br/>supabase helper<br/>[middleware.ts]"]
  node_supabase_client["Browser client<br/>supabase helper<br/>[client.ts]"]
  node_supabase_server["Server client<br/>supabase helper<br/>[server.ts]"]
end

subgraph group_infra["Automation"]
  node_next_config["Next config<br/>build config<br/>[next.config.ts]"]
  node_vercel_config["Vercel config<br/>deploy config<br/>[vercel.json]"]
  node_gha_ai["AI pipeline<br/>github action<br/>[ai-pipeline.yml]"]
  node_gha_review["PR reviewer<br/>github action<br/>[pr-reviewer.yml]"]
end

node_proxy_middleware -->|"refresh session"| node_supabase_mw
node_supabase_mw -.->|"session context"| node_supabase_server
node_app_layout -->|"loads"| node_app_styles
node_home_page -->|"renders"| node_script_cards
node_home_page -->|"hosts"| node_upload_zone
node_login_page -->|"submits to"| node_login_actions
node_login_page -->|"uses"| node_ui_input
node_login_page -->|"uses"| node_ui_button
node_upload_zone -->|"requests"| node_upload_url_api
node_upload_zone -->|"uses"| node_ui_button
node_upload_zone -->|"uses"| node_ui_card
node_upload_zone -->|"notifies"| node_ui_toast
node_script_cards -->|"uses"| node_ui_card
node_script_cards -->|"uses"| node_ui_button
node_login_actions -->|"authenticates"| node_supabase_server
node_upload_url_api -->|"issues token"| node_supabase_server
node_generate_api -->|"reads/writes"| node_supabase_server
node_home_page -->|"calls"| node_generate_api
node_supabase_client -.->|"used by"| node_upload_zone
node_supabase_client -.->|"used by"| node_script_cards
node_next_config -.->|"aligns with"| node_vercel_config
node_gha_ai -.->|"checks"| node_generate_api
node_gha_review -.->|"reviews"| node_home_page
node_gha_review -.->|"reviews"| node_login_page

click node_app_layout "https://github.com/token-hoarder/video-to-script-mvp/blob/main/app/layout.tsx"
click node_app_styles "https://github.com/token-hoarder/video-to-script-mvp/blob/main/app/globals.css"
click node_home_page "https://github.com/token-hoarder/video-to-script-mvp/blob/main/app/page.tsx"
click node_login_page "https://github.com/token-hoarder/video-to-script-mvp/blob/main/app/login/page.tsx"
click node_login_actions "https://github.com/token-hoarder/video-to-script-mvp/blob/main/app/login/actions.ts"
click node_upload_url_api "https://github.com/token-hoarder/video-to-script-mvp/blob/main/app/api/upload-url/route.ts"
click node_generate_api "https://github.com/token-hoarder/video-to-script-mvp/blob/main/app/api/generate-script/route.ts"
click node_proxy_middleware "https://github.com/token-hoarder/video-to-script-mvp/blob/main/proxy.ts"
click node_supabase_mw "https://github.com/token-hoarder/video-to-script-mvp/blob/main/utils/supabase/middleware.ts"
click node_supabase_client "https://github.com/token-hoarder/video-to-script-mvp/blob/main/utils/supabase/client.ts"
click node_supabase_server "https://github.com/token-hoarder/video-to-script-mvp/blob/main/utils/supabase/server.ts"
click node_script_cards "https://github.com/token-hoarder/video-to-script-mvp/blob/main/components/script-cards.tsx"
click node_upload_zone "https://github.com/token-hoarder/video-to-script-mvp/blob/main/components/upload-zone.tsx"
click node_ui_button "https://github.com/token-hoarder/video-to-script-mvp/blob/main/components/ui/button.tsx"
click node_ui_card "https://github.com/token-hoarder/video-to-script-mvp/blob/main/components/ui/card.tsx"
click node_ui_input "https://github.com/token-hoarder/video-to-script-mvp/blob/main/components/ui/input.tsx"
click node_ui_label "https://github.com/token-hoarder/video-to-script-mvp/blob/main/components/ui/label.tsx"
click node_ui_toast "https://github.com/token-hoarder/video-to-script-mvp/blob/main/components/ui/sonner.tsx"
click node_next_config "https://github.com/token-hoarder/video-to-script-mvp/blob/main/next.config.ts"
click node_vercel_config "https://github.com/token-hoarder/video-to-script-mvp/blob/main/vercel.json"
click node_gha_ai "https://github.com/token-hoarder/video-to-script-mvp/blob/main/.github/workflows/ai-pipeline.yml"
click node_gha_review "https://github.com/token-hoarder/video-to-script-mvp/blob/main/.github/workflows/pr-reviewer.yml"

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_script_cards,node_upload_zone,node_ui_button,node_ui_card,node_ui_input,node_ui_label,node_ui_toast toneBlue
class node_app_layout,node_app_styles,node_home_page,node_login_page,node_login_actions,node_upload_url_api,node_generate_api toneAmber
class node_proxy_middleware,node_supabase_mw,node_supabase_client,node_supabase_server toneMint
class node_next_config,node_vercel_config,node_gha_ai,node_gha_review toneRose
```

## Components

### Client UI

Browser-facing pages and reusable UI components.

- [Script cards](https://github.com/token-hoarder/video-to-script-mvp/blob/main/components/script-cards.tsx): feature component · Dashboard/list view for generated script results. · `components/script-cards.tsx`
- [Upload zone](https://github.com/token-hoarder/video-to-script-mvp/blob/main/components/upload-zone.tsx): feature component · Upload flow UI that requests signed URLs and sends content directly to storage. · `components/upload-zone.tsx`
- [Button](https://github.com/token-hoarder/video-to-script-mvp/blob/main/components/ui/button.tsx): ui primitive · Reusable interface control used across the app. · `components/ui/button.tsx`
- [Card](https://github.com/token-hoarder/video-to-script-mvp/blob/main/components/ui/card.tsx): ui primitive · Reusable container primitive for dashboards and content blocks. · `components/ui/card.tsx`
- [Input](https://github.com/token-hoarder/video-to-script-mvp/blob/main/components/ui/input.tsx): ui primitive · Reusable text input primitive for forms. · `components/ui/input.tsx`
- [Label](https://github.com/token-hoarder/video-to-script-mvp/blob/main/components/ui/label.tsx): ui primitive · Reusable form label primitive. · `components/ui/label.tsx`
- [Toasts](https://github.com/token-hoarder/video-to-script-mvp/blob/main/components/ui/sonner.tsx): ui primitive · Notification layer used for user feedback. · `components/ui/sonner.tsx`

### Next.js Server

App Router pages, server actions, and route handlers.

- [App shell](https://github.com/token-hoarder/video-to-script-mvp/blob/main/app/layout.tsx): layout · Global app layout and shared document structure. · `app/layout.tsx`
- [Global styles](https://github.com/token-hoarder/video-to-script-mvp/blob/main/app/globals.css): style · Application-wide stylesheet for the shell and pages. · `app/globals.css`
- [Workspace](https://github.com/token-hoarder/video-to-script-mvp/blob/main/app/page.tsx): page · Main authenticated landing page for the product flow. · `app/page.tsx`
- [Login page](https://github.com/token-hoarder/video-to-script-mvp/blob/main/app/login/page.tsx): page · Sign-in screen for unauthenticated users. · `app/login/page.tsx`
- [Login action](https://github.com/token-hoarder/video-to-script-mvp/blob/main/app/login/actions.ts): server action · Server-side login submission and session creation. · `app/login/actions.ts`
- [Upload URL](https://github.com/token-hoarder/video-to-script-mvp/blob/main/app/api/upload-url/route.ts): route handler · API endpoint that issues a signed upload URL or token. · `app/api/upload-url/route.ts`
- [Generate script](https://github.com/token-hoarder/video-to-script-mvp/blob/main/app/api/generate-script/route.ts): route handler · API endpoint that creates scripts from uploaded content. · `app/api/generate-script/route.ts`

### Auth & Data

Supabase-backed session, identity, and storage helpers.

- [Proxy](https://github.com/token-hoarder/video-to-script-mvp/blob/main/proxy.ts): middleware · Edge layer for session refresh and route protection. · `proxy.ts`
- [Middleware auth](https://github.com/token-hoarder/video-to-script-mvp/blob/main/utils/supabase/middleware.ts): supabase helper · Supabase session handling in the middleware runtime. · `utils/supabase/middleware.ts`
- [Browser client](https://github.com/token-hoarder/video-to-script-mvp/blob/main/utils/supabase/client.ts): supabase helper · Client-side Supabase integration used by UI code. · `utils/supabase/client.ts`
- [Server client](https://github.com/token-hoarder/video-to-script-mvp/blob/main/utils/supabase/server.ts): supabase helper · Server-runtime Supabase integration for actions and routes. · `utils/supabase/server.ts`

### Automation

Build, deployment, and GitHub Actions workflows.

- [Next config](https://github.com/token-hoarder/video-to-script-mvp/blob/main/next.config.ts): build config · Next.js build/runtime configuration. · `next.config.ts`
- [Vercel config](https://github.com/token-hoarder/video-to-script-mvp/blob/main/vercel.json): deploy config · Deployment configuration for the serverless host. · `vercel.json`
- [AI pipeline](https://github.com/token-hoarder/video-to-script-mvp/blob/main/.github/workflows/ai-pipeline.yml): github action · Workflow for AI-related pipeline checks or processing. · `.github/workflows/ai-pipeline.yml`
- [PR reviewer](https://github.com/token-hoarder/video-to-script-mvp/blob/main/.github/workflows/pr-reviewer.yml): github action · Workflow for pull request review automation. · `.github/workflows/pr-reviewer.yml`

## Connections

- Proxy → Middleware auth: refresh session · Edge proxy delegates session handling to Supabase middleware helpers.
- Middleware auth → Server client: session context · Middleware shares auth/session semantics with server-side Supabase usage.
- App shell → Global styles: loads · The app shell imports global styling.
- Workspace → Script cards: renders · The workspace page presents generated scripts.
- Workspace → Upload zone: hosts · The main page includes the upload flow.
- Login page → Login action: submits to · Login form posts through a server action.
- Login page → Input: uses · The login screen uses form inputs.
- Login page → Button: uses · The login screen uses shared button primitives.
- Upload zone → Upload URL: requests · Upload UI fetches a signed URL before sending bytes directly to storage.
- Upload zone → Button: uses · Upload flow uses shared controls.
- Upload zone → Card: uses · Upload flow is wrapped in card UI.
- Upload zone → Toasts: notifies · Upload flow uses toast feedback.
- Script cards → Card: uses · Script listing is composed from card primitives.
- Script cards → Button: uses · Script cards use shared action controls.
- Login action → Server client: authenticates · Server action uses server-side Supabase helpers for sign-in.
- Upload URL → Server client: issues token · Signed upload URLs or tokens are created through server-side Supabase access.
- Generate script → Server client: reads/writes · Script generation route uses server-side Supabase access for data and session-aware work.
- Workspace → Generate script: calls · Workspace triggers script generation through the API route.
- Browser client → Upload zone: used by · Client Supabase helpers support browser-side interactions.
- Browser client → Script cards: used by · Client Supabase helpers may back interactive dashboard behavior.
- Next config → Vercel config: aligns with · Build and deployment settings are coordinated for the serverless target.
- AI pipeline → Generate script: checks · Automation likely exercises the generation pipeline.
- PR reviewer → Workspace: reviews · PR automation covers the application surface.
- PR reviewer → Login page: reviews · PR automation covers the authentication surface.
