# gautamkmahato/match-fox-v3 architecture

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

- Interactive diagram: https://gitdiagram.com/gautamkmahato/match-fox-v3
- Repository: https://github.com/gautamkmahato/match-fox-v3

## Overview

##### Project type and purpose
- This is a full-stack Next.js application for conducting and managing technical interviews, job postings, resume generation, payments, and related user flows. The `app/` directory contains both React frontend pages and API routes (`app/api/...`). Utility libraries, services, and external integrations are organized under `lib/` and `app/service/`.

##### File structure
- Top-level `app/` contains:
- `(auth)`, `(legal)`, `home`, `dashboard`, `payment`, `privacy`, `settings`, `success` – React pages and nested UI components.
- `app/api/…` – Next.js API route handlers for features: checkout (Razorpay), PayPal, interviews, jobs, resume, reports, user management, webhooks.
- `app/context/` and `app/hooks/` – React Contexts & custom hooks for state management and data fetching on the frontend.
- `app/service/…` – Client-side service modules that call the API routes or external services.
- `lib/` folder provides shared utilities and integrations (payment SDK clients, ratelimiter, queue, Supabase client, prompts, helpers).
- Root config files: `next.config.mjs`, `middleware.js`, `jsconfig.json`, `postcss.config.mjs` etc.

##### README

a. Main components
- Client (Browser/SPA) – Next.js front-end pages, React components, Context/hooks.
- Next.js Server – handles SSR, SSG, and API routes under `app/api/…`.
- Database – Supabase (via `lib/supabase/client.js`).
- External Services – Payment Gateways (Stripe, Razorpay, PayPal), Authentication (Clerk webhooks), LLM/chat agent (OpenAI or Gemini via `lib/queue/geminiQueue.js`), file storage (resume uploads).
- Background/Queue – geminiQueue for async LLM tasks.

b. Relationships & interactions
1. Client issues HTTP requests to Next.js Server:
– Page navigations & data fetching (React → Next.js server → Supabase).
– API calls (e.g., checkout, create-interview, generate-questions).
2. Next.js API routes orchestrate logic:
– Invoke service modules in `app/service/…`.
– Service modules call external SDKs (`lib/paypal`, `lib/razorpay`), Supabase, LLM queue.
3. Webhooks from Payment Gateways & Clerk feed into `/api/webhooks/...`.
4. Background queue processes heavy tasks (chat agent, report generation).
5. Data persisted in Supabase; client subscribes or polls for updates.

c. Architectural patterns & design principles
- App Router (Next.js) – Co-located UI and backend code.
- Layered separation: Presentation (React + Context + Hooks), API layer (Next.js routes), Service/Domain logic (`app/service`), Infrastructure/Integration (`lib/*`).
- Single codebase hosting static assets (`public/`) and serverless functions.
- Event-driven (webhooks, queues) for async tasks.

d. Key technologies & frameworks
- Next.js (App Router, serverless API routes)
- React + Context + Custom Hooks
- Supabase (database + auth? via `lib/supabase`)
- Payment SDKs: PayPal, Stripe, Razorpay
- Background queue (GeminiQueue)
- Clerk (authentication webhook)
- AI LLM prompts & chat integration

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend Layer"
        direction TB
        BROWSER["Browser / React App"]:::frontend
        COMPONENTS["Presentation Components\n(app/_components/,\napp/context/, app/hooks/)"]:::frontend
    end

    BROWSER -->|"uses"| COMPONENTS
    COMPONENTS -->|"HTTP Requests"| NEXTJS

    click BROWSER "https://github.com/gautamkmahato/match-fox-v3/tree/main/app/"
    click COMPONENTS "https://github.com/gautamkmahato/match-fox-v3/tree/main/app/_components/"
    click COMPONENTS "https://github.com/gautamkmahato/match-fox-v3/blob/main/app/context/UserContext.js"
    click COMPONENTS "https://github.com/gautamkmahato/match-fox-v3/blob/main/app/context/usageContext.js"
    click COMPONENTS "https://github.com/gautamkmahato/match-fox-v3/tree/main/app/hooks/"

    %% Backend/API Layer
    subgraph "Backend / API Layer"
        direction TB
        NEXTJS["Next.js Server\n(app/api/)"]:::backend

        subgraph "API Domains"
            direction TB
            API_INTERVIEW["Interview API\n(app/api/interview/)"]:::backend
            API_JOBS["Jobs API\n(app/api/jobs/)"]:::backend
            API_RESUME["Resume API\n(app/api/resume/)"]:::backend
            API_REPORT["Reports API\n(app/api/report/)"]:::backend
            API_USER["User API\n(app/api/user/)"]:::backend
            API_LLM["LLM Endpoint\n(app/api/tools/ask-llm/)"]:::backend
        end

        subgraph "Payment & Webhooks"
            direction TB
            API_CHECKOUT_RAZOR["Razorpay Checkout\n(app/api/checkout/razorpay/)"]:::backend
            API_VERIFY["Verify Payment\n(app/api/verify-payment/)"]:::backend
            API_PAYPAL_CREATE["PayPal Create Order\n(app/api/paypal/create-order/)"]:::backend
            API_PAYPAL_CAPTURE["PayPal Capture Order\n(app/api/paypal/capture-order/)"]:::backend

            API_WEBHOOK_CLERK["Clerk Webhooks\n(app/api/webhooks/clerk/)"]:::backend
            API_WEBHOOK_PAYPAL["PayPal Webhooks\n(app/api/webhooks/paypal/)"]:::backend
            API_WEBHOOK_RAZOR["Razorpay Webhooks\n(app/api/webhooks/razorpay/)"]:::backend
            API_WEBHOOK_STRIPE["Stripe Webhooks\n(app/api/webhooks/stripe/)"]:::backend
        end

        NEXTJS --> API_INTERVIEW
        NEXTJS --> API_JOBS
        NEXTJS --> API_RESUME
        NEXTJS --> API_REPORT
        NEXTJS --> API_USER
        NEXTJS --> API_LLM
        NEXTJS --> API_CHECKOUT_RAZOR
        NEXTJS --> API_VERIFY
        NEXTJS --> API_PAYPAL_CREATE
        NEXTJS --> API_PAYPAL_CAPTURE
        NEXTJS --> API_WEBHOOK_CLERK
        NEXTJS --> API_WEBHOOK_PAYPAL
        NEXTJS --> API_WEBHOOK_RAZOR
        NEXTJS --> API_WEBHOOK_STRIPE
    end

    click NEXTJS "https://github.com/gautamkmahato/match-fox-v3/tree/main/app/api/"
    click API_INTERVIEW "https://github.com/gautamkmahato/match-fox-v3/tree/main/app/api/interview/"
    click API_JOBS "https://github.com/gautamkmahato/match-fox-v3/tree/main/app/api/jobs/"
    click API_RESUME "https://github.com/gautamkmahato/match-fox-v3/tree/main/app/api/resume/"
    click API_REPORT "https://github.com/gautamkmahato/match-fox-v3/tree/main/app/api/report/"
    click API_USER "https://github.com/gautamkmahato/match-fox-v3/tree/main/app/api/user/"
    click API_LLM "https://github.com/gautamkmahato/match-fox-v3/blob/main/app/api/tools/ask-llm/route.js"
    click API_CHECKOUT_RAZOR "https://github.com/gautamkmahato/match-fox-v3/blob/main/app/api/checkout/razorpay/route.js"
    click API_VERIFY "https://github.com/gautamkmahato/match-fox-v3/blob/main/app/api/verify-payment/route.js"
    click API_PAYPAL_CREATE "https://github.com/gautamkmahato/match-fox-v3/blob/main/app/api/paypal/create-order/route.js"
    click API_PAYPAL_CAPTURE "https://github.com/gautamkmahato/match-fox-v3/blob/main/app/api/paypal/capture-order/route.js"
    click API_WEBHOOK_CLERK "https://github.com/gautamkmahato/match-fox-v3/blob/main/app/api/webhooks/clerk/route.js"
    click API_WEBHOOK_PAYPAL "https://github.com/gautamkmahato/match-fox-v3/blob/main/app/api/webhooks/paypal/route.js"
    click API_WEBHOOK_RAZOR "https://github.com/gautamkmahato/match-fox-v3/blob/main/app/api/webhooks/razorpay/route.js"
    click API_WEBHOOK_STRIPE "https://github.com/gautamkmahato/match-fox-v3/blob/main/app/api/webhooks/stripe/route.js"

    %% Service Layer
    subgraph "Service / Domain Layer"
        direction TB
        SERVICE["Service Modules\n(app/service/)"]:::service
    end

    NEXTJS -->|"calls"| SERVICE
    click SERVICE "https://github.com/gautamkmahato/match-fox-v3/tree/main/app/service/"

    %% Infrastructure & Utilities
    subgraph "Infrastructure & Utilities"
        direction TB
        SUPABASE_CLIENT["Supabase Client\n(lib/supabase/client.js)"]:::data
        RAZORPAY_SDK["Razorpay SDK\n(lib/razorpay/razorpay.js)"]:::external
        PAYPAL_SDK["PayPal SDK\n(lib/paypal/paypalClient.js)"]:::external
        QUEUE["LLM Queue Processor\n(lib/queue/geminiQueue.js)"]:::service
        UTILS["Utility Libraries\n(lib/utils/)"]:::service
    end

    SERVICE --> SUPABASE_CLIENT
    SERVICE --> RAZORPAY_SDK
    SERVICE --> PAYPAL_SDK
    SERVICE --> QUEUE
    SERVICE --> UTILS

    click SUPABASE_CLIENT "https://github.com/gautamkmahato/match-fox-v3/blob/main/lib/supabase/client.js"
    click RAZORPAY_SDK "https://github.com/gautamkmahato/match-fox-v3/blob/main/lib/razorpay/razorpay.js"
    click PAYPAL_SDK "https://github.com/gautamkmahato/match-fox-v3/blob/main/lib/paypal/paypalClient.js"
    click QUEUE "https://github.com/gautamkmahato/match-fox-v3/blob/main/lib/queue/geminiQueue.js"
    click UTILS "https://github.com/gautamkmahato/match-fox-v3/tree/main/lib/utils/"

    %% Data Store
    SUPABASE_CLIENT -->|reads/writes| DB["Supabase Database"]:::data

    %% External Services
    subgraph "External Services"
        direction TB
        PGATEWAYS["Payment Gateways\n(Stripe, Razorpay, PayPal)"]:::external
        CLERK["Clerk Auth"]:::external
        LLM_SERVICE["LLM Service\n(OpenAI/Gemini)"]:::external
        STORAGE["File Storage"]:::external
    end

    RAZORPAY_SDK --> PGATEWAYS
    PAYPAL_SDK --> PGATEWAYS
    API_WEBHOOK_STRIPE --> PGATEWAYS
    API_WEBHOOK_RAZOR --> PGATEWAYS
    API_WEBHOOK_PAYPAL --> PGATEWAYS

    API_WEBHOOK_CLERK --> CLERK
    SERVICE --> LLM_SERVICE
    QUEUE --> LLM_SERVICE
    SERVICE --> STORAGE

    %% Global Config & Middleware
    subgraph "Config & Middleware"
        NEXT_CONFIG["next.config.mjs"]:::service
        MIDDLEWARE["middleware.js"]:::service
    end
    NEXT_CONFIG --> NEXTJS
    MIDDLEWARE --> NEXTJS

    click NEXT_CONFIG "https://github.com/gautamkmahato/match-fox-v3/blob/main/next.config.mjs"
    click MIDDLEWARE "https://github.com/gautamkmahato/match-fox-v3/blob/main/middleware.js"

    %% Styles
    classDef frontend fill:#E0F7FA,stroke:#006064,color:#004D40
    classDef backend fill:#E8F5E9,stroke:#2E7D32,color:#1B5E20
    classDef service fill:#FFF3E0,stroke:#EF6C00,color:#E65100
    classDef data fill:#ECEFF1,stroke:#546E7A,color:#37474F
    classDef external fill:#F3E5F5,stroke:#8E24AA,color:#4A148C
```
