# prish20/prepwise-interview architecture

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

- Interactive diagram: https://gitdiagram.com/prish20/prepwise-interview
- Repository: https://github.com/prish20/prepwise-interview

## Overview

##### Project Type and Purpose
- This is a full-stack web application: an AI-powered mock interview platform (“Prepwise”) built with Next.js (App Router) on the frontend and Firebase (Auth + Firestore) on the backend.
- It leverages external AI services (Vapi for real-time voice interviews, Google Gemini for question generation, OpenAI GPT-4 for feedback).

##### File Structure
- Top-level:
- app/ (Next.js pages and layouts, segmented into (auth) and (root) for public vs. authenticated routes)
- app/api/vapi/generate/route.ts (API route for question generation)
- components/ & components/ui/ (reusable UI components with ShadCN styling)
- firebase/ (client.ts and admin.ts for Firebase SDK setup)
- lib/ (business logic and SDK wrappers: auth.action.ts, general.actions.ts, vapi.sdk.ts)
- constants/ (static configuration)
- types/ (TypeScript type definitions)
- Patterns:
- App Router – layout.tsx files define global and nested layouts
- Feature grouping – (auth) and (root) route groups
- API route encapsulating AI workflows

##### README for Additional Insights
- Architecture overview in “How It Works”:
1) Firebase Auth with session cookies → secure protected routes
2) POST to /api/vapi/generate → Gemini question generation → save to Firestore
3) Real-time voice interview via Vapi SDK
4) Transcript saved → GPT-4 feedback analysis → detailed scoring
- Tech stack clearly calls out Next.js, Firebase, Vapi, Gemini, OpenAI, Tailwind CSS, ShadCN UI, React Hook Form + Zod.

##### Main Components
a. Frontend (Next.js App Router)
- Layouts & pages: sign-in, sign-up, interview list, interview session
b. Authentication Layer
- Firebase Auth (client SDK)
- Session cookie management (admin SDK)
c. API Layer (Next.js API Routes)
- /api/vapi/generate
- Business logic (lib/actions, lib/vapi.sdk.ts)
d. Data Storage
- Firestore (interview records, transcripts, feedback)
e. External AI Services
- Vapi SDK (real-time voice interaction)
- Google Gemini API (question generation)
- OpenAI GPT-4 (feedback analysis)
f. Static Assets & Constants
- Public assets, constants for tech stacks, prompts

##### Relationships and Interactions
- User (browser) → Next.js Frontend → Firebase Auth → Session Cookie
- Authenticated Frontend → Interview UI → calls API route (/api/vapi/generate)
- API route → Gemini API (questions) → Firestore → returns questions to UI
- Interview UI ↔ Vapi SDK ↔ Vapi service (streaming voice)
- On call end: UI sends transcript → API route or lib/sdk → OpenAI GPT-4 → Firestore (feedback) → UI fetches/display feedback

##### Architectural Patterns and Design Principles
- Separation of concerns: presentation (app/pages + components), business logic (lib/actions), data layer (Firebase SDK, Firestore), external integrations (Vapi, Gemini, GPT-4)
- Feature-based routing with Next.js App Router
- Secure server-side session management via Firebase Admin

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Frontend Layer
    subgraph "Frontend (Next.js)" 
        direction TB
        GlobalLayout["app/layout.tsx"]:::frontend
        RootLayout["app/(root)/layout.tsx"]:::frontend
        AuthLayout["app/(auth)/layout.tsx"]:::frontend
        SignIn["Sign-In Page"]:::frontend
        SignUp["Sign-Up Page"]:::frontend
        InterviewList["Interview List Page"]:::frontend
        InterviewSession["Interview Session Page"]:::frontend
        FeedbackPage["Feedback Page"]:::frontend
        Agent["Agent Component"]:::frontend
        AuthForm["Authentication Form"]:::frontend
        InterviewCard["Interview Card"]:::frontend
        TechIcons["Display Tech Icons"]:::frontend
        FormField["Form Field"]:::frontend
        subgraph "UI Primitives"
            direction TB
            Button["button"]:::frontend
            FormPrim["form"]:::frontend
            Input["input"]:::frontend
            Label["label"]:::frontend
            Sonner["sonner"]:::frontend
        end
    end

    %% Authentication Layer
    subgraph "Authentication Layer"
        direction TB
        FirebaseClient["Firebase Client SDK"]:::backend
        FirebaseAdmin["Firebase Admin SDK"]:::backend
        AuthLogic["auth.action.ts"]:::backend
    end

    %% Backend API Layer
    subgraph "Backend/API"
        direction TB
        APIRoute["/api/vapi/generate"]:::api
        VapiSDK["vapi.sdk.ts"]:::api
        GeneralLogic["general.actions.ts"]:::api
    end

    %% Database
    Firestore["Firestore"]:::db

    %% External AI Services
    subgraph "External AI Services"
        direction TB
        VapiService["Vapi (voice)"]:::external
        Gemini["Google Gemini"]:::external
        GPT4["OpenAI GPT-4"]:::external
    end

    %% Data Flows
    User["User (Browser)"]:::frontend --> NextApp["Next.js Frontend"]:::frontend
    NextApp --> FirebaseClient
    FirebaseClient --> FirebaseAdmin
    FirebaseClient --> AuthLogic
    NextApp --> APIRoute
    APIRoute -->|"HTTPS"| Gemini
    Gemini -->|"questions"| Firestore
    APIRoute -->|"calls"| VapiSDK
    NextApp <-->|"WebSocket/Stream"| VapiService
    NextApp -->|"transcript"| GeneralLogic
    GeneralLogic -->|"calls GPT-4"| GPT4
    GPT4 -->|"feedback"| Firestore
    NextApp --> Firestore

    %% Click Events
    click GlobalLayout "https://github.com/prish20/prepwise-interview/blob/main/app/layout.tsx"
    click RootLayout "https://github.com/prish20/prepwise-interview/blob/main/app/(root)/layout.tsx"
    click AuthLayout "https://github.com/prish20/prepwise-interview/blob/main/app/(auth)/layout.tsx"
    click SignIn "https://github.com/prish20/prepwise-interview/blob/main/app/(auth)/sign-in/page.tsx"
    click SignUp "https://github.com/prish20/prepwise-interview/blob/main/app/(auth)/sign-up/page.tsx"
    click InterviewList "https://github.com/prish20/prepwise-interview/blob/main/app/(root)/interview/page.tsx"
    click InterviewSession "https://github.com/prish20/prepwise-interview/blob/main/app/(root)/interview/[id]/page.tsx"
    click FeedbackPage "https://github.com/prish20/prepwise-interview/blob/main/app/(root)/interview/[id]/feedback/page.tsx"
    click Agent "https://github.com/prish20/prepwise-interview/blob/main/components/Agent.tsx"
    click AuthForm "https://github.com/prish20/prepwise-interview/blob/main/components/AuthForm.tsx"
    click InterviewCard "https://github.com/prish20/prepwise-interview/blob/main/components/InterviewCard.tsx"
    click TechIcons "https://github.com/prish20/prepwise-interview/blob/main/components/DisplayTechIcons.tsx"
    click FormField "https://github.com/prish20/prepwise-interview/blob/main/components/FormField.tsx"
    click Button "https://github.com/prish20/prepwise-interview/blob/main/components/ui/button.tsx"
    click FormPrim "https://github.com/prish20/prepwise-interview/blob/main/components/ui/form.tsx"
    click Input "https://github.com/prish20/prepwise-interview/blob/main/components/ui/input.tsx"
    click Label "https://github.com/prish20/prepwise-interview/blob/main/components/ui/label.tsx"
    click Sonner "https://github.com/prish20/prepwise-interview/blob/main/components/ui/sonner.tsx"
    click FirebaseClient "https://github.com/prish20/prepwise-interview/blob/main/firebase/client.ts"
    click FirebaseAdmin "https://github.com/prish20/prepwise-interview/blob/main/firebase/admin.ts"
    click AuthLogic "https://github.com/prish20/prepwise-interview/blob/main/lib/actions/auth.action.ts"
    click APIRoute "https://github.com/prish20/prepwise-interview/blob/main/app/api/vapi/generate/route.ts"
    click VapiSDK "https://github.com/prish20/prepwise-interview/blob/main/lib/vapi.sdk.ts"
    click GeneralLogic "https://github.com/prish20/prepwise-interview/blob/main/lib/actions/general.actions.ts"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0366D6
    classDef backend fill:#DFFFE0,stroke:#2E7D32
    classDef api fill:#E0F7FA,stroke:#00695C
    classDef db fill:#E8EAF6,stroke:#3F51B5
    classDef external fill:#FFF3E0,stroke:#FB8C00
```
