# ruturaj-007/zyra-gnani architecture

> Architecture diagram of the GitHub repository ruturaj-007/zyra-gnani, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ruturaj-007/zyra-gnani
- Repository: https://github.com/ruturaj-007/zyra-gnani

## Overview

Zyra is a browser-based, adaptive voice-interview product: a candidate sets up an interview, answers spoken questions, and reviews scores, reasoning, and latency in a results timeline. The backend handles voice turns, interview planning and evaluation, checkpointing, resume, and trace retrieval; the frontend provides setup, live-interview, and results experiences. The sampled backend excerpts support its calls and persistence paths. Frontend interactions and some integrations are documented in the README but their implementation details were not sampled.

Main entry points: [`frontend/lib/api.ts`](https://github.com/ruturaj-007/zyra-gnani/blob/main/frontend/lib/api.ts) (API client), [`backend/app/main.py`](https://github.com/ruturaj-007/zyra-gnani/blob/main/backend/app/main.py) (FastAPI application), [`frontend/app/(root)/interview/[id]/page.tsx`](https://github.com/ruturaj-007/zyra-gnani/blob/main/frontend/app/(root)/interview/%5Bid%5D/page.tsx) (Results page), [`backend/app/routes/voice.py`](https://github.com/ruturaj-007/zyra-gnani/blob/main/backend/app/routes/voice.py) (Voice endpoints)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Candidate experience"]
  node_setup["Interview setup<br/>[page.tsx]"]
  node_interview_page["Interview page<br/>[page.tsx]"]
  node_voice_ui["Voice interaction<br/>[Agent.tsx]"]
  node_audio_capture["Audio capture<br/>[recorder.ts]"]
  node_api_client["API client<br/>[api.ts]"]
  node_candidate_state["Candidate identity<br/>[candidate.ts]"]
  node_results_page["Results page<br/>[page.tsx]"]
  node_trace_timeline["Reasoning timeline<br/>[TraceTimeline.tsx]"]
  node_score_chart["Score chart<br/>[RadarChart.tsx]"]
  node_latency_panel["Latency panel<br/>[LatencyPanel.tsx]"]
end

subgraph group_api["Interview API"]
  node_fastapi["FastAPI application<br/>[main.py]"]
  node_voice_routes["Voice endpoints<br/>[voice.py]"]
  node_resume_route["Resume endpoint"]
  node_trace_route["Trace endpoint<br/>[trace.py]"]
  node_gnani["Speech services client<br/>[gnani.py]"]
  node_schemas["API data models<br/>[schemas.py]"]
end

subgraph group_intelligence["Interview intelligence"]
  node_interview_core["Interview orchestration<br/>[interview_core.py]"]
  node_agent["Planning and evaluation<br/>[agent.py]"]
end

subgraph group_records["Persistence and results"]
  node_neon[("Neon Postgres<br/>[db.py]")]
end

node_candidate(("Candidate"))
node_groq{{"Groq LLM"}}
node_gnani_service{{"Gnani speech APIs"}}

node_candidate -->|"sets interview"| node_setup
node_setup -.->|"submits setup"| node_api_client
node_candidate -->|"speaks answers"| node_voice_ui
node_voice_ui -.->|"records audio"| node_audio_capture
node_voice_ui -.->|"sends voice turns"| node_api_client
node_api_client -->|"calls API"| node_fastapi
node_fastapi -->|"registers routes"| node_voice_routes
node_fastapi -->|"registers routes"| node_resume_route
node_fastapi -->|"registers routes"| node_trace_route
node_voice_routes -->|"handles interview"| node_interview_core
node_voice_routes -->|"transcribes and speaks"| node_gnani
node_interview_core -->|"plans and evaluates"| node_agent
node_interview_core -->|"reads and writes"| node_neon
node_agent -->|"requests LLM"| node_groq
node_gnani -->|"calls speech APIs"| node_gnani_service
node_resume_route -->|"reads checkpoint"| node_neon
node_trace_route -->|"reads trace data"| node_neon
node_trace_route -->|"returns results"| node_api_client
node_api_client -.->|"provides trace"| node_results_page
node_results_page -.->|"shows reasoning"| node_trace_timeline
node_results_page -.->|"shows scores"| node_score_chart
node_results_page -.->|"shows latency"| node_latency_panel
node_candidate_state -.->|"identifies candidate"| node_api_client
node_voice_routes -->|"validates payloads"| node_schemas
node_trace_route -->|"returns trace model"| node_schemas
node_resume_route -->|"returns resume model"| node_schemas
node_fastapi -->|"initializes database"| node_neon

click node_setup "https://github.com/ruturaj-007/zyra-gnani/blob/main/frontend/app/(root)/page.tsx"
click node_interview_page "https://github.com/ruturaj-007/zyra-gnani/blob/main/frontend/app/(root)/interview/%5Bid%5D/page.tsx"
click node_voice_ui "https://github.com/ruturaj-007/zyra-gnani/blob/main/frontend/components/Agent.tsx"
click node_audio_capture "https://github.com/ruturaj-007/zyra-gnani/blob/main/frontend/lib/recorder.ts"
click node_api_client "https://github.com/ruturaj-007/zyra-gnani/blob/main/frontend/lib/api.ts"
click node_candidate_state "https://github.com/ruturaj-007/zyra-gnani/blob/main/frontend/lib/candidate.ts"
click node_results_page "https://github.com/ruturaj-007/zyra-gnani/blob/main/frontend/app/(root)/interview/%5Bid%5D/page.tsx"
click node_trace_timeline "https://github.com/ruturaj-007/zyra-gnani/blob/main/frontend/components/TraceTimeline.tsx"
click node_score_chart "https://github.com/ruturaj-007/zyra-gnani/blob/main/frontend/components/RadarChart.tsx"
click node_latency_panel "https://github.com/ruturaj-007/zyra-gnani/blob/main/frontend/components/LatencyPanel.tsx"
click node_fastapi "https://github.com/ruturaj-007/zyra-gnani/blob/main/backend/app/main.py"
click node_voice_routes "https://github.com/ruturaj-007/zyra-gnani/blob/main/backend/app/routes/voice.py"
click node_resume_route "https://github.com/ruturaj-007/zyra-gnani/blob/main/backend/app/routes/resume_interview.py"
click node_trace_route "https://github.com/ruturaj-007/zyra-gnani/blob/main/backend/app/routes/trace.py"
click node_interview_core "https://github.com/ruturaj-007/zyra-gnani/blob/main/backend/app/interview_core.py"
click node_agent "https://github.com/ruturaj-007/zyra-gnani/blob/main/backend/app/agent.py"
click node_gnani "https://github.com/ruturaj-007/zyra-gnani/blob/main/backend/app/gnani.py"
click node_neon "https://github.com/ruturaj-007/zyra-gnani/blob/main/backend/app/db.py"
click node_schemas "https://github.com/ruturaj-007/zyra-gnani/blob/main/backend/app/schemas.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_setup,node_interview_page,node_voice_ui,node_audio_capture,node_api_client,node_candidate_state,node_results_page,node_trace_timeline,node_score_chart,node_latency_panel toneBlue
class node_fastapi,node_voice_routes,node_resume_route,node_trace_route,node_gnani,node_schemas toneAmber
class node_interview_core,node_agent,node_gnani_service toneMint
class node_neon toneRose
class node_candidate,node_groq toneIndigo
```

## Components

### Candidate experience

- [Interview setup](https://github.com/ruturaj-007/zyra-gnani/blob/main/frontend/app/(root)/page.tsx): `frontend/app/(root)/page.tsx`
- [Interview page](https://github.com/ruturaj-007/zyra-gnani/blob/main/frontend/app/(root)/interview/%5Bid%5D/page.tsx): `frontend/app/(root)/interview/[id]/page.tsx`
- [Voice interaction](https://github.com/ruturaj-007/zyra-gnani/blob/main/frontend/components/Agent.tsx): `frontend/components/Agent.tsx`
- [Audio capture](https://github.com/ruturaj-007/zyra-gnani/blob/main/frontend/lib/recorder.ts): `frontend/lib/recorder.ts`
- [API client](https://github.com/ruturaj-007/zyra-gnani/blob/main/frontend/lib/api.ts): `frontend/lib/api.ts`
- [Candidate identity](https://github.com/ruturaj-007/zyra-gnani/blob/main/frontend/lib/candidate.ts): `frontend/lib/candidate.ts`
- [Results page](https://github.com/ruturaj-007/zyra-gnani/blob/main/frontend/app/(root)/interview/%5Bid%5D/page.tsx): `frontend/app/(root)/interview/[id]/page.tsx`
- [Reasoning timeline](https://github.com/ruturaj-007/zyra-gnani/blob/main/frontend/components/TraceTimeline.tsx): `frontend/components/TraceTimeline.tsx`
- [Score chart](https://github.com/ruturaj-007/zyra-gnani/blob/main/frontend/components/RadarChart.tsx): `frontend/components/RadarChart.tsx`
- [Latency panel](https://github.com/ruturaj-007/zyra-gnani/blob/main/frontend/components/LatencyPanel.tsx): `frontend/components/LatencyPanel.tsx`

### Interview API

- [FastAPI application](https://github.com/ruturaj-007/zyra-gnani/blob/main/backend/app/main.py): `backend/app/main.py`
- [Voice endpoints](https://github.com/ruturaj-007/zyra-gnani/blob/main/backend/app/routes/voice.py): `backend/app/routes/voice.py`
- [Resume endpoint](https://github.com/ruturaj-007/zyra-gnani/blob/main/backend/app/routes/resume_interview.py): `backend/app/routes/resume_interview.py`
- [Trace endpoint](https://github.com/ruturaj-007/zyra-gnani/blob/main/backend/app/routes/trace.py): `backend/app/routes/trace.py`
- [Speech services client](https://github.com/ruturaj-007/zyra-gnani/blob/main/backend/app/gnani.py): `backend/app/gnani.py`
- [API data models](https://github.com/ruturaj-007/zyra-gnani/blob/main/backend/app/schemas.py): `backend/app/schemas.py`

### Interview intelligence

- [Interview orchestration](https://github.com/ruturaj-007/zyra-gnani/blob/main/backend/app/interview_core.py): `backend/app/interview_core.py`
- [Planning and evaluation](https://github.com/ruturaj-007/zyra-gnani/blob/main/backend/app/agent.py): `backend/app/agent.py`

### Persistence and results

- [Neon Postgres](https://github.com/ruturaj-007/zyra-gnani/blob/main/backend/app/db.py): `backend/app/db.py`

### Other components

- **Candidate**
- **Groq LLM**
- **Gnani speech APIs**

## Connections

- Candidate → Interview setup: sets interview (evidence: `README.md`)
- Interview setup → API client: submits setup
- Candidate → Voice interaction: speaks answers (evidence: `README.md`)
- Voice interaction → Audio capture: records audio
- Voice interaction → API client: sends voice turns
- API client → FastAPI application: calls API (evidence: `README.md`)
- FastAPI application → Voice endpoints: registers routes (evidence: `backend/app/main.py`)
- FastAPI application → Resume endpoint: registers routes (evidence: `backend/app/main.py`)
- FastAPI application → Trace endpoint: registers routes (evidence: `backend/app/main.py`)
- Voice endpoints → Interview orchestration: handles interview (evidence: `backend/app/routes/voice.py`)
- Voice endpoints → Speech services client: transcribes and speaks (evidence: `backend/app/routes/voice.py`)
- Interview orchestration → Planning and evaluation: plans and evaluates (evidence: `backend/app/interview_core.py`)
- Interview orchestration → Neon Postgres: reads and writes (evidence: `backend/app/interview_core.py`)
- Planning and evaluation → Groq LLM: requests LLM (evidence: `README.md`)
- Speech services client → Gnani speech APIs: calls speech APIs (evidence: `backend/app/gnani.py`)
- Resume endpoint → Neon Postgres: reads checkpoint (evidence: `backend/app/routes/resume_interview.py`)
- Trace endpoint → Neon Postgres: reads trace data (evidence: `backend/app/routes/trace.py`)
- Trace endpoint → API client: returns results (evidence: `README.md`)
- API client → Results page: provides trace
- Results page → Reasoning timeline: shows reasoning
- Results page → Score chart: shows scores
- Results page → Latency panel: shows latency
- Candidate identity → API client: identifies candidate
- Voice endpoints → API data models: validates payloads (evidence: `backend/app/routes/voice.py`)
- Trace endpoint → API data models: returns trace model (evidence: `backend/app/routes/trace.py`)
- Resume endpoint → API data models: returns resume model (evidence: `backend/app/routes/resume_interview.py`)
- FastAPI application → Neon Postgres: initializes database (evidence: `backend/app/main.py`)
