VidEval — Project Guide for AI Coding Agents

What This Project Is

VidEval is a browser-based (client-side, local-first) Next.js 15 app for evaluating videos against custom rubrics using AI providers. Teachers upload a rubric file, select a Google Drive folder with videos, choose an AI provider + API key, and the app evaluates each video and stores results in Google Sheets.

Tech Stack

• Framework: Next.js 15 (App Router)
• Language: TypeScript
• State: Zustand (persisted to localStorage)
• UI: shadcn/ui + Tailwind CSS
• AI Providers: OpenAI, Claude, Gemini, OpenRouter, Groq (all called directly from browser via fetch)
• Storage: Google Sheets (results), Google Drive (videos), localStorage (app state)
• Auth: Google OAuth (GSI)

Key Directories

src/
  app/                          # Next.js App Router
    page.tsx                    # Public homepage
    dashboard/page.tsx          # Authenticated dashboard
    create/page.tsx             # Create evaluation room
    room/[id]/page.tsx          # Room detail (video evaluation)
    settings/page.tsx           # Settings
    api/rubrics/parse/route.ts  # Server-side rubric file parsing
    api/rubrics/summarize/route.ts  # Server-side rubric summarization
  screens/
    RoomDetail.tsx              # Main evaluation orchestrator
    CreateRoom.tsx              # Room creation form
    Dashboard.tsx               # Dashboard screen
    GoogleAuthScreen.tsx        # Google OAuth
  lib/
    aiEvaluator.ts              # Core AI evaluation + transcription
    googleApi.ts                # Google OAuth, Drive, Sheets API
    rubricParser.ts             # Rubric extraction + prompt generation
    rubricSummarizer.ts         # AI rubric summarization
    videoProcessor.ts           # Video clip splitting + screenshot extraction
  stores/
    useAppStore.ts              # Zustand store (rooms, auth, roomVideos)
  types/
    index.ts                    # TypeScript types

Evaluation Flow

1. Auth — User signs in with Google OAuth → access token stored in Zustand
2. Create Room — User picks Drive folder, uploads rubric (CSV/PDF/DOC/DOCX), selects AI provider + enters API key
3. Evaluate — For each video:
   • Split into 30-second clips (videoProcessor.ts)
   • Extract screenshot at midpoint of each clip
   • Get full transcript, split proportionally by time per clip
   • Evaluate each clip with AI using transcript + screenshot (aiEvaluator.ts)
   • Average all clip scores → final video score
   • Append to Google Sheet (googleApi.ts)
4. View Results — Table shows scores per rubric, descriptions, Google Sheet link

State Management (Zustand)

Store: useAppStore

• auth — {isAuthenticated, accessToken, userEmail, userName, userPhoto}
• rooms — array of Room objects (persisted to localStorage)
• roomVideos — Record<roomId, VideoFile[]> (NOT persisted)

Key: video-eval-store in localStorage. Partializes auth and rooms only.

AI Providers & Models

All API calls are made directly from the browser. API keys are user-entered at room creation time.

Google Sheet Storage

• Spreadsheet created in the same Drive folder as the source videos
• Headers: ["Sr.", "Name", "Clips Evaluated", ...rubricNames, "Description"]
• Each evaluation appends one row with averaged scores across all clips
• Spreadsheet ID stored on the Room object

Important Conventions

• All AI calls use fetch (no SDKs)
• JSON responses from AI are parsed via regex \{[\s\S]*\}
• Screenshots are JPEG at max 640px width (base64 encoded)
• Clip duration: 30 seconds
• Scores are averaged and rounded to 2 decimal places
• No backend database — everything is client-side
• Google OAuth uses Google Identity Services (GSI) with token client
• Components use shadcn/ui pattern with cn() utility for className merging

Environment Variables

• NEXT_PUBLIC_GOOGLE_CLIENT_ID — Google OAuth client ID
• NEXT_PUBLIC_GOOGLE_PICKER_API_KEY — Google Picker API key
• NEXT_PUBLIC_GOOGLE_APP_ID — (optional) Google Cloud project number

AI API keys are NOT env vars — entered by user at runtime.

Implementation Docs

See implementation_docs/ for detailed implementation notes:

• clip-based-evaluation.md — Clip evaluation architecture and flow