# vijkumz88/tabletopics architecture

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

- Interactive diagram: https://gitdiagram.com/vijkumz88/tabletopics
- Repository: https://github.com/vijkumz88/tabletopics

## Overview

##### 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.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Presentation (Browser UI)"
        direction TB
        Home["Home / Topic Selection Page"]:::frontend
        PracticeFlow["Practice Flow Page"]:::frontend
        TranscriptView["Transcript View Page"]:::frontend
        FeedbackView["Feedback View Page"]:::frontend
        AppContext["AppContext Provider"]:::frontend
        AudioRecorder["useAudioRecorder Hook"]:::frontend
        AudioVisualizer["AudioVisualizer Component"]:::frontend
        UIPrimitives["UI Primitives"]:::frontend
    end

    %% Backend Layer
    subgraph "Application (Next.js Server)"
        direction TB
        TranscribeAPI["/api/transcribe Route"]:::backend
        FeedbackAPI["/api/generate-feedback Route"]:::backend
    end

    %% External Services
    subgraph "External Services"
        direction TB
        Whisper["OpenAI Whisper API"]:::external
        GPT4o["OpenAI GPT-4o API"]:::external
    end

    %% Data Flow
    Home -->|"select topic"| PracticeFlow
    PracticeFlow -->|"start timers & record"| AudioRecorder
    AudioRecorder -->|"audio blob"| AppContext
    PracticeFlow -->|"FormData(blob)"| TranscribeAPI
    TranscribeAPI -->|"transcribe audio"| Whisper
    Whisper -->|"JSON transcript"| TranscribeAPI
    TranscribeAPI -->|"JSON transcript"| PracticeFlow
    PracticeFlow -->|"store transcript"| AppContext
    PracticeFlow -->|"POST {transcript,duration}"| FeedbackAPI
    FeedbackAPI -->|"generate feedback"| GPT4o
    GPT4o -->|"JSON feedback"| FeedbackAPI
    FeedbackAPI -->|"JSON feedback"| FeedbackView
    TranscriptView -->|"reads transcript from Context"| AppContext
    FeedbackView -->|"reads feedback from Context"| AppContext

    %% Click Events
    click Home "https://github.com/vijkumz88/tabletopics/blob/master/src/app/page.tsx"
    click PracticeFlow "https://github.com/vijkumz88/tabletopics/blob/master/src/app/practice/page.tsx"
    click TranscriptView "https://github.com/vijkumz88/tabletopics/blob/master/src/app/transcript/page.tsx"
    click FeedbackView "https://github.com/vijkumz88/tabletopics/blob/master/src/app/feedback/page.tsx"
    click AppContext "https://github.com/vijkumz88/tabletopics/blob/master/src/lib/context/AppContext.tsx"
    click AudioRecorder "https://github.com/vijkumz88/tabletopics/blob/master/src/lib/hooks/useAudioRecorder.ts"
    click AudioVisualizer "https://github.com/vijkumz88/tabletopics/blob/master/src/components/ui/AudioVisualizer.tsx"
    click TranscribeAPI "https://github.com/vijkumz88/tabletopics/blob/master/src/app/api/transcribe/route.ts"
    click FeedbackAPI "https://github.com/vijkumz88/tabletopics/blob/master/src/app/api/generate-feedback/route.ts"
    click UIPrimitives "https://github.com/vijkumz88/tabletopics/tree/master/src/components/ui/"
    click GlobalLayout "https://github.com/vijkumz88/tabletopics/blob/master/src/app/layout.tsx"

    %% Styles
    classDef frontend fill:#e0f7fa,stroke:#00796b,color:#004d40;
    classDef backend fill:#e8f5e9,stroke:#2e7d32,color:#1b5e20;
    classDef external fill:#fff9c4,stroke:#f9a825,color:#f57f17;
```
