# abhay-2309/hireez architecture

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

- Interactive diagram: https://gitdiagram.com/abhay-2309/hireez
- Repository: https://github.com/abhay-2309/hireez

## Overview

##### Project type and purpose
- This is a full-stack, server-rendered React/Next.js 14 application (“app/” directory) that serves as an AI-powered recruitment platform.
- It combines UI pages, serverless API routes, database access via Supabase, AI integrations (Hugging Face, Vapi AI), and email services.

##### File structure
- “app/” holds all Next.js page routes and API route handlers (app/api/proxy/route.ts).
- “components/” contains shared UI and feature components (AuthProvider, DashboardLayout, chat & interview widgets, Shadcn UI primitives).
- “lib/” includes wrappers for Supabase, AI calls (ai.ts, vapi.ts), email logic and utilities.
- “supabase/” holds database migrations; Supabase is both DB and file storage.
- Root config files: next.config.js, tailwind.config.ts, tsconfig.json, middleware.ts for global edge logic.
- “hooks/” and “types/” supplement data flow and typings.

##### Extract architectural insights from README
- Data flows from Recruiter Dashboard → Resume parsing (Hugging Face API) → Supabase.
- Recruiters create interview configs stored in Supabase; secure links are emailed.
- Candidates submit forms (Supabase) or take AI-driven interviews (Vapi AI + Hugging Face scoring + Webhooks).
- Results (form responses, recordings, scores) persist in Supabase and feed back to the Recruiter Review Dashboard.

##### Main components
a. Frontend (Next.js 14)
- Pages (app/**) rendered server-side or client-side.
- React Context for auth and state.
- UI components (Shadcn UI + custom).
b. API/Backend (Next.js serverless functions & Lib)
- API route: resume parsing proxy, interview webhooks.
- Lib modules wrap Supabase SDK, AI service calls, email.
c. Database & Storage (Supabase)
- Postgres tables (interview_configs, interview_links, candidate_forms, candidate_emails, etc.).
- Supabase Storage for video/audio files.
d. External AI Services
- Hugging Face API for resume analysis and scoring.
- Vapi AI for interview orchestration and recording.
- Webhook endpoints back into Next.js API.
e. Email Service
- Nodemailer / Resend / EmailJS integration via lib/email.ts.
f. Third-party Clients
- Recruiter’s browser.
- Candidate’s browser.
g. CI/CD & Hosting (implied: Vercel)

##### Relationships and interactions
- Client → Next.js frontend pages.
- Frontend → Next.js API routes (e.g. /api/proxy).
- API routes/lib → Supabase (queries, file uploads) and external AI/email services.
- External services → Webhooks → Next.js API → Supabase.
- Supabase → Frontend via lib/supabase.ts for dashboard metrics, form data, recordings.

##### Architectural patterns and design principles
- Monolithic serverless architecture using Next.js “app” directory.
- Layered separation: UI layer, API layer, data layer, external integrations.
- Context-based state management for authentication and toast notifications.
- Modular components for reusability (Shadcn UI primitives).
- Edge middleware for authentication/redirects.

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% Clients
  subgraph "Clients"
    Recruiter["Recruiter Browser"]:::external
    Candidate["Candidate Browser"]:::external
  end

  %% Frontend Layer
  subgraph "Frontend (Next.js 14, React, TS, Tailwind)"
    subgraph "Pages (app/)"
      Layout["Layout"]:::frontend
      RootPage["Root Page"]:::frontend
      DashboardPage["Dashboard Page"]:::frontend
      InterviewsPage["Interviews Page"]:::frontend
      ApplyPage["Apply Page"]:::frontend
      CandidatesPage["Candidates Page"]:::frontend
      FormBuilder["Form Builder Page"]:::frontend
      FormSubs["Form Submissions Page"]:::frontend
      LiveInterview["Live Interview Page"]:::frontend
      SessionInterview["Interview Session Page"]:::frontend
    end
    subgraph "UI & State"
      AuthProvider["AuthProvider"]:::frontend
      DashboardLayout["DashboardLayout"]:::frontend
      UIPrimitives["Shadcn UI Primitives"]:::frontend
      ChatInterface["Chat Interface"]:::frontend
      VoiceAgent["VoiceAgent"]:::frontend
      RecruiterVoiceAgent["RecruiterVoiceAgent"]:::frontend
    end
    Middleware["Edge Middleware"]:::frontend
  end

  %% API & Business Logic
  subgraph "API & Business Logic (Serverless & Lib)"
    ProxyAPI["Resume Proxy API"]:::api
    SupabaseLib["Supabase SDK Wrapper"]:::api
    AILib["Hugging Face Wrapper"]:::api
    VapiLib["Vapi AI Wrapper"]:::api
    EmailLib["Email Service Wrapper"]:::api
    Utils["Utilities"]:::api
    MockAuth["Mock Auth"]:::api
  end

  %% Database & Storage
  subgraph "Database & Storage (Supabase)"
    Postgres["Postgres Database"]:::db
    Storage["File Storage"]:::db
    Migration1["Pink Lagoon Migration"]:::db
    Migration2["Dusty Ember Migration"]:::db
  end

  %% External Services
  subgraph "External Services"
    HuggingFace["Hugging Face API"]:::externalAI
    VapiAI["Vapi AI"]:::externalAI
    EmailService["Email Service"]:::externalEmail
  end

  %% Connections
  Recruiter -->|views| DashboardPage
  Recruiter -->|views| InterviewsPage
  Candidate -->|views| ApplyPage
  Candidate -->|views| FormBuilder
  Candidate -->|views| FormSubs
  Candidate -->|views| LiveInterview
  Candidate -->|views| SessionInterview

  DashboardPage -->|getDashboardData| SupabaseLib
  InterviewsPage -->|getInterviews| SupabaseLib
  ApplyPage -->|submit application| SupabaseLib
  FormBuilder -->|save config| SupabaseLib
  FormSubs -->|fetch submissions| SupabaseLib
  LiveInterview -->|start session| VapiLib
  SessionInterview -->|join session| VapiLib

  ProxyAPI -->|query| SupabaseLib
  ProxyAPI -->|POST /api/proxy| AILib
  AILib -->|resume parse| HuggingFace
  VapiAI -->|webhook| ProxyAPI
  ProxyAPI -->|handle webhook| VapiLib
  ProxyAPI -->|invoke| EmailLib
  EmailLib -->|send email| EmailService

  SupabaseLib -->|read/write| Postgres
  SupabaseLib -->|upload/download| Storage

  %% Click Events
  click Layout "https://github.com/abhay-2309/hireez/blob/main/app/layout.tsx"
  click RootPage "https://github.com/abhay-2309/hireez/blob/main/app/page.tsx"
  click DashboardPage "https://github.com/abhay-2309/hireez/blob/main/app/dashboard/page.tsx"
  click InterviewsPage "https://github.com/abhay-2309/hireez/blob/main/app/dashboard/interviews/page.tsx"
  click ApplyPage "https://github.com/abhay-2309/hireez/blob/main/app/apply/[slug]/page.tsx"
  click CandidatesPage "https://github.com/abhay-2309/hireez/blob/main/app/candidates/page.tsx"
  click FormBuilder "https://github.com/abhay-2309/hireez/blob/main/app/forms/[formId]/builder/page.tsx"
  click FormSubs "https://github.com/abhay-2309/hireez/blob/main/app/forms/[formId]/submissions/page.tsx"
  click LiveInterview "https://github.com/abhay-2309/hireez/blob/main/app/interview/live/[sessionId]/page.tsx"
  click SessionInterview "https://github.com/abhay-2309/hireez/blob/main/app/interview/session/[sessionId]/page.tsx"
  click AuthProvider "https://github.com/abhay-2309/hireez/blob/main/components/AuthProvider.tsx"
  click DashboardLayout "https://github.com/abhay-2309/hireez/blob/main/components/DashboardLayout.tsx"
  click UIPrimitives "https://github.com/abhay-2309/hireez/tree/main/components/ui/"
  click ChatInterface "https://github.com/abhay-2309/hireez/blob/main/components/chat/ChatInterface.tsx"
  click VoiceAgent "https://github.com/abhay-2309/hireez/blob/main/components/interview/VoiceAgent.tsx"
  click RecruiterVoiceAgent "https://github.com/abhay-2309/hireez/blob/main/components/recruiter/RecruiterVoiceAgent.tsx"
  click Middleware "https://github.com/abhay-2309/hireez/blob/main/middleware.ts"
  click ProxyAPI "https://github.com/abhay-2309/hireez/blob/main/app/api/proxy/route.ts"
  click SupabaseLib "https://github.com/abhay-2309/hireez/blob/main/lib/supabase.ts"
  click AILib "https://github.com/abhay-2309/hireez/blob/main/lib/ai.ts"
  click VapiLib "https://github.com/abhay-2309/hireez/blob/main/lib/vapi.ts"
  click EmailLib "https://github.com/abhay-2309/hireez/blob/main/lib/email.ts"
  click Utils "https://github.com/abhay-2309/hireez/blob/main/lib/utils.ts"
  click MockAuth "https://github.com/abhay-2309/hireez/blob/main/lib/mock-auth.tsx"
  click Migration1 "https://github.com/abhay-2309/hireez/blob/main/supabase/migrations/20250607063731_pink_lagoon.sql"
  click Migration2 "https://github.com/abhay-2309/hireez/blob/main/supabase/migrations/20250607090304_dusty_ember.sql"

  %% Styles
  classDef frontend fill:#D0E8FF,stroke:#0366d6,color:#000
  classDef api fill:#D6F5D6,stroke:#28a745,color:#000
  classDef db fill:#FFE0B2,stroke:#e65100,color:#000
  classDef externalAI fill:#E0C8FF,stroke:#6f42c1,color:#000
  classDef externalEmail fill:#FFF5CC,stroke:#ffd33d,color:#000
  classDef external fill:#C0C0C0,stroke:#6c757d,color:#000
```
