How token-hoarder/video-to-script-mvp works
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: upload-zone.tsx Upload zone · app/page.tsx Workspace · login/page.tsx Login page · script-cards.tsx Script cards
Components 22
Client UI
Browser-facing pages and reusable UI components.
- Script cards · Dashboard/list view for generated script results.
components/script-cards.tsx - Upload zone · Upload flow UI that requests signed URLs and sends content directly to storage.
components/upload-zone.tsx - Button · Reusable interface control used across the app.
components/ui/button.tsx - Card · Reusable container primitive for dashboards and content blocks.
components/ui/card.tsx - Input · Reusable text input primitive for forms.
components/ui/input.tsx - Label · Reusable form label primitive.
components/ui/label.tsx - Toasts · Notification layer used for user feedback.
components/ui/sonner.tsx
Next.js Server
App Router pages, server actions, and route handlers.
- App shell · Global app layout and shared document structure.
app/layout.tsx - Global styles · Application-wide stylesheet for the shell and pages.
app/globals.css - Workspace · Main authenticated landing page for the product flow.
app/page.tsx - Login page · Sign-in screen for unauthenticated users.
app/login/page.tsx - Login action · Server-side login submission and session creation.
app/login/actions.ts - Upload URL · API endpoint that issues a signed upload URL or token.
app/api/upload-url/route.ts - Generate script · API endpoint that creates scripts from uploaded content.
app/api/generate-script/route.ts
Auth & Data
Supabase-backed session, identity, and storage helpers.
- Proxy · Edge layer for session refresh and route protection.
proxy.ts - Middleware auth · Supabase session handling in the middleware runtime.
utils/supabase/middleware.ts - Browser client · Client-side Supabase integration used by UI code.
utils/supabase/client.ts - Server client · Server-runtime Supabase integration for actions and routes.
utils/supabase/server.ts
Automation
Build, deployment, and GitHub Actions workflows.
- Next config · Next.js build/runtime configuration.
next.config.ts - Vercel config · Deployment configuration for the serverless host.
vercel.json - AI pipeline · Workflow for AI-related pipeline checks or processing.
.github/workflows/ai-pipeline.yml - PR reviewer · Workflow for pull request review automation.
.github/workflows/pr-reviewer.yml
Connections 24
- 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.