# hirementis-dev/hirementis-frontend architecture

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

- Interactive diagram: https://gitdiagram.com/hirementis-dev/hirementis-frontend
- Repository: https://github.com/hirementis-dev/hirementis-frontend

## Overview

##### Project type and purpose
- This is a Next.js-based full-stack web application (“Hirementis – AI Interview Platform”).
- Purpose: Provide users with AI-driven mock interviews for real job listings, secure login, interview simulation, feedback reporting, and profile management.

##### File structure
- Top-level directories:
- app/ – Next.js App Router structure (pages, layouts, API routes)
- pages/ – Legacy Next.js Pages Router (coexists during migration)
- components/ – Reusable UI and feature components, organized by domain (e.g. interview-feedback, ui)
- lib/ – Core business logic and SDK wrappers (OpenAI, vapi, auth actions)
- firebase/ – Auth and database client setup (admin.ts, client.ts, actions.ts)
- hooks/ – Custom React hooks for fetching feedback, user profiles, auth state
- data/ – Static data (job listings)
- utils/ – Utility functions (formatting, CSV export, vapi prompt templates)
- public/ – Static assets (intro.mp4)
- types/ – TypeScript type definitions
- Key configuration/build files: next.config.ts, tsconfig.json, eslint.config.mjs, postcss.config.mjs, package.json.

##### Extract architectural insights from README
- Interactive multi-section homepage, jobs browsing, secure login, interview flows, feedback dashboard.
- Real-time job data, AI callouts for question generation and feedback (via OpenAI & custom vapi).
- Temporary “secret key” gate during launch.
- Persistent data for users and interview history (likely stored in Firebase).

##### Main components & their interactions
a. Frontend (Client Browser / Mobile)
- Next.js App Router (app/) serving React Server and Client Components
- UI components (Navbar, HeroSection, Interview pages, Profile dashboard)
b. API Layer (Next.js Serverless Functions in app/api/)
- /generate-question → calls OpenAI/vapi SDK
- /generate-feedback → processes interview answers, returns feedback
- /interviews → CRUD interview records in Firebase
- /upload-imagekit → proxy for ImageKit uploads
c. Business Logic & SDKs (lib/)
- Auth.action.ts connects to Firebase Auth
- openai.sdk.ts, vapi.sdk.ts wrap external AI services
- utils.ts for shared utilities
d. Data Layer
- Firebase Auth (user sign-in, secret key gating)
- Firebase Firestore or Realtime DB (interview records, user profiles)
- ImageKit (avatar, resume, social links uploads)
- Static data/jobs.ts for job listings fallback
e. External Services
- OpenAI API for question/feedback generation
- Vapi API (custom prompt workflows)
- ImageKit for file storage
- Potential analytics or monitoring (not shown, but common)

##### Architectural patterns & design principles
- Component-based UI (Atomic/UI, feature-specific components)
- File-based routing (Next.js App & Pages routers)
- Serverless API endpoints (Next.js functions)
- Separation of concerns: UI ↔ API ↔ Business Logic ↔ Data Layer
- Hybrid rendering: SSR for public pages, client-side fetching for dynamic interview sessions
- Secure data flow: Auth guard on protected routes (app/(auth))

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Presentation Layer
    subgraph "Presentation Layer"
        direction TB
        NextApp["Next.js App Router"]:::presentation
        NextPages["Next.js Pages Router"]:::presentation
        Layout["Global Layout & Styles"]:::presentation
        NextApp --> Layout
        NextPages --> Layout
        NextApp --> GenericUI
        NextApp --> FeatureUI
        NextApp --> InterviewUI
    end

    %% UI Components
    subgraph "UI Components"
        direction TB
        GenericUI["Generic UI Components"]:::presentation
        FeatureUI["Feature Sections & Layouts"]:::presentation
        InterviewUI["Interview Feedback UI"]:::presentation
    end

    %% API Layer
    subgraph "API Layer"
        direction TB
        GenerateQ["/generate-question"]:::api
        GenerateF["/generate-feedback"]:::api
        Interviews["/interviews"]:::api
        UploadImg["/upload-imagekit"]:::api
    end

    %% Business Logic
    subgraph "Business Logic & SDKs"
        direction TB
        OpenAISDK["OpenAI SDK Wrapper"]:::biz
        VapiSDK["Vapi SDK Wrapper"]:::biz
        AuthActions["Auth Actions (Firebase)"]:::biz
        FeedbackOrch["Feedback Generation Orchestration"]:::biz
        Utils["Shared Utilities"]:::biz
    end

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        FirebaseClient["Firebase Client Setup"]:::data
        FirebaseAdmin["Firebase Admin Setup"]:::data
        FirebaseActions["Firebase DB Actions"]:::data
        StaticJobs["Static Job Listings"]:::data
    end

    %% External Services
    subgraph "External Services"
        direction TB
        OpenAI["OpenAI API"]:::external
        Vapi["Vapi API"]:::external
        ImageKit["ImageKit Storage"]:::external
    end

    %% Interactions
    User["User"]:::external
    User -->|"interacts with"| NextApp
    NextApp -->|"calls API"| GenerateQ
    NextApp --> GenerateF
    NextApp --> Interviews
    NextApp --> UploadImg

    GenerateQ -->|"uses"| OpenAISDK
    GenerateQ --> VapiSDK
    GenerateF --> FeedbackOrch
    GenerateF --> OpenAISDK
    GenerateF --> VapiSDK
    GenerateF --> FirebaseActions
    Interviews --> FirebaseActions
    UploadImg --> ImageKit

    OpenAISDK --> OpenAI
    VapiSDK --> Vapi
    AuthActions --> FirebaseClient
    AuthActions --> FirebaseAdmin
    FirebaseActions --> FirebaseClient
    FirebaseActions --> FirebaseAdmin
    StaticJobs --> NextApp

    %% Click Events
    click NextApp "https://github.com/hirementis-dev/hirementis-frontend/tree/main/app/"
    click NextPages "https://github.com/hirementis-dev/hirementis-frontend/tree/main/pages/"
    click Layout "https://github.com/hirementis-dev/hirementis-frontend/blob/main/app/layout.tsx"
    click Layout "https://github.com/hirementis-dev/hirementis-frontend/blob/main/app/globals.css"
    click GenericUI "https://github.com/hirementis-dev/hirementis-frontend/tree/main/components/ui/"
    click FeatureUI "https://github.com/hirementis-dev/hirementis-frontend/blob/main/components/CTASection.tsx"
    click FeatureUI "https://github.com/hirementis-dev/hirementis-frontend/blob/main/components/FeatureSection.tsx"
    click FeatureUI "https://github.com/hirementis-dev/hirementis-frontend/blob/main/components/HeroSection.tsx"
    click FeatureUI "https://github.com/hirementis-dev/hirementis-frontend/blob/main/components/HowItWorks.tsx"
    click FeatureUI "https://github.com/hirementis-dev/hirementis-frontend/blob/main/components/PricingSection.tsx"
    click FeatureUI "https://github.com/hirementis-dev/hirementis-frontend/blob/main/components/TestimonialSection.tsx"
    click FeatureUI "https://github.com/hirementis-dev/hirementis-frontend/blob/main/components/Footer.tsx"
    click FeatureUI "https://github.com/hirementis-dev/hirementis-frontend/blob/main/components/Navbar.tsx"
    click FeatureUI "https://github.com/hirementis-dev/hirementis-frontend/blob/main/components/FullScreenLoader.tsx"
    click FeatureUI "https://github.com/hirementis-dev/hirementis-frontend/blob/main/components/Loader.tsx"
    click InterviewUI "https://github.com/hirementis-dev/hirementis-frontend/tree/main/components/interview-feedback/"
    click GenerateQ "https://github.com/hirementis-dev/hirementis-frontend/blob/main/app/api/generate-question/route.ts"
    click GenerateF "https://github.com/hirementis-dev/hirementis-frontend/blob/main/app/api/generate-feedback/route.ts"
    click Interviews "https://github.com/hirementis-dev/hirementis-frontend/blob/main/app/api/interviews/route.ts"
    click UploadImg "https://github.com/hirementis-dev/hirementis-frontend/blob/main/app/api/upload-imagekit/route.ts"
    click OpenAISDK "https://github.com/hirementis-dev/hirementis-frontend/blob/main/lib/openai.sdk.ts"
    click VapiSDK "https://github.com/hirementis-dev/hirementis-frontend/blob/main/lib/vapi.sdk.ts"
    click VapiSDK "https://github.com/hirementis-dev/hirementis-frontend/blob/main/utils/vapi/prompt.ts"
    click AuthActions "https://github.com/hirementis-dev/hirementis-frontend/blob/main/lib/actions/auth.action.ts"
    click FeedbackOrch "https://github.com/hirementis-dev/hirementis-frontend/blob/main/lib/generate-feedback.ts"
    click Utils "https://github.com/hirementis-dev/hirementis-frontend/blob/main/lib/utils.ts"
    click FirebaseClient "https://github.com/hirementis-dev/hirementis-frontend/blob/main/firebase/client.ts"
    click FirebaseAdmin "https://github.com/hirementis-dev/hirementis-frontend/blob/main/firebase/admin.ts"
    click FirebaseActions "https://github.com/hirementis-dev/hirementis-frontend/blob/main/firebase/actions.ts"
    click StaticJobs "https://github.com/hirementis-dev/hirementis-frontend/blob/main/data/jobs.ts"

    %% Styles
    classDef presentation fill:#E0F7FA,stroke:#006064,color:#000
    classDef api fill:#E8F5E9,stroke:#1B5E20,color:#000
    classDef biz fill:#FFF3E0,stroke:#E65100,color:#000
    classDef data fill:#FFF8E1,stroke:#FF6F00,color:#000
    classDef external fill:#F3E5F5,stroke:#4A148C,color:#000
```
