# lovelyshades/ai_powered_tech_interview_prep architecture

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

- Interactive diagram: https://gitdiagram.com/lovelyshades/ai_powered_tech_interview_prep
- Repository: https://github.com/lovelyshades/ai_powered_tech_interview_prep

## Overview

##### Project Type and Purpose
- This is a full-stack, real-time web application (“AI Tech Interview”) built with React/Next.js on the frontend, Supabase (Auth, Postgres, Edge Functions) on the backend, and OpenAI’s Realtime APIs (GPT-4o & Whisper) for AI transcription and feedback.
- It simulates a technical interview environment supporting coding, text, and live voice questions, delivering instant or deferred AI-driven feedback.

a. Frontend Application
- Pages (Landing, Interview, Results, NotFound)
- UI Components (AuthDialog, LiveInterviewPanel, MonacoEditor, AnswerPanel, etc.)
- Hooks & State Store (useAuth, useSecureQuestions, sessionStore)
- Client Integrations (Supabase client.ts, OpenAI Realtime bridge in lib/codeRunner.ts)
b. Supabase Services
- Auth & Storage (built-in Supabase features)
- Postgres Database (questions, sessions, answers)
- Edge Functions (evaluate-answer, get-question, realtime-interview, text-to-speech, transcribe-audio)
- Migrations (schema definitions)
c. External AI Services
- OpenAI Realtime API (WebSocket for GPT-4o feedback)
- Whisper Transcription (audio→text)
d. Supporting Utilities
- Audio utils (AudioRecorder, RealtimeAudio, VoicePlayer)
- Shared utils (utils.ts, use-toast, codeRunner)

- User → Frontend (HTTP/WebSocket):
- Auth requests to Supabase Auth
- Page fetches & static assets via Vite/AWS CDN (if deployed)
- Frontend → Supabase Edge Functions (HTTP/REST):
- get-question → fetch interview questions
- evaluate-answer → run code tests or AI evaluation
- text-to-speech → synthesize questions
- transcribe-audio → receive transcripts
- Frontend ↔ Supabase Realtime (WebSocket):
- realtime-interview function bridges audio stream to OpenAI Realtime
- Frontend ↔ OpenAI Realtime API (WebSocket):
- Stream audio & receive live transcription/feedback
- Edge Functions → Database (internal Postgres connection)
- Edge Functions → External OpenAI APIs (HTTP/WebSocket)

##### Architectural Patterns & Principles
- Modular Frontend: clear separation of pages, reusable UI primitives, domain-specific components (auth, interview, UI library).
- Backend as Functions: serverless edge functions isolate each use case (evaluation, transcription, TTS, real-time bridging).
- Reactive State Management: sessionStore drives interview state across panels.
- API Gateway Pattern: Supabase functions act as internal API endpoints.
- Event-Driven Streams: WebSocket streams for real-time audio and AI feedback.

1) User (browser)
2) Frontend App (React/Next.js + hooks + UI)
3) Backend:
– Supabase Edge Functions
– Supabase Auth & Postgres DB
– External AI Services
b. Within the Frontend layer, group:
– Pages & Routing
– Component Library
– State Store & Hooks
– Integrations folder (client.ts)
c. Within the Backend layer, group each edge function as a microservice.
d. Postgres DB below the edge functions, connected via internal lines.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Layer
    User["User (Browser)"]:::user

    %% Frontend Application Layer
    subgraph "Frontend Application"
        direction TB
        subgraph "Pages"
            direction TB
            Landing["Landing Page"]:::frontend
            Interview["Interview Page"]:::frontend
            Results["Results Page"]:::frontend
            NotFound["NotFound Page"]:::frontend
        end
        subgraph "UI Components"
            direction TB
            AuthDialog["AuthDialog"]:::frontend
            AuthButton["AuthButton"]:::frontend
            LiveInterviewPanel["LiveInterviewPanel"]:::frontend
            MonacoEditor["MonacoEditor"]:::frontend
            AnswerPanel["AnswerPanel"]:::frontend
            FeedbackPanel["FeedbackPanel"]:::frontend
            QuestionPanel["QuestionPanel"]:::frontend
            SettingsSheet["SettingsSheet"]:::frontend
            UIPrimitives["UI Primitives Library"]:::frontend
        end
        subgraph "Hooks & State Store"
            direction TB
            useAuth["useAuth"]:::frontend
            useSecureQuestions["useSecureQuestions"]:::frontend
            sessionStore["sessionStore"]:::frontend
        end
        subgraph "Client Integrations"
            direction TB
            SupabaseClient["Supabase Client"]:::frontend
            SupabaseTypes["Supabase Types"]:::frontend
            CodeRunner["OpenAI Realtime Bridge / codeRunner"]:::frontend
        end
    end

    %% Backend Application Layer
    subgraph "Supabase Services"
        direction TB
        subgraph "Edge Functions"
            direction TB
            getQuestion["get-question"]:::backend
            evaluateAnswer["evaluate-answer"]:::backend
            realtimeInterview["realtime-interview"]:::backend
            textToSpeech["text-to-speech"]:::backend
            transcribeAudio["transcribe-audio"]:::backend
        end
        subgraph "Auth & Storage"
            direction TB
            SupabaseAuth["Supabase Auth & Storage"]:::backend
        end
        DB["Postgres Database"]:::database
        subgraph "Config & Migrations"
            direction TB
            configToml["config.toml"]:::backend
            migrations["migrations (*.sql)"]:::backend
        end
    end

    %% External AI Services
    subgraph "External AI Services"
        direction TB
        OpenAIRealtime["OpenAI Realtime API"]:::external
        Whisper["Whisper Transcription"]:::external
    end

    %% Connections
    User -->|"HTTP/WS"| Landing
    User -->|"HTTP/WS"| Interview
    User -->|"HTTP/WS"| Results
    User -->|"HTTP/WS"| NotFound

    %% Frontend internal flows
    Landing -->|renders| AuthDialog
    Interview -->|renders| LiveInterviewPanel
    Interview -->|renders| MonacoEditor
    Interview -->|renders| AnswerPanel
    Interview -->|renders| FeedbackPanel
    Interview -->|renders| QuestionPanel
    Interview -->|renders| SettingsSheet
    AuthDialog -->|uses| useAuth
    LiveInterviewPanel -->|uses| CodeRunner
    MonacoEditor -->|uses| sessionStore
    QuestionPanel -->|uses| useSecureQuestions
    UIPrimitives -->|used by| AuthButton
    UIPrimitives -->|used by| SettingsSheet

    %% Frontend to Supabase Edge Functions
    SupabaseClient -->|HTTP|getQuestion
    SupabaseClient -->|HTTP|evaluateAnswer
    SupabaseClient -->|HTTP|textToSpeech
    SupabaseClient -->|HTTP|transcribeAudio
    CodeRunner -.->|WS|realtimeInterview

    %% Frontend to Auth & Storage
    useAuth -->|Auth Requests| SupabaseAuth

    %% Edge Functions to Database
    getQuestion -->|query| DB
    evaluateAnswer -->|query| DB
    textToSpeech -->|query| DB
    transcribeAudio -->|query| DB
    realtimeInterview -->|query| DB

    %% Edge Functions to External AI
    evaluateAnswer -->|HTTP| OpenAIRealtime
    realtimeInterview -.->|WS Stream| OpenAIRealtime
    realtimeInterview -.->|WS Stream| Whisper
    textToSpeech -->|HTTP| OpenAIRealtime
    transcribeAudio -->|HTTP| OpenAIRealtime

    %% Auth & Storage to DB
    SupabaseAuth -->|manage| DB
    migrations -->|apply| DB

    %% External AI back to Frontend
    OpenAIRealtime -.->|WS Feedback| CodeRunner
    Whisper -.->|WS Transcript| CodeRunner

    %% Click Events
    click Landing "https://github.com/lovelyshades/ai_powered_tech_interview_prep/blob/main/src/pages/Landing.tsx"
    click Interview "https://github.com/lovelyshades/ai_powered_tech_interview_prep/blob/main/src/pages/Interview.tsx"
    click Results "https://github.com/lovelyshades/ai_powered_tech_interview_prep/blob/main/src/pages/Results.tsx"
    click NotFound "https://github.com/lovelyshades/ai_powered_tech_interview_prep/blob/main/src/pages/NotFound.tsx"
    click AuthDialog "https://github.com/lovelyshades/ai_powered_tech_interview_prep/blob/main/src/components/auth/AuthDialog.tsx"
    click AuthButton "https://github.com/lovelyshades/ai_powered_tech_interview_prep/blob/main/src/components/auth/AuthButton.tsx"
    click LiveInterviewPanel "https://github.com/lovelyshades/ai_powered_tech_interview_prep/blob/main/src/components/interview/LiveInterviewPanel.tsx"
    click MonacoEditor "https://github.com/lovelyshades/ai_powered_tech_interview_prep/blob/main/src/components/interview/MonacoEditor.tsx"
    click AnswerPanel "https://github.com/lovelyshades/ai_powered_tech_interview_prep/blob/main/src/components/interview/AnswerPanel.tsx"
    click FeedbackPanel "https://github.com/lovelyshades/ai_powered_tech_interview_prep/blob/main/src/components/interview/FeedbackPanel.tsx"
    click QuestionPanel "https://github.com/lovelyshades/ai_powered_tech_interview_prep/blob/main/src/components/interview/QuestionPanel.tsx"
    click SettingsSheet "https://github.com/lovelyshades/ai_powered_tech_interview_prep/blob/main/src/components/interview/SettingsSheet.tsx"
    click UIPrimitives "https://github.com/lovelyshades/ai_powered_tech_interview_prep/tree/main/src/components/ui/"
    click useAuth "https://github.com/lovelyshades/ai_powered_tech_interview_prep/blob/main/src/hooks/useAuth.ts"
    click useSecureQuestions "https://github.com/lovelyshades/ai_powered_tech_interview_prep/blob/main/src/hooks/useSecureQuestions.ts"
    click sessionStore "https://github.com/lovelyshades/ai_powered_tech_interview_prep/blob/main/src/lib/store/sessionStore.ts"
    click SupabaseClient "https://github.com/lovelyshades/ai_powered_tech_interview_prep/blob/main/src/integrations/supabase/client.ts"
    click SupabaseTypes "https://github.com/lovelyshades/ai_powered_tech_interview_prep/blob/main/src/integrations/supabase/types.ts"
    click CodeRunner "https://github.com/lovelyshades/ai_powered_tech_interview_prep/blob/main/src/lib/codeRunner.ts"
    click getQuestion "https://github.com/lovelyshades/ai_powered_tech_interview_prep/blob/main/supabase/functions/get-question/index.ts"
    click evaluateAnswer "https://github.com/lovelyshades/ai_powered_tech_interview_prep/blob/main/supabase/functions/evaluate-answer/index.ts"
    click realtimeInterview "https://github.com/lovelyshades/ai_powered_tech_interview_prep/blob/main/supabase/functions/realtime-interview/index.ts"
    click textToSpeech "https://github.com/lovelyshades/ai_powered_tech_interview_prep/blob/main/supabase/functions/text-to-speech/index.ts"
    click transcribeAudio "https://github.com/lovelyshades/ai_powered_tech_interview_prep/blob/main/supabase/functions/transcribe-audio/index.ts"
    click configToml "https://github.com/lovelyshades/ai_powered_tech_interview_prep/blob/main/supabase/config.toml"
    click migrations "https://github.com/lovelyshades/ai_powered_tech_interview_prep/tree/main/supabase/migrations/"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0284C7,color:#000
    classDef backend fill:#DDF7DD,stroke:#228B22,color:#000
    classDef external fill:#FFEFD5,stroke:#FF8C00,color:#000
    classDef database fill:#FFFFFF,stroke:#0000CD,stroke-width:2px,shape:cylinder
    classDef user fill:#F5F5F5,stroke:#696969,color:#000

    class Landing,Interview,Results,NotFound,AuthDialog,AuthButton,LiveInterviewPanel,MonacoEditor,AnswerPanel,FeedbackPanel,QuestionPanel,SettingsSheet,UIPrimitives,useAuth,useSecureQuestions,sessionStore,SupabaseClient,SupabaseTypes,CodeRunner frontend
    class getQuestion,evaluateAnswer,realtimeInterview,textToSpeech,transcribeAudio,SupabaseAuth,configToml,migrations backend
    class OpenAIRealtime,Whisper external
    class DB database
    class User user
```
