# hariharan024/hackarena architecture

> Architecture diagram of the GitHub repository hariharan024/hackarena, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hariharan024/hackarena
- Repository: https://github.com/hariharan024/hackarena

## Overview

Sakhi guides a woman from a spoken, typed, or button-selected situation through a stateless conversation to a potential pension match and personalized document checklist. The browser owns the profile and presents the result; FastAPI routes turns to the dialogue engine, which combines language understanding, deterministic eligibility rules, and verified scheme data. Voice input and output are browser features, with optional Gemini extraction and speech fallback. Source excerpts show the main calls; unsampled result-screen details are supported by the README and component excerpts.

Main entry points: [`backend/dialogue.py`](https://github.com/hariharan024/hackarena/blob/main/backend/dialogue.py) (Turn and result flow), [`frontend/src/App.jsx`](https://github.com/hariharan024/hackarena/blob/main/frontend/src/App.jsx) (Conversation UI), [`backend/gemini_service.py`](https://github.com/hariharan024/hackarena/blob/main/backend/gemini_service.py) (Optional Gemini services), [`backend/main.py`](https://github.com/hariharan024/hackarena/blob/main/backend/main.py) (HTTP API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Guidance interface"]
  node_app["Conversation UI<br/>[App.jsx]"]
  node_screens["Guidance screens<br/>[components.jsx]"]
  node_labels["Interface labels<br/>[ui.js]"]
  node_api["API client<br/>[api.js]"]
end

subgraph group_service["Conversation service"]
  node_fastapi["HTTP API<br/>[main.py]"]
  node_dialogue["Turn and result flow<br/>[dialogue.py]"]
end

subgraph group_domain["Pension domain"]
  node_eligibility["Eligibility rules<br/>[eligibility.py]"]
  node_schemes["Schemes and documents<br/>[scheme_data.py]"]
  node_messages["Conversation wording<br/>[messages.py]"]
end

subgraph group_integrations["Voice and language"]
  node_voice["Browser speech<br/>[speech.js]"]
  node_nlu["Tamil and English parser<br/>[nlu.py]"]
  node_gemini["Optional Gemini services<br/>[gemini_service.py]"]
end

node_woman(("Woman user"))
node_browser_speech(("Browser speech services"))
node_google(("Google Gemini"))

node_woman -->|"answers questions"| node_app
node_app -->|"renders screens"| node_screens
node_app -->|"loads labels"| node_labels
node_app -->|"sends turns"| node_api
node_app -->|"controls speech"| node_voice
node_voice -->|"recognizes and speaks"| node_browser_speech
node_voice -->|"requests TTS"| node_api
node_api -->|"calls chat and TTS"| node_fastapi
node_fastapi -->|"handles chat turn"| node_dialogue
node_fastapi -->|"requests speech"| node_gemini
node_dialogue -->|"parses answers"| node_nlu
node_dialogue -.->|"extracts fallback facts"| node_gemini
node_dialogue -->|"evaluates profile"| node_eligibility
node_dialogue -->|"builds checklist"| node_schemes
node_eligibility -->|"reads scheme rules"| node_schemes
node_dialogue -->|"formats replies"| node_messages
node_gemini -->|"validates document keys"| node_schemes
node_gemini -->|"calls model"| node_google

click node_app "https://github.com/hariharan024/hackarena/blob/main/frontend/src/App.jsx"
click node_screens "https://github.com/hariharan024/hackarena/blob/main/frontend/src/components.jsx"
click node_labels "https://github.com/hariharan024/hackarena/blob/main/frontend/src/ui.js"
click node_api "https://github.com/hariharan024/hackarena/blob/main/frontend/src/api.js"
click node_voice "https://github.com/hariharan024/hackarena/blob/main/frontend/src/speech.js"
click node_fastapi "https://github.com/hariharan024/hackarena/blob/main/backend/main.py"
click node_dialogue "https://github.com/hariharan024/hackarena/blob/main/backend/dialogue.py"
click node_nlu "https://github.com/hariharan024/hackarena/blob/main/backend/nlu.py"
click node_gemini "https://github.com/hariharan024/hackarena/blob/main/backend/gemini_service.py"
click node_eligibility "https://github.com/hariharan024/hackarena/blob/main/backend/eligibility.py"
click node_schemes "https://github.com/hariharan024/hackarena/blob/main/backend/scheme_data.py"
click node_messages "https://github.com/hariharan024/hackarena/blob/main/backend/messages.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_app,node_screens,node_labels,node_api,node_woman,node_browser_speech toneBlue
class node_fastapi,node_dialogue toneAmber
class node_eligibility,node_schemes,node_messages toneMint
class node_voice,node_nlu,node_gemini toneRose
class node_google toneIndigo
```

## Components

### Guidance interface

- [Conversation UI](https://github.com/hariharan024/hackarena/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Guidance screens](https://github.com/hariharan024/hackarena/blob/main/frontend/src/components.jsx): `frontend/src/components.jsx`
- [Interface labels](https://github.com/hariharan024/hackarena/blob/main/frontend/src/ui.js): `frontend/src/ui.js`
- [API client](https://github.com/hariharan024/hackarena/blob/main/frontend/src/api.js): `frontend/src/api.js`

### Conversation service

- [HTTP API](https://github.com/hariharan024/hackarena/blob/main/backend/main.py): `backend/main.py`
- [Turn and result flow](https://github.com/hariharan024/hackarena/blob/main/backend/dialogue.py): `backend/dialogue.py`

### Pension domain

- [Eligibility rules](https://github.com/hariharan024/hackarena/blob/main/backend/eligibility.py): `backend/eligibility.py`
- [Schemes and documents](https://github.com/hariharan024/hackarena/blob/main/backend/scheme_data.py): `backend/scheme_data.py`
- [Conversation wording](https://github.com/hariharan024/hackarena/blob/main/backend/messages.py): `backend/messages.py`

### Voice and language

- [Browser speech](https://github.com/hariharan024/hackarena/blob/main/frontend/src/speech.js): `frontend/src/speech.js`
- [Tamil and English parser](https://github.com/hariharan024/hackarena/blob/main/backend/nlu.py): `backend/nlu.py`
- [Optional Gemini services](https://github.com/hariharan024/hackarena/blob/main/backend/gemini_service.py): `backend/gemini_service.py`

### Other components

- **Woman user**
- **Browser speech services**
- **Google Gemini**

## Connections

- Woman user → Conversation UI: answers questions (evidence: `README.md`)
- Conversation UI → Guidance screens: renders screens (evidence: `frontend/src/App.jsx`)
- Conversation UI → Interface labels: loads labels (evidence: `frontend/src/App.jsx`)
- Conversation UI → API client: sends turns (evidence: `frontend/src/App.jsx`)
- Conversation UI → Browser speech: controls speech (evidence: `frontend/src/App.jsx`)
- Browser speech → Browser speech services: recognizes and speaks (evidence: `frontend/src/speech.js`)
- Browser speech → API client: requests TTS (evidence: `frontend/src/speech.js`)
- API client → HTTP API: calls chat and TTS (evidence: `frontend/src/api.js`)
- HTTP API → Turn and result flow: handles chat turn (evidence: `backend/main.py`)
- HTTP API → Optional Gemini services: requests speech (evidence: `backend/main.py`)
- Turn and result flow → Tamil and English parser: parses answers (evidence: `backend/dialogue.py`)
- Turn and result flow → Optional Gemini services: extracts fallback facts (evidence: `backend/main.py`)
- Turn and result flow → Eligibility rules: evaluates profile (evidence: `backend/dialogue.py`)
- Turn and result flow → Schemes and documents: builds checklist (evidence: `backend/dialogue.py`)
- Eligibility rules → Schemes and documents: reads scheme rules (evidence: `backend/eligibility.py`)
- Turn and result flow → Conversation wording: formats replies (evidence: `backend/dialogue.py`)
- Optional Gemini services → Schemes and documents: validates document keys (evidence: `backend/gemini_service.py`)
- Optional Gemini services → Google Gemini: calls model (evidence: `backend/gemini_service.py`)
