> ## Documentation Index
> Fetch the complete documentation index at: https://docs.techeval.ai/llms.txt
> Use this file to discover all available pages before exploring further.

> Under the hood of the Kovi AI Interview Agent: LangGraph state machines, serverless compute, and ultra-low latency WebRTC.

# Architecture & System Design

Kovi is engineered to evaluate technical talent deterministically. Unlike standard conversational AI wrappers, TechEval.ai utilizes a supervisor-worker agent architecture built on LangGraph, deployed entirely on serverless infrastructure (GCP Cloud Run and Vercel) localized in the Mumbai data region.

## The LangGraph State Machine

To prevent the Kovi voice agent from hallucinating positive feedback or drifting off-topic, the interview flow is strictly controlled by a LangGraph supervisor agent. The system does not rely on a single massive prompt; instead, it routes discrete tasks to specialized worker nodes.

* **Supervisor Node:** Manages the overall interview state, tracks the 60-minute time limit, and ensures all 'Must-Ask' technical topics are covered before concluding the session.
* **Context Extraction Worker (RAG):** Utilizes Pinecone and PostgreSQL (Neon) to retrieve specific candidate experience from the parsed resume and align it against the Job Description requirements.
* **Q\&A Generation Worker:** Dynamically generates the next question based on the candidate's previous answer. If the candidate gives a shallow answer about FastAPI or microservices, this worker triggers a "deep dive" sub-routine.
* **Evaluation & Scoring Worker:** An isolated evaluation model that asynchronously grades responses against the objective 10-point rubric, completely separate from the conversational voice model.

## Infrastructure & Technology Stack

The TechEval.ai backend is designed for high concurrency and ultra-low latency, ensuring the automated voice feels instantaneous to the candidate.

| Component | Technology | Purpose |
| :- | :- | :- |
| **API Gateway** | FastAPI (Python) | Handles high-throughput asynchronous requests and webhook dispatching. |
| **Agent Orchestration** | LangGraph | Manages deterministic state transitions and prevents LLM conversational drift. |
| **Compute** | GCP Cloud Run | Serverless scaling allows for processing thousands of concurrent interviews while maintaining the flat ₹150 per interview cost structure. |
| **Vector & State Storage** | Neon & Pinecone | Manages session state checkpoints and Retrieval-Augmented Generation (RAG) for candidate context. |
| **Real-Time Audio** | WebRTC | Delivers sub-500ms conversational audio streaming natively in the browser without plugins. |

## Network Resilience & State Recovery

In regions where 5G networks or home broadband can be unstable, standard WebSocket connections often fail and terminate the interview. Kovi addresses this through persistent state checkpointing.

1. **Checkpointing:** Every time a candidate finishes answering a question (triggered by the 7-second pause rule), the LangGraph state is serialized and saved to the PostgreSQL database.
2. **Disconnection Handling:** If a candidate's WebRTC stream drops, the interview session is paused, not terminated.
3. **Rehydration:** When the candidate clicks their original secure link, the FastAPI backend fetches the latest checkpoint from the database, rehydrates the LangGraph state, and resumes the interview exactly where the connection was lost.

```mermaid theme={null}
sequenceDiagram
    participant C as Candidate Browser (WebRTC)
    participant F as FastAPI Gateway
    participant L as LangGraph Supervisor
    participant DB as Neon(State Checkpoint)
    
    C->>F: Connect to Interview Session
    F->>L: Initialize State Machine
    L->>F: Stream Audio Question 1
    F->>C: Play Audio
    C->>F: Submit Answer (Audio Buffer)
    F->>L: Process Answer
    L->>DB: Save Checkpoint (Question 1 Complete)
    Note over C,F: Network Connection Drops
    C--xF: Connection Lost
    C->>F: Candidate Reconnects via Link
    F->>DB: Fetch Latest Checkpoint
    DB->>F: Return State (Question 1 Complete)
    F->>L: Rehydrate Agent State
    L->>F: Stream Audio Question 2
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.