# davidvarghese10/ai-for-hiring-3 architecture

> Architecture diagram of the GitHub repository davidvarghese10/ai-for-hiring-3, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/davidvarghese10/ai-for-hiring-3
- Repository: https://github.com/davidvarghese10/ai-for-hiring-3

## Overview

1. **Overall architecture**
   - This is a two-process local application: a **React/Vite frontend** in the browser and a **FastAPI backend** on the machine.
   - The app is designed to run on **localhost only**: frontend on `5173`, backend on `8000`.
   - The frontend handles browser-native capabilities directly; the backend handles heavier AI/processing work.

2. **Frontend subsystem**
   - Located under `frontend/`.
   - Built with **React** and **Vite** (`src/App.jsx`, `src/main.jsx`, `vite.config.js`).
   - The frontend is the user-facing orchestration layer: it collects inputs, shows results, and sends selected data to the backend over HTTP.

3. **Backend subsystem**
   - Located under `backend/`.
   - Exposes API endpoints through **FastAPI** (`backend/main.py`) and runs with **Uvicorn**.
   - Acts as a wrapper around the existing AI/processing code in `specch_to_text.py`, rather than reimplementing the core logic.

4. **Legacy/core processing module**
   - `backend/specch_to_text.py` is treated as the authoritative processing module and is explicitly described as “untouched.”
   - The README indicates it contains the main AI/processing functions such as:
     - `load_resume()` for resume parsing
     - `run_fact_check()` for fact checking
     - Groq LLM integration for AI responses
   - `main.py` likely exists to make this module accessible via FastAPI endpoints.

5. **Resume parsing flow**
   - User uploads a resume in the frontend.
   - The frontend sends the file or extracted content to the backend.
   - The backend uses `load_resume()` from `specch_to_text.py` to extract/parse the resume and then returns structured output to the UI.
   - This is a backend-mediated flow because parsing and LLM work happen outside the browser.

6. **Follow-up AI flow**
   - The frontend collects a candidate response or interview answer.
   - It sends that text to the backend chat endpoint described in the README as `/api/chat`.
   - The backend forwards the request to Groq-powered LLM logic in `specch_to_text.py` and returns generated follow-up questions or prompts.

7. **Fact-checking flow**
   - The frontend uses the **Web Speech API** to capture spoken input in the browser.
   - The recognized text is sent to the backend.
   - The backend calls `run_fact_check()` in `specch_to_text.py`, which uses the Groq API to evaluate the content and produce fact-check feedback.

8. **Eye-tracking subsystem**
   - Eye tracking is handled **entirely in the browser** using **MediaPipe** according to the README.
   - This subsystem does not depend on the backend, making it a separate client-side capability.
   - Architecturally, it is a good example of a local, compute-in-browser feature versus backend-assisted AI features.

9. **External dependency boundary**
   - The only clearly relevant external service is **Groq**, used for LLM inference.
   - Although the app is “local” in deployment terms, it is not fully offline because AI features depend on Groq API calls from the backend.
   - The Groq API key is configured directly in `backend/specch_to_text.py`.

10. **Runtime and startup model**
    - Frontend runtime: Node.js toolchain during development, served via Vite.
    - Backend runtime: Python 3.10+ with FastAPI/Uvicorn.
    - The provided `start.sh` and `start.bat` scripts are launchers that start both sides for local use.

11. **Repository boundaries**
    - `frontend/` is responsible for presentation, browser APIs, and sending requests.
    - `backend/` is responsible for API exposure and AI/processing orchestration.
    - `specch_to_text.py` is a protected core module that should remain unchanged, which suggests the architecture intentionally separates integration code from original logic.

12. **Deployment/config artifacts**
    - `render.yaml` exists, but the README frames this repository as a local-only setup, so it is not part of the primary architecture described here.
    - `resume.txt` appears to be sample input data rather than a core subsystem.

13. **How to draw the diagram**
    - Draw a browser client box containing the React UI plus eye tracking, speech capture, and input collection.
    - Draw a backend API box for FastAPI/Uvicorn with a boundary to `specch_to_text.py`.
    - Show Groq as an external service connected only to the backend.
    - Show direct browser-only arrows for eye tracking, and browser-to-backend arrows for resume parsing, follow-up generation, and fact checking.

Main entry points: [`frontend/src/App.jsx`](https://github.com/davidvarghese10/ai-for-hiring-3/blob/main/frontend/src/App.jsx) (React App), [`backend/main.py`](https://github.com/davidvarghese10/ai-for-hiring-3/blob/main/backend/main.py) (API Routes), [`backend/specch_to_text.py`](https://github.com/davidvarghese10/ai-for-hiring-3/blob/main/backend/specch_to_text.py) (Core Logic), [`start.sh`](https://github.com/davidvarghese10/ai-for-hiring-3/blob/main/start.sh) (Launchers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_root["Repository"]
  node_launchers["Launchers<br/>shell/batch<br/>[start.sh]"]
end

subgraph group_frontend["Frontend"]
  node_browser_ui["Browser UI<br/>client shell"]
  node_react_app["React App<br/>[App.jsx]"]
  node_app_bootstrap["Bootstrap<br/>react entry<br/>[main.jsx]"]
  node_speech_capture(("Speech Capture<br/>web speech"))
  node_eye_tracking(("Eye Tracking<br/>mediapipe"))
  node_input_orchestrator["Input Flow<br/>ui orchestration"]
  node_vite_config["Vite Config<br/>build config<br/>[vite.config.js]"]
end

subgraph group_backend["Backend"]
  node_api_server["FastAPI API<br/>http server<br/>[main.py]"]
  node_api_routes["API Routes<br/>endpoint layer<br/>[main.py]"]
  node_legacy_core["Core Logic<br/>legacy processor<br/>[specch_to_text.py]"]
  node_resume_parse["Resume Parse<br/>parser<br/>[specch_to_text.py]"]
  node_followup_ai["Follow-up AI<br/>llm flow<br/>[specch_to_text.py]"]
  node_fact_check["Fact Check<br/>llm flow<br/>[specch_to_text.py]"]
end

subgraph group_external["External"]
  node_groq[("Groq LLM<br/>external ai")]
end

node_launchers -->|"starts"| node_browser_ui
node_launchers -->|"starts"| node_api_server
node_app_bootstrap -->|"mounts"| node_react_app
node_react_app -->|"drives"| node_input_orchestrator
node_react_app -->|"uses"| node_speech_capture
node_react_app -->|"uses"| node_eye_tracking
node_react_app -->|"HTTP"| node_api_routes
node_input_orchestrator -->|"submits"| node_api_routes
node_api_server -->|"serves"| node_api_routes
node_api_routes -->|"delegates"| node_legacy_core
node_legacy_core -->|"parses"| node_resume_parse
node_legacy_core -->|"generates"| node_followup_ai
node_legacy_core -->|"evaluates"| node_fact_check
node_resume_parse -->|"calls"| node_groq
node_followup_ai -->|"calls"| node_groq
node_fact_check -->|"calls"| node_groq
node_speech_capture -->|"sends text"| node_api_routes

click node_launchers "https://github.com/davidvarghese10/ai-for-hiring-3/blob/main/start.sh"
click node_react_app "https://github.com/davidvarghese10/ai-for-hiring-3/blob/main/frontend/src/App.jsx"
click node_app_bootstrap "https://github.com/davidvarghese10/ai-for-hiring-3/blob/main/frontend/src/main.jsx"
click node_vite_config "https://github.com/davidvarghese10/ai-for-hiring-3/blob/main/frontend/vite.config.js"
click node_api_server "https://github.com/davidvarghese10/ai-for-hiring-3/blob/main/backend/main.py"
click node_api_routes "https://github.com/davidvarghese10/ai-for-hiring-3/blob/main/backend/main.py"
click node_legacy_core "https://github.com/davidvarghese10/ai-for-hiring-3/blob/main/backend/specch_to_text.py"
click node_resume_parse "https://github.com/davidvarghese10/ai-for-hiring-3/blob/main/backend/specch_to_text.py"
click node_followup_ai "https://github.com/davidvarghese10/ai-for-hiring-3/blob/main/backend/specch_to_text.py"
click node_fact_check "https://github.com/davidvarghese10/ai-for-hiring-3/blob/main/backend/specch_to_text.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_launchers toneBlue
class node_browser_ui,node_react_app,node_app_bootstrap,node_speech_capture,node_eye_tracking,node_input_orchestrator,node_vite_config toneAmber
class node_api_server,node_api_routes,node_legacy_core,node_resume_parse,node_followup_ai,node_fact_check toneMint
class node_groq toneRose
```

## Components

### Repository

Local app entrypoints and deployment wrappers

- [Launchers](https://github.com/davidvarghese10/ai-for-hiring-3/blob/main/start.sh): shell/batch · Scripts that start the local frontend and backend together · `start.sh`

### Frontend

React/Vite browser client and browser-native features

- **Browser UI**: client shell · Top-level browser experience for collecting inputs and presenting results
- [React App](https://github.com/davidvarghese10/ai-for-hiring-3/blob/main/frontend/src/App.jsx): react · Main frontend application component · `frontend/src/App.jsx`
- [Bootstrap](https://github.com/davidvarghese10/ai-for-hiring-3/blob/main/frontend/src/main.jsx): react entry · Client entrypoint that mounts the React app · `frontend/src/main.jsx`
- **Speech Capture**: web speech · Browser speech recognition used to capture spoken input locally
- **Eye Tracking**: mediapipe · In-browser eye tracking capability with no backend dependency
- **Input Flow**: ui orchestration · Collects uploads, text, and captured signals before sending selected data onward
- [Vite Config](https://github.com/davidvarghese10/ai-for-hiring-3/blob/main/frontend/vite.config.js): build config · Frontend dev-server and build configuration · `frontend/vite.config.js`

### Backend

FastAPI adapter around legacy AI and parsing logic

- [FastAPI API](https://github.com/davidvarghese10/ai-for-hiring-3/blob/main/backend/main.py): http server · Backend API surface exposed on localhost · `backend/main.py`
- [API Routes](https://github.com/davidvarghese10/ai-for-hiring-3/blob/main/backend/main.py): endpoint layer · HTTP endpoints that adapt frontend requests to core processing · `backend/main.py`
- [Core Logic](https://github.com/davidvarghese10/ai-for-hiring-3/blob/main/backend/specch_to_text.py): legacy processor · Untouched authoritative module for resume parsing and AI workflows · `backend/specch_to_text.py`
- [Resume Parse](https://github.com/davidvarghese10/ai-for-hiring-3/blob/main/backend/specch_to_text.py): parser · Extracts structured resume content from uploaded input · `backend/specch_to_text.py`
- [Follow-up AI](https://github.com/davidvarghese10/ai-for-hiring-3/blob/main/backend/specch_to_text.py): llm flow · Generates interview follow-up prompts from submitted text · `backend/specch_to_text.py`
- [Fact Check](https://github.com/davidvarghese10/ai-for-hiring-3/blob/main/backend/specch_to_text.py): llm flow · Evaluates recognized speech and returns fact-check feedback · `backend/specch_to_text.py`

### External

Third-party inference service

- **Groq LLM**: external ai · External inference service used by backend AI workflows

## Connections

- Launchers → Browser UI: starts · Local startup scripts launch the frontend
- Launchers → FastAPI API: starts · Local startup scripts launch the backend
- Bootstrap → React App: mounts · Client entrypoint renders the main React app
- React App → Input Flow: drives · UI coordinates user inputs and result presentation
- React App → Speech Capture: uses · Browser speech recognition feeds text into the app
- React App → Eye Tracking: uses · Browser-only eye tracking runs independently of the backend
- React App → API Routes: HTTP · Selected inputs are sent to backend endpoints
- Input Flow → API Routes: submits · Uploads and extracted text are forwarded for server-side processing
- FastAPI API → API Routes: serves · FastAPI exposes the application endpoints
- API Routes → Core Logic: delegates · Routes hand off work to the protected processing module
- Core Logic → Resume Parse: parses · Resume extraction is implemented in the core module
- Core Logic → Follow-up AI: generates · Chat/follow-up responses are produced by the core module
- Core Logic → Fact Check: evaluates · Fact-checking workflow is implemented in the core module
- Resume Parse → Groq LLM: calls · Parsing and associated AI workflows can use Groq-backed inference
- Follow-up AI → Groq LLM: calls · Follow-up generation depends on Groq LLM responses
- Fact Check → Groq LLM: calls · Fact-checking depends on Groq LLM responses
- Speech Capture → API Routes: sends text · Recognized speech is forwarded to the backend for analysis
