How davidvarghese10/ai-for-hiring-3 works
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: App.jsx React App · main.py API Routes · specch_to_text.py Core Logic · start.sh Launchers
Components 15
Repository
Local app entrypoints and deployment wrappers
- Launchers · Scripts that start the local frontend and backend together
start.sh
Frontend
React/Vite browser client and browser-native features
- Browser UI · Top-level browser experience for collecting inputs and presenting results
- React App · Main frontend application component
frontend/src/App.jsx - Bootstrap · Client entrypoint that mounts the React app
frontend/src/main.jsx - Speech Capture · Browser speech recognition used to capture spoken input locally
- Eye Tracking · In-browser eye tracking capability with no backend dependency
- Input Flow · Collects uploads, text, and captured signals before sending selected data onward
- Vite Config · Frontend dev-server and build configuration
frontend/vite.config.js
Backend
FastAPI adapter around legacy AI and parsing logic
- FastAPI API · Backend API surface exposed on localhost
backend/main.py - API Routes · HTTP endpoints that adapt frontend requests to core processing
backend/main.py - Core Logic · Untouched authoritative module for resume parsing and AI workflows
backend/specch_to_text.py - Resume Parse · Extracts structured resume content from uploaded input
backend/specch_to_text.py - Follow-up AI · Generates interview follow-up prompts from submitted text
backend/specch_to_text.py - Fact Check · Evaluates recognized speech and returns fact-check feedback
backend/specch_to_text.py
External
Third-party inference service
- Groq LLM · External inference service used by backend AI workflows
Connections 17
- 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