# tanjul17/ai-mock-interview architecture

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

- Interactive diagram: https://gitdiagram.com/tanjul17/ai-mock-interview
- Repository: https://github.com/tanjul17/ai-mock-interview

## Overview

##### Main Components

- User Interface Layer:
- Represented primarily by the Next.js “app” directory where the UI pages are organized.
- Separate branches for authentication: sign-in and sign-up pages exist in app/(auth), and the interview flow is found in app/(root)/interview.
- The top-level layout files (app/layout.tsx and sub-layouts) provide the base for dynamic page rendering.

- API Layer (Backend Logic):
- The API endpoints reside under app/api. Specifically, the vapi endpoint (app/api/vapi/generate/route.ts) handles interactions with Vapi, likely for generating interviews or processing voice interactions.
- Additional business logic is handled in the “lib” directory (such as auth.action.ts and general.action.ts) which organizes core actions and utilities.

- Authentication & Data Storage:
- Firebase is used for authentication and data persistence. Note the firebase directory with admin.ts and client.ts which define different client-side and server-side Firebase interactions.
- The README confirms Firebase is responsible for sign-up/sign-in functionalities and data management.

- External Services Integration:
- Vapi AI Voice agents and Google Gemini are explicitly listed in the README.
- Vapi integration is also indicated by vapi references in the project structure and the SDK in lib/vapi.sdk.ts.
- This layer connects the voice agent functionalities with the backend for producing interviews and feedback.

- UI Components & Design System:
- The “components” and nested “components/ui” directories contain reusable UI components (Agent, AuthForm, InterviewCard, and others). These encapsulate the user experience and are based on shadcn/ui elements.
- Tailwind CSS (along with globals.css in the app directory) provides styling.

##### Relationships and Interactions

- The user (client browser) interacts with the UI layer (Next.js pages) that renders layouts, forms, and interviews.
- UI components call API endpoints (via fetch or Next.js server routes) to perform operations such as interview generation and authentication.
- Business logic in lib (actions and utilities) consolidates processing for both frontend actions and API calls.
- Firebase (both via client and admin scripts) mediates user authentication and data storage operations.
- External AI services (Vapi AI and Google Gemini) are reached through the API layer, where the Vapi SDK might encapsulate the voice agent interactions. This chain provides AI-driven interview simulation and feedback.

##### Architectural Patterns and Technologies

- Full-stack Next.js application pattern where frontend and backend coexist.
- Separation of concerns: distinct directories for UI pages (app), reusable components (components), and server/API logic (app/api, lib).
- Integration of external services via dedicated SDKs and API routes.
- Usage of Firebase for authentication/data, ensuring clear segregation between client and server Firebase configurations.
- Adoption of utility-driven design for actions (lib/actions) that reinforces modularity and reusability.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Global Entities
    User["User (Client Browser)"]:::user

    %% Frontend Layer
    subgraph "Frontend (Next.js UI Layer)"
        UIApp["Next.js UI Pages"]:::frontend
        UIAuth["Authentication Pages"]:::frontend
        UIInterview["Interview Pages"]:::frontend
        UILayoutMain["Main Layout (layout.tsx)"]:::frontend
        UILayoutRoot["Interview Layout (root layout.tsx)"]:::frontend
    end

    %% UI Components & Design System
    subgraph "UI Components & Design System"
        UICore["Core Components"]:::component
        UIElements["UI Components (UI Elements)"]:::component
    end

    %% Backend API Layer
    subgraph "Backend API Layer"
        APIEndpoint["Next.js API Endpoint (vapi/generate)"]:::api
        subgraph "Business Logic"
            LibAuth["Auth Action"]:::api
            LibGeneral["General Action"]:::api
        end
    end

    %% Firebase Services
    subgraph "Firebase Services"
        FirebaseAdmin["Firebase Admin"]:::firebase
        FirebaseClient["Firebase Client"]:::firebase
    end

    %% External AI Services
    subgraph "External AI Services"
        AI["Vapi AI & Google Gemini"]:::external
    end

    %% Connections - User and Frontend
    User -->|"initiates"| UIApp
    UIApp -->|"renders"| UIAuth
    UIApp -->|"renders"| UIInterview
    UIApp -->|"uses"| UILayoutMain
    UIApp -->|"uses"| UILayoutRoot
    UIApp -->|"includes"| UICore
    UIApp -->|"includes"| UIElements

    %% Connections - Frontend to API
    UIApp -->|"calls_API"| APIEndpoint
    UIAuth -->|"calls_API"| APIEndpoint
    UIInterview -->|"calls_API"| APIEndpoint

    %% Connections - API layer interactions
    APIEndpoint -->|"triggers"| LibAuth
    APIEndpoint -->|"triggers"| LibGeneral

    %% Connections - API to Firebase Services
    APIEndpoint -->|"stores_data"| FirebaseAdmin
    APIEndpoint -->|"fetches_data"| FirebaseClient
    LibAuth -->|"authenticates"| FirebaseClient
    LibGeneral -->|"processes"| FirebaseClient

    %% Connections - API to External AI Services
    APIEndpoint -->|"integrates_with"| AI
    LibAuth -->|"utilizes_SDK"| AI

    %% Styles and Classes
    classDef frontend fill:#add8e6,stroke:#00008b,stroke-width:2px;
    classDef api fill:#90ee90,stroke:#006400,stroke-width:2px;
    classDef firebase fill:#dda0dd,stroke:#800080,stroke-width:2px;
    classDef external fill:#ffa500,stroke:#ff8c00,stroke-width:2px;
    classDef component fill:#ffcccb,stroke:#d2691e,stroke-width:2px;
    classDef user fill:#ffffcc,stroke:#b8860b,stroke-width:2px;

    %% Click Events for Frontend Layer
    click UIApp "https://github.com/tanjul17/ai-mock-interview/tree/main/app"
    click UIAuth "https://github.com/tanjul17/ai-mock-interview/tree/main/app/(auth)"
    click UIInterview "https://github.com/tanjul17/ai-mock-interview/tree/main/app/(root)/interview"
    click UILayoutMain "https://github.com/tanjul17/ai-mock-interview/blob/main/app/layout.tsx"
    click UILayoutRoot "https://github.com/tanjul17/ai-mock-interview/blob/main/app/(root)/layout.tsx"

    %% Click Events for API Layer
    click APIEndpoint "https://github.com/tanjul17/ai-mock-interview/blob/main/app/api/vapi/generate/route.ts"
    click LibAuth "https://github.com/tanjul17/ai-mock-interview/blob/main/lib/actions/auth.action.ts"
    click LibGeneral "https://github.com/tanjul17/ai-mock-interview/blob/main/lib/actions/general.action.ts"

    %% Click Events for Firebase Services
    click FirebaseAdmin "https://github.com/tanjul17/ai-mock-interview/blob/main/firebase/admin.ts"
    click FirebaseClient "https://github.com/tanjul17/ai-mock-interview/blob/main/firebase/client.ts"

    %% Click Event for External AI Services
    click AI "https://github.com/tanjul17/ai-mock-interview/blob/main/lib/vapi.sdk.ts"

    %% Click Events for UI Components & Design System
    click UICore "https://github.com/tanjul17/ai-mock-interview/tree/main/components"
    click UIElements "https://github.com/tanjul17/ai-mock-interview/tree/main/components/ui"
```
