How vijkumz88/tabletopics works
Project Type and Purpose
• This is a full-stack web application (Next.js) acting as an AI-powered speech coach.
• Frontend: React/TypeScript UI for topic selection, timers, in-browser audio recording, and displaying transcript/feedback.
• Backend: Next.js API routes that invoke OpenAI Whisper (for transcription) and GPT-4o (for feedback analysis).
File Structure Highlights
• src/app/… – Next.js “app router” pages and API endpoints:
• /practice/page.tsx – Orchestrates topic fetch, timers, recording, and workflow.
• /api/transcribe/route.ts – Receives audio blob → calls Whisper → returns text.
• /api/generate-feedback/route.ts – Receives transcript + duration → calls GPT-4o → returns JSON feedback.
• /feedback, /transcript pages – Render the results.
• src/components/ui/ – Reusable UI primitives (buttons, progress, dialogs, visualizers).
• src/lib/context/AppContext.tsx – Global React context for topic, audio, transcript, feedback.
• src/lib/hooks/useAudioRecorder.ts – MediaRecorder abstraction for capturing microphone input.
• Configuration/build: next.config.js, tailwind.config.js, tsconfig.json, postcss.config.js.
Key Architectural Patterns
• “Serverless” API routes inside Next.js handle backend logic.
• React Context for cross-page state management.
• Custom hook for encapsulating browser MediaRecorder.
• API/Client separation: pages call endpoints via fetch().
Core Components
a. Frontend (Browser)
• UI Pages & Components – PracticeFlow, TranscriptView, FeedbackView.
• AudioRecorder Module – useAudioRecorder hook & AudioVisualizer UI.
• Context Provider – AppContext.
b. Backend (Next.js Server)
• API Route: /api/transcribe → OpenAI Whisper service.
• API Route: /api/generate-feedback → OpenAI GPT-4o service.
c. External Services
• OpenAI Whisper API (speech-to-text).
• OpenAI GPT-4o API (feedback generation).
d. Supporting Tools
• Next.js runtime & routing.
• Tailwind CSS / Shadcn UI for styling.
• Environment (env.local for OPENAI_API_KEY).
Data Flow & Interactions
1. User requests a “topic” and starts practice (frontend).
2. Preparation timer → Recording timer kicks in.
3. AudioRecorder captures audio blob → pushes it into AppContext.
4. Frontend POSTs FormData(blob) to /api/transcribe.
5. /api/transcribe calls Whisper → returns transcript.
6. Frontend stores transcript in AppContext.
7. Frontend POSTs { transcript, duration } to /api/generate-feedback.
8. /api/generate-feedback calculates WPM, builds prompt → GPT-4o → structured JSON feedback.
9. Frontend displays feedback and transcript pages.
Architectural Patterns & Principles
• Single-Page App with serverless backend routes.
• Separation of concerns: UI vs. state vs. data-processing routes.
• Dependency inversion: UI only depends on abstract fetch endpoints, not OpenAI SDK.
• Reusability: <AudioVisualizer>, <CircularProgress>, dialog, button components.