# vivekvt/mockmentor architecture

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

- Interactive diagram: https://gitdiagram.com/vivekvt/mockmentor
- Repository: https://github.com/vivekvt/mockmentor

## Overview

##### Project Type and Purpose
- Full-stack web application for AI-powered interview practice.
- Frontend: Next.js 15 + React + TypeScript + Tailwind.
- Backend: Next.js API Routes (serverless), MongoDB via Mongoose.
- External AI/ML services: OpenAI GPT, Google AI SDK, HeyGen streaming, Deepgram STT, ElevenLabs TTS.
- Authentication: Clerk.
- Real-time streaming: WebSockets (or SSE).

##### File Structure for Architectural Hints
- app/
- Pages & layout for “upload resume,” “new interview,” “ongoing interview” (React components in app/page.tsx, app/interview/[id]/page.tsx, etc.)
- serverless API endpoints in app/api/* for resume processing, job description processing, interview creation, access-token retrieval, WebSocket handshake, user profile.
- components/
- UI (Radix UI wrappers under components/ui)
- Domain logic hooks (components/logic/*) handling streaming, chat state, connection quality, etc.
- Avatar video component (HeyGen integration).
- lib/
- Configuration (appConfig.ts)
- Mongoose models & MongoDB connector (Interview.ts, User.ts, mongodb.ts)
- Utility functions (utils.ts).
- Public/static assets under public/.
- Root configs: next.config.ts, tsconfig.json, postcss.config.mjs.

##### Extract Key Architectural Insights from README
- Sequence: Resume upload → AI analysis → Job-description intake → Interview creation → Real-time voice/video stream → Feedback.
- Technologies for each step: resume (OpenAI), job analysis (OpenAI), video avatars (HeyGen), voice-chat (Deepgram + ElevenLabs), data storage (MongoDB), auth (Clerk).

a. Main Components
- Client Browser (React UI + hooks)
- Next.js Server (handles SSR/CSR & API Routes)
- Authentication Service (Clerk)
- Database (MongoDB via Mongoose)
- AI Services
- OpenAI GPT (resume & question generation)
- Google AI SDK (optional ML tasks)
- HeyGen Streaming Avatar API
- Deepgram STT (speech-to-text)
- ElevenLabs TTS (text-to-speech)
- WebSocket/Streaming Layer

b. Relationships & Data Flow
1. Client → Next.js Frontend (SSR/CSR pages)
2. Frontend ↔ Clerk for sign-in/out and session tokens
3. Frontend → API Route: upload-resume → Next.js → OpenAI (resume parse) → Store in MongoDB
4. Frontend → API Route: process-job → OpenAI (job-tailored questions)
5. User selects mentor → API Route: create-interview → Create Interview record in MongoDB
6. Client opens WebSocket to Next.js (or separate Node WS server) → negotiate streaming token via API Route: get-access-token → HeyGen + ElevenLabs + Deepgram
7. Live streaming data (audio/video chunks) flows through WS → Client AvatarVideo component renders stream
8. Conversation events stored/updated in MongoDB (message history) via API Routes or direct calls

c. Architectural Patterns & Principles
- Serverless/API-Route microservices pattern
- Separation of concerns: UI components vs. domain logic hooks vs. data layer (lib/)
- Event-driven streaming via WebSockets
- Single Source of Truth: MongoDB for interview sessions, user profiles, history

d. Technologies & Libraries
- Next.js App Router (app/ directory)
- React + TypeScript + Tailwind CSS
- Clerk for auth (middleware.ts)
- Mongoose & MongoDB (lib/mongodb.ts, lib/models/)
- HeyGen, OpenAI, Google AI SDK, Deepgram, ElevenLabs (lib/appwrite.ts, utils)

##### Essential Details
- Context provider (components/logic/context.tsx) linking UI → streaming hooks.
- Auth flow via Clerk (middleware.ts) before any API call.
- Real-time streaming separately from RESTful endpoints.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Side
    subgraph "Client Browser" 
        direction TB
        Pages["React UI & Pages"]:::frontend
        Logic["Domain Logic & Streaming Hooks"]:::frontend
        UIlib["UI Component Library"]:::frontend
        AvatarVideo["Avatar Video"]:::frontend
    end

    %% Backend Side
    subgraph "Backend (Next.js Server)" 
        direction TB
        Clerk["Clerk Auth Middleware"]:::backend

        subgraph "API Routes"
            direction TB
            UR["UploadResume API"]:::backend
            PRS["ProcessResume API"]:::backend
            PJ["ProcessJob API"]:::backend
            CI["CreateInterview API"]:::backend
            GAT["GetAccessToken API"]:::backend
            IR["Interview[ID] API"]:::backend
            UP["UserProfile API"]:::backend
        end

        Streaming["WebSocket / Streaming Layer"]:::backend

        subgraph "Config & Utilities"
            direction TB
            AppConfig["AppConfig"]:::backend
            Utils["Utils"]:::backend
        end

        subgraph "Third-Party Service Helpers"
            direction TB
            Appwrite["Service Integrations (lib/appwrite.ts)"]:::backend
        end
    end

    %% Database
    DB["MongoDB (Mongoose)"]:::database

    %% External Services
    subgraph "External AI/ML Services"
        direction TB
        OpenAI["OpenAI GPT"]:::external
        GoogleAI["Google AI SDK"]:::external
        HeyGen["HeyGen Avatar API"]:::external
        Deepgram["Deepgram STT"]:::external
        ElevenLabs["ElevenLabs TTS"]:::external
    end

    %% Flows
    Pages -->|"uses"| Clerk
    Pages -->|"calls"| UR
    UR -->|"requests parse"| OpenAI
    UR -->|"stores resume"| DB

    Pages -->|"calls"| PRS
    PRS -->|"requests analysis"| OpenAI

    Pages -->|"calls"| PJ
    PJ -->|"requests questions"| OpenAI

    Pages -->|"calls"| CI
    CI -->|"creates record"| DB

    Pages -->|"calls"| GAT
    GAT -->|"provides token"| Streaming

    Streaming -->|"streams audio/video"| HeyGen
    Streaming -->|"streams audio"| Deepgram
    Streaming -->|"streams text"| ElevenLabs
    Streaming -->|"renders"| AvatarVideo

    Pages -->|"fetches/edit"| IR
    IR -->|"reads/writes"| DB

    Pages -->|"calls"| UP
    UP -->|"reads/writes"| DB

    Logic -->|"hooks into"| Streaming
    Logic -->|"manages state"| Pages

    UIlib -->|"provides components"| Pages

    AppConfig -->|"configures"| UR
    Utils -->|"utilities"| PRS
    Appwrite -->|"integrates"| Streaming

    Clerk -->|"guards"| UR
    Clerk -->|"guards"| PRS
    Clerk -->|"guards"| PJ
    Clerk -->|"guards"| CI
    Clerk -->|"guards"| GAT
    Clerk -->|"guards"| IR
    Clerk -->|"guards"| UP

    %% Click Events - Client Browser
    click Pages "https://github.com/vivekvt/mockmentor/blob/main/app/layout.tsx"
    click Pages "https://github.com/vivekvt/mockmentor/blob/main/app/page.tsx"
    click Pages "https://github.com/vivekvt/mockmentor/blob/main/app/interview/new/page.tsx"
    click Pages "https://github.com/vivekvt/mockmentor/blob/main/app/interview/[id]/page.tsx"
    click Pages "https://github.com/vivekvt/mockmentor/tree/main/components/"

    click Logic "https://github.com/vivekvt/mockmentor/blob/main/components/logic/context.tsx"
    click Logic "https://github.com/vivekvt/mockmentor/blob/main/components/logic/useConnectionQuality.ts"
    click Logic "https://github.com/vivekvt/mockmentor/blob/main/components/logic/useConversationState.ts"
    click Logic "https://github.com/vivekvt/mockmentor/blob/main/components/logic/useInterrupt.ts"
    click Logic "https://github.com/vivekvt/mockmentor/blob/main/components/logic/useMessageHistory.ts"
    click Logic "https://github.com/vivekvt/mockmentor/blob/main/components/logic/useStreamingAvatarSession.ts"
    click Logic "https://github.com/vivekvt/mockmentor/blob/main/components/logic/useTextChat.ts"
    click Logic "https://github.com/vivekvt/mockmentor/blob/main/components/logic/useVoiceChat.ts"

    click UIlib "https://github.com/vivekvt/mockmentor/blob/main/components/ui/alert-dialog.tsx"
    click UIlib "https://github.com/vivekvt/mockmentor/blob/main/components/ui/avatar.tsx"
    click UIlib "https://github.com/vivekvt/mockmentor/blob/main/components/ui/badge.tsx"
    click UIlib "https://github.com/vivekvt/mockmentor/blob/main/components/ui/button.tsx"
    click UIlib "https://github.com/vivekvt/mockmentor/blob/main/components/ui/card.tsx"
    click UIlib "https://github.com/vivekvt/mockmentor/blob/main/components/ui/input.tsx"
    click UIlib "https://github.com/vivekvt/mockmentor/blob/main/components/ui/scroll-area.tsx"
    click UIlib "https://github.com/vivekvt/mockmentor/blob/main/components/ui/separator.tsx"
    click UIlib "https://github.com/vivekvt/mockmentor/blob/main/components/theme-provider.tsx"

    click AvatarVideo "https://github.com/vivekvt/mockmentor/blob/main/components/avatar/AvatarVideo.tsx"

    %% Click Events - Backend
    click UR "https://github.com/vivekvt/mockmentor/blob/main/app/api/upload-resume/route.ts"
    click PRS "https://github.com/vivekvt/mockmentor/blob/main/app/api/process-resume/route.ts"
    click PJ "https://github.com/vivekvt/mockmentor/blob/main/app/api/process-job/route.ts"
    click CI "https://github.com/vivekvt/mockmentor/blob/main/app/api/create-interview/route.ts"
    click GAT "https://github.com/vivekvt/mockmentor/blob/main/app/api/get-access-token/route.ts"
    click IR "https://github.com/vivekvt/mockmentor/blob/main/app/api/interview/[id]/route.ts"
    click UP "https://github.com/vivekvt/mockmentor/blob/main/app/api/user-profile/route.ts"

    click Clerk "https://github.com/vivekvt/mockmentor/blob/main/middleware.ts"

    click DB "https://github.com/vivekvt/mockmentor/blob/main/lib/mongodb.ts"
    click DB "https://github.com/vivekvt/mockmentor/blob/main/lib/models/Interview.ts"
    click DB "https://github.com/vivekvt/mockmentor/blob/main/lib/models/User.ts"

    click AppConfig "https://github.com/vivekvt/mockmentor/blob/main/lib/appConfig.ts"
    click Utils "https://github.com/vivekvt/mockmentor/blob/main/lib/utils.ts"
    click Appwrite "https://github.com/vivekvt/mockmentor/blob/main/lib/appwrite.ts"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0366d6,stroke-width:1px;
    classDef backend fill:#D0FFD0,stroke:#228B22,stroke-width:1px;
    classDef external fill:#FFE0B2,stroke:#FF8C00,stroke-width:1px;
    classDef database fill:#E0E0E0,stroke:#555,stroke-width:1px;
```
