# nikhileshnarkhede/portfolio-chatbot architecture

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

- Interactive diagram: https://gitdiagram.com/nikhileshnarkhede/portfolio-chatbot
- Repository: https://github.com/nikhileshnarkhede/portfolio-chatbot
- Video tour (about a minute): https://gitdiagram.com/nikhileshnarkhede/portfolio-chatbot/video

## Overview

Portfolio Chatbot is a resume-grounded recruiter Q&A app, with an evaluation console for measuring and applying configuration changes. A user asks in the Streamlit chat; the graph expands the query, routes it, retrieves resume context, generates and sanitizes an answer, and may summarize older history. Ingestion prepares the searchable index. The console runs datasets through the same graph, scores retrieval, grounding, generation, safety, and performance, and supports gates, comparisons, ratings, calibration, noise measurement, and guarded application. Several internal relationships are documented or indexed; unsampled subsystem wiring is not inferred.

Main entry points: [`src/portfolio_chatbot/graph.py`](https://github.com/nikhileshnarkhede/portfolio-chatbot/blob/master/src/portfolio_chatbot/graph.py) (Graph workflow), [`ui/dash/panels.py`](https://github.com/nikhileshnarkhede/portfolio-chatbot/blob/master/ui/dash/panels.py) (Dashboard panels), [`eval/runner.py`](https://github.com/nikhileshnarkhede/portfolio-chatbot/blob/master/eval/runner.py) (Evaluation runner), [`src/portfolio_chatbot/ingestion/build_index.py`](https://github.com/nikhileshnarkhede/portfolio-chatbot/blob/master/src/portfolio_chatbot/ingestion/build_index.py) (Index builder)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_chat["Chat pipeline"]
  node_chat_ui["Chat UI<br/>[chat.py]"]
  node_graph["Graph workflow<br/>[graph.py]"]
  node_query["Query expansion<br/>[expand_query.py]"]
  node_routing["Question routing<br/>[route.py]"]
  node_retrieval["Context retrieval<br/>[retrieve.py]"]
  node_search_tool["Vector search<br/>[retriever_tool.py]"]
  node_generation["Answer generation<br/>[generate.py]"]
  node_llm["Model provider<br/>[provider.py]"]
  node_sanitize["Link sanitization<br/>[sanitize.py]"]
  node_history["History summary<br/>[summarize.py]"]
  node_state["Turn state<br/>[state.py]"]
  node_config["Experiment config<br/>[config.py]"]
end

subgraph group_indexing["Resume indexing"]
  node_resume["Resume source<br/>[parser.py]"]
  node_index_builder["Index builder<br/>[build_index.py]"]
  node_chunker["Resume chunking<br/>[chunker.py]"]
  node_embedder["Text embeddings<br/>[embedder.py]"]
  node_vector_index[("FAISS index<br/>[retriever_tool.py]")]
end

subgraph group_evaluation["Evaluation"]
  node_eval_runner["Evaluation runner<br/>[runner.py]"]
  node_metrics["Evaluation metrics<br/>[retrieval.py]"]
  node_gate["Threshold gate<br/>[gate.py]"]
  node_compare["Experiment comparison<br/>[compare.py]"]
  node_noise["Noise measurement<br/>[noise.py]"]
  node_calibration["Judge calibration<br/>[calibration.py]"]
  node_ratings["Human ratings<br/>[ratings.py]"]
  node_apply["Config application<br/>[apply.py]"]
end

subgraph group_console["Evaluation console"]
  node_dashboard["Dashboard entry<br/>[dashboard.py]"]
  node_panels["Dashboard panels<br/>[panels.py]"]
  node_dashboard_state["Dashboard state<br/>[state.py]"]
end

node_user(("Recruiter"))
node_groq{{"Groq service"}}

node_user -->|"asks"| node_chat_ui
node_chat_ui -->|"invokes"| node_graph
node_graph -->|"dispatches"| node_query
node_graph -->|"dispatches"| node_routing
node_graph -->|"dispatches"| node_retrieval
node_graph -->|"dispatches"| node_generation
node_graph -->|"dispatches"| node_sanitize
node_graph -->|"conditionally dispatches"| node_history
node_retrieval -->|"calls"| node_search_tool
node_search_tool -->|"searches"| node_vector_index
node_generation -.->|"calls"| node_llm
node_llm -.->|"requests completions"| node_groq
node_graph -->|"uses state contract"| node_state
node_graph -->|"configures workflow"| node_config
node_index_builder -->|"chunks"| node_chunker
node_index_builder -->|"embeds"| node_embedder
node_index_builder -.->|"builds index"| node_vector_index
node_resume -.->|"provides source"| node_index_builder
node_eval_runner -->|"runs questions through"| node_graph
node_eval_runner -->|"scores turns"| node_metrics
node_eval_runner -.->|"gates report"| node_gate
node_compare -.->|"compares experiment results"| node_eval_runner
node_noise -->|"measures variance"| node_metrics
node_calibration -.->|"validates judge threshold"| node_gate
node_apply -->|"updates configuration"| node_config
node_dashboard -->|"renders"| node_panels
node_dashboard -->|"uses"| node_dashboard_state
node_panels -->|"starts evaluations"| node_eval_runner
node_panels -->|"shows gate results"| node_gate
node_panels -->|"shows comparisons"| node_compare
node_panels -->|"measures repeat noise"| node_noise
node_panels -->|"calibrates judge"| node_calibration
node_panels -->|"collects ratings"| node_ratings
node_panels -->|"applies decisions"| node_apply
node_chat_ui -->|"records field ratings"| node_ratings

click node_chat_ui "https://github.com/nikhileshnarkhede/portfolio-chatbot/blob/master/ui/components/chat.py"
click node_graph "https://github.com/nikhileshnarkhede/portfolio-chatbot/blob/master/src/portfolio_chatbot/graph.py"
click node_query "https://github.com/nikhileshnarkhede/portfolio-chatbot/blob/master/src/portfolio_chatbot/nodes/expand_query.py"
click node_routing "https://github.com/nikhileshnarkhede/portfolio-chatbot/blob/master/src/portfolio_chatbot/nodes/route.py"
click node_retrieval "https://github.com/nikhileshnarkhede/portfolio-chatbot/blob/master/src/portfolio_chatbot/nodes/retrieve.py"
click node_search_tool "https://github.com/nikhileshnarkhede/portfolio-chatbot/blob/master/src/portfolio_chatbot/tools/retriever_tool.py"
click node_generation "https://github.com/nikhileshnarkhede/portfolio-chatbot/blob/master/src/portfolio_chatbot/nodes/generate.py"
click node_llm "https://github.com/nikhileshnarkhede/portfolio-chatbot/blob/master/src/portfolio_chatbot/llm/provider.py"
click node_sanitize "https://github.com/nikhileshnarkhede/portfolio-chatbot/blob/master/src/portfolio_chatbot/nodes/sanitize.py"
click node_history "https://github.com/nikhileshnarkhede/portfolio-chatbot/blob/master/src/portfolio_chatbot/nodes/summarize.py"
click node_state "https://github.com/nikhileshnarkhede/portfolio-chatbot/blob/master/src/portfolio_chatbot/state.py"
click node_config "https://github.com/nikhileshnarkhede/portfolio-chatbot/blob/master/src/portfolio_chatbot/config.py"
click node_resume "https://github.com/nikhileshnarkhede/portfolio-chatbot/blob/master/src/portfolio_chatbot/ingestion/parser.py"
click node_index_builder "https://github.com/nikhileshnarkhede/portfolio-chatbot/blob/master/src/portfolio_chatbot/ingestion/build_index.py"
click node_chunker "https://github.com/nikhileshnarkhede/portfolio-chatbot/blob/master/src/portfolio_chatbot/ingestion/chunker.py"
click node_embedder "https://github.com/nikhileshnarkhede/portfolio-chatbot/blob/master/src/portfolio_chatbot/ingestion/embedder.py"
click node_vector_index "https://github.com/nikhileshnarkhede/portfolio-chatbot/blob/master/src/portfolio_chatbot/tools/retriever_tool.py"
click node_eval_runner "https://github.com/nikhileshnarkhede/portfolio-chatbot/blob/master/eval/runner.py"
click node_metrics "https://github.com/nikhileshnarkhede/portfolio-chatbot/blob/master/eval/metrics/retrieval.py"
click node_gate "https://github.com/nikhileshnarkhede/portfolio-chatbot/blob/master/eval/gate.py"
click node_compare "https://github.com/nikhileshnarkhede/portfolio-chatbot/blob/master/eval/compare.py"
click node_noise "https://github.com/nikhileshnarkhede/portfolio-chatbot/blob/master/eval/noise.py"
click node_calibration "https://github.com/nikhileshnarkhede/portfolio-chatbot/blob/master/eval/calibration.py"
click node_ratings "https://github.com/nikhileshnarkhede/portfolio-chatbot/blob/master/eval/ratings.py"
click node_apply "https://github.com/nikhileshnarkhede/portfolio-chatbot/blob/master/eval/apply.py"
click node_dashboard "https://github.com/nikhileshnarkhede/portfolio-chatbot/blob/master/ui/dashboard.py"
click node_panels "https://github.com/nikhileshnarkhede/portfolio-chatbot/blob/master/ui/dash/panels.py"
click node_dashboard_state "https://github.com/nikhileshnarkhede/portfolio-chatbot/blob/master/ui/dash/state.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_chat_ui,node_graph,node_query,node_routing,node_retrieval,node_search_tool,node_generation,node_llm,node_sanitize,node_history,node_state,node_config toneBlue
class node_resume,node_index_builder,node_chunker,node_embedder,node_vector_index toneAmber
class node_eval_runner,node_metrics,node_gate,node_compare,node_noise,node_calibration,node_ratings,node_apply toneMint
class node_dashboard,node_panels,node_dashboard_state toneRose
class node_user,node_groq toneIndigo
```

## Components

### Chat pipeline

- [Chat UI](https://github.com/nikhileshnarkhede/portfolio-chatbot/blob/master/ui/components/chat.py): `ui/components/chat.py`
- [Graph workflow](https://github.com/nikhileshnarkhede/portfolio-chatbot/blob/master/src/portfolio_chatbot/graph.py): `src/portfolio_chatbot/graph.py`
- [Query expansion](https://github.com/nikhileshnarkhede/portfolio-chatbot/blob/master/src/portfolio_chatbot/nodes/expand_query.py): `src/portfolio_chatbot/nodes/expand_query.py`
- [Question routing](https://github.com/nikhileshnarkhede/portfolio-chatbot/blob/master/src/portfolio_chatbot/nodes/route.py): `src/portfolio_chatbot/nodes/route.py`
- [Context retrieval](https://github.com/nikhileshnarkhede/portfolio-chatbot/blob/master/src/portfolio_chatbot/nodes/retrieve.py): `src/portfolio_chatbot/nodes/retrieve.py`
- [Vector search](https://github.com/nikhileshnarkhede/portfolio-chatbot/blob/master/src/portfolio_chatbot/tools/retriever_tool.py): `src/portfolio_chatbot/tools/retriever_tool.py`
- [Answer generation](https://github.com/nikhileshnarkhede/portfolio-chatbot/blob/master/src/portfolio_chatbot/nodes/generate.py): `src/portfolio_chatbot/nodes/generate.py`
- [Model provider](https://github.com/nikhileshnarkhede/portfolio-chatbot/blob/master/src/portfolio_chatbot/llm/provider.py): `src/portfolio_chatbot/llm/provider.py`
- [Link sanitization](https://github.com/nikhileshnarkhede/portfolio-chatbot/blob/master/src/portfolio_chatbot/nodes/sanitize.py): `src/portfolio_chatbot/nodes/sanitize.py`
- [History summary](https://github.com/nikhileshnarkhede/portfolio-chatbot/blob/master/src/portfolio_chatbot/nodes/summarize.py): `src/portfolio_chatbot/nodes/summarize.py`
- [Turn state](https://github.com/nikhileshnarkhede/portfolio-chatbot/blob/master/src/portfolio_chatbot/state.py): `src/portfolio_chatbot/state.py`
- [Experiment config](https://github.com/nikhileshnarkhede/portfolio-chatbot/blob/master/src/portfolio_chatbot/config.py): `src/portfolio_chatbot/config.py`

### Resume indexing

- [Resume source](https://github.com/nikhileshnarkhede/portfolio-chatbot/blob/master/src/portfolio_chatbot/ingestion/parser.py): `src/portfolio_chatbot/ingestion/parser.py`
- [Index builder](https://github.com/nikhileshnarkhede/portfolio-chatbot/blob/master/src/portfolio_chatbot/ingestion/build_index.py): `src/portfolio_chatbot/ingestion/build_index.py`
- [Resume chunking](https://github.com/nikhileshnarkhede/portfolio-chatbot/blob/master/src/portfolio_chatbot/ingestion/chunker.py): `src/portfolio_chatbot/ingestion/chunker.py`
- [Text embeddings](https://github.com/nikhileshnarkhede/portfolio-chatbot/blob/master/src/portfolio_chatbot/ingestion/embedder.py): `src/portfolio_chatbot/ingestion/embedder.py`
- [FAISS index](https://github.com/nikhileshnarkhede/portfolio-chatbot/blob/master/src/portfolio_chatbot/tools/retriever_tool.py): `src/portfolio_chatbot/tools/retriever_tool.py`

### Evaluation

- [Evaluation runner](https://github.com/nikhileshnarkhede/portfolio-chatbot/blob/master/eval/runner.py): `eval/runner.py`
- [Evaluation metrics](https://github.com/nikhileshnarkhede/portfolio-chatbot/blob/master/eval/metrics/retrieval.py): `eval/metrics/retrieval.py`
- [Threshold gate](https://github.com/nikhileshnarkhede/portfolio-chatbot/blob/master/eval/gate.py): `eval/gate.py`
- [Experiment comparison](https://github.com/nikhileshnarkhede/portfolio-chatbot/blob/master/eval/compare.py): `eval/compare.py`
- [Noise measurement](https://github.com/nikhileshnarkhede/portfolio-chatbot/blob/master/eval/noise.py): `eval/noise.py`
- [Judge calibration](https://github.com/nikhileshnarkhede/portfolio-chatbot/blob/master/eval/calibration.py): `eval/calibration.py`
- [Human ratings](https://github.com/nikhileshnarkhede/portfolio-chatbot/blob/master/eval/ratings.py): `eval/ratings.py`
- [Config application](https://github.com/nikhileshnarkhede/portfolio-chatbot/blob/master/eval/apply.py): `eval/apply.py`

### Evaluation console

- [Dashboard entry](https://github.com/nikhileshnarkhede/portfolio-chatbot/blob/master/ui/dashboard.py): `ui/dashboard.py`
- [Dashboard panels](https://github.com/nikhileshnarkhede/portfolio-chatbot/blob/master/ui/dash/panels.py): `ui/dash/panels.py`
- [Dashboard state](https://github.com/nikhileshnarkhede/portfolio-chatbot/blob/master/ui/dash/state.py): `ui/dash/state.py`

### Other components

- **Recruiter**
- **Groq service**

## Connections

- Recruiter → Chat UI: asks (evidence: `README.md`)
- Chat UI → Graph workflow: invokes (evidence: `ui/components/chat.py`)
- Graph workflow → Query expansion: dispatches (evidence: `src/portfolio_chatbot/graph.py`)
- Graph workflow → Question routing: dispatches (evidence: `src/portfolio_chatbot/graph.py`)
- Graph workflow → Context retrieval: dispatches (evidence: `src/portfolio_chatbot/graph.py`)
- Graph workflow → Answer generation: dispatches (evidence: `src/portfolio_chatbot/graph.py`)
- Graph workflow → Link sanitization: dispatches (evidence: `src/portfolio_chatbot/graph.py`)
- Graph workflow → History summary: conditionally dispatches (evidence: `src/portfolio_chatbot/graph.py`)
- Context retrieval → Vector search: calls (evidence: `src/portfolio_chatbot/nodes/retrieve.py`)
- Vector search → FAISS index: searches (evidence: `src/portfolio_chatbot/tools/retriever_tool.py`)
- Answer generation → Model provider: calls
- Model provider → Groq service: requests completions
- Graph workflow → Turn state: uses state contract (evidence: `src/portfolio_chatbot/graph.py`)
- Graph workflow → Experiment config: configures workflow (evidence: `src/portfolio_chatbot/graph.py`)
- Index builder → Resume chunking: chunks (evidence: `src/portfolio_chatbot/ingestion/build_index.py`)
- Index builder → Text embeddings: embeds (evidence: `src/portfolio_chatbot/ingestion/build_index.py`)
- Index builder → FAISS index: builds index
- Resume source → Index builder: provides source
- Evaluation runner → Graph workflow: runs questions through (evidence: `eval/runner.py`)
- Evaluation runner → Evaluation metrics: scores turns (evidence: `eval/runner.py`)
- Evaluation runner → Threshold gate: gates report
- Experiment comparison → Evaluation runner: compares experiment results
- Noise measurement → Evaluation metrics: measures variance (evidence: `eval/noise.py`)
- Judge calibration → Threshold gate: validates judge threshold
- Config application → Experiment config: updates configuration (evidence: `eval/apply.py`)
- Dashboard entry → Dashboard panels: renders (evidence: `ui/dashboard.py`)
- Dashboard entry → Dashboard state: uses (evidence: `ui/dashboard.py`)
- Dashboard panels → Evaluation runner: starts evaluations (evidence: `ui/dash/panels.py`)
- Dashboard panels → Threshold gate: shows gate results (evidence: `ui/dash/panels.py`)
- Dashboard panels → Experiment comparison: shows comparisons (evidence: `ui/dash/panels.py`)
- Dashboard panels → Noise measurement: measures repeat noise (evidence: `ui/dash/panels.py`)
- Dashboard panels → Judge calibration: calibrates judge (evidence: `ui/dash/panels.py`)
- Dashboard panels → Human ratings: collects ratings (evidence: `ui/dash/panels.py`)
- Dashboard panels → Config application: applies decisions (evidence: `ui/dash/panels.py`)
- Chat UI → Human ratings: records field ratings (evidence: `ui/components/chat.py`)
