# tameyer41/liftoff architecture

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

- Interactive diagram: https://gitdiagram.com/tameyer41/liftoff
- Repository: https://github.com/tameyer41/liftoff

## Overview

##### Project Type & Purpose
- This is a full-stack web application (Next.js) that simulates mock interviews and delivers AI-powered feedback.
- The user interacts via their browser (React UI), records a video, which is transcoded client-side, then sent to serverless API routes that call OpenAI’s Whisper (for transcription) and GPT-3.5 Turbo (for feedback). Rate limiting uses Upstash Redis.

##### Main Components
A. Client (Browser/Frontend)
- React pages & components (app/page.tsx, pages/demo.tsx, components/Gradient.js)
- FFmpeg.wasm (public/ffmpeg/dist/ffmpeg-core.*) used in-browser to transcode raw webcam video to MP3.
B. Next.js Serverless Layer (Vercel Edge/Node)
- API Routes under pages/api:
- transcribe.ts → calls OpenAI Whisper
- generate.ts → streams chat responses via OpenAIStream (GPT-3.5-Turbo)
- blocked.ts → checks rate limits via Upstash Redis
- Middleware (middleware.ts) intercepts requests for authentication/rate-limiting.
- app/opengraph-image.tsx runs at the edge for dynamic OG image generation.
C. External Services
- OpenAI API (Whisper & GPT-3.5 Turbo)
- Upstash Redis (serverless Redis for rate limiting)
- Vercel (hosting, edge network, CDN for static assets & edge functions)

##### Data Flow & Interactions
1. User opens the app → Next.js SSR/SSG renders pages. Static assets served from Vercel CDN.
2. User records video via React‐Webcam. FFmpeg.wasm transcodes on client.
3. Frontend POSTs MP3 data to /api/transcribe
↳ Edge function invokes OpenAI Whisper → returns transcript.
4. Frontend streams transcript to /api/generate
↳ Edge function uses OpenAIStream → returns streaming AI feedback.
5. Each API call passes through middleware.ts → blocked.ts uses Upstash Redis to implement rate limits.

##### Architectural Patterns & Design Principles
- Separation of Concerns: UI vs. API vs. external services.
- Serverless functions as micro-endpoints for transcription, generation, and rate-limiting.
- Client-side heavy lifting (FFmpeg) to minimize server load & simplify streaming.
- Edge rendering for performance (SSR, dynamic OG images).

##### Final Checklist
[ ] All major components (Browser, Next.js, API routes, Redis, OpenAI) present
[ ] Notes on architectural patterns (serverless, edge rendering, client transcoding)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Browser Layer
    subgraph "Browser (Frontend)" 
        direction TB
        MainPage["app/page.tsx"]:::frontend
        DemoPage["pages/demo.tsx"]:::frontend
        AppWrapper["pages/_app.tsx"]:::frontend
        SharedLayout["app/layout.tsx"]:::frontend
        GradientComp["components/Gradient.js"]:::frontend
        GlobalStyles["styles/globals.css"]:::frontend
        TailwindConfig["tailwind.config.js"]:::frontend
        subgraph "Client-Side Transcoding"
            direction TB
            FFmpegCoreJS["ffmpeg-core.js"]:::frontend
            FFmpegCoreWASM["ffmpeg-core.wasm"]:::frontend
            FFmpegWorker["ffmpeg-core.worker.js"]:::frontend
        end
    end

    %% API Layer
    subgraph "Serverless/API (Next.js)" 
        direction TB
        Middleware["middleware.ts"]:::api
        Transcribe["pages/api/transcribe.ts"]:::api
        Generate["pages/api/generate.ts"]:::api
        Blocked["pages/api/blocked.ts"]:::api
        OpenGraphGen["app/opengraph-image.tsx"]:::api
        OpenAIStreamUtil["utils/OpenAIStream.ts"]:::api
        NextConfig["next.config.js"]:::api
    end

    %% External Services
    subgraph "External / Cloud Services"
        direction TB
        OpenAIWhisper["OpenAI Whisper"]:::external
        OpenAIGPT["OpenAI GPT-3.5 Turbo"]:::external
        Vercel["Vercel CDN & Edge"]:::external
        UpstashRedis["Upstash Redis"]:::storage
    end

    %% Data Flow
    DemoPage -->|records video & uses FFmpeg| FFmpegCoreJS
    FFmpegCoreJS --> FFmpegCoreWASM
    FFmpegCoreWASM --> FFmpegWorker

    DemoPage -->|POST MP3 data| Middleware
    Middleware -->|auth & rate-limit check| Blocked
    Blocked -->|check| UpstashRedis
    UpstashRedis -->|limit status| Blocked
    Blocked --> Middleware

    Middleware --> Transcribe
    Transcribe -->|calls Whisper API| OpenAIWhisper
    OpenAIWhisper -->|transcript| Transcribe
    Transcribe -->|returns transcript| DemoPage

    DemoPage -->|stream transcript| Middleware
    Middleware --> Generate
    Generate -->|calls GPT-3.5 Turbo| OpenAIGPT
    OpenAIGPT -->|stream tokens| Generate
    Generate -->|stream feedback| DemoPage

    %% Edge OG Image
    Vercel --> OpenGraphGen

    %% Click Events
    click MainPage "https://github.com/tameyer41/liftoff/blob/main/app/page.tsx"
    click DemoPage "https://github.com/tameyer41/liftoff/blob/main/pages/demo.tsx"
    click AppWrapper "https://github.com/tameyer41/liftoff/blob/main/pages/_app.tsx"
    click SharedLayout "https://github.com/tameyer41/liftoff/blob/main/app/layout.tsx"
    click GradientComp "https://github.com/tameyer41/liftoff/blob/main/components/Gradient.js"
    click GlobalStyles "https://github.com/tameyer41/liftoff/blob/main/styles/globals.css"
    click TailwindConfig "https://github.com/tameyer41/liftoff/blob/main/tailwind.config.js"
    click FFmpegCoreJS "https://github.com/tameyer41/liftoff/blob/main/public/ffmpeg/dist/ffmpeg-core.js"
    click FFmpegCoreWASM "https://github.com/tameyer41/liftoff/blob/main/public/ffmpeg/dist/ffmpeg-core.wasm"
    click FFmpegWorker "https://github.com/tameyer41/liftoff/blob/main/public/ffmpeg/dist/ffmpeg-core.worker.js"
    click Transcribe "https://github.com/tameyer41/liftoff/blob/main/pages/api/transcribe.ts"
    click Generate "https://github.com/tameyer41/liftoff/blob/main/pages/api/generate.ts"
    click Blocked "https://github.com/tameyer41/liftoff/blob/main/pages/api/blocked.ts"
    click Middleware "https://github.com/tameyer41/liftoff/blob/main/middleware.ts"
    click OpenGraphGen "https://github.com/tameyer41/liftoff/blob/main/app/opengraph-image.tsx"
    click OpenAIStreamUtil "https://github.com/tameyer41/liftoff/blob/main/utils/OpenAIStream.ts"
    click NextConfig "https://github.com/tameyer41/liftoff/blob/main/next.config.js"

    %% Styles
    classDef frontend fill:#BBDEFB,stroke:#0D47A1,color:#0D47A1
    classDef api fill:#C8E6C9,stroke:#1B5E20,color:#1B5E20
    classDef external fill:#E0E0E0,stroke:#424242,color:#424242
    classDef storage fill:#FFECB3,stroke:#FF6F00,color:#FF6F00
```
