# prahalad-ship-it/knowable- architecture

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

- Interactive diagram: https://gitdiagram.com/prahalad-ship-it/knowable-
- Repository: https://github.com/prahalad-ship-it/knowable-
- Video tour (about a minute): https://gitdiagram.com/prahalad-ship-it/knowable-/video

## Overview

Episteme AI is a confidence-aware question-answering product: users submit a question, the backend obtains a model response, and the interface presents calibrated text, confidence indicators, gaps, and resolution suggestions. The README also describes asynchronous edge-case auditing and uncertainty logging into a fine-tuning flywheel; the sampled API and triage code support background capture and flywheel handoff, but do not establish a separate audit-worker implementation. Research and calibration scripts form a supporting empirical-evaluation branch. Some frontend stream phases are timed UI states, not evidence of token streaming.

Main entry points: [`frontend/src/App.jsx`](https://github.com/prahalad-ship-it/knowable-/blob/main/frontend/src/App.jsx) (Application state), [`api/index.py`](https://github.com/prahalad-ship-it/knowable-/blob/main/api/index.py) (Flask API and orchestration), [`episteme_empirical_results.csv`](https://github.com/prahalad-ship-it/knowable-/blob/main/episteme_empirical_results.csv) (Empirical results), [`episteme_research.py`](https://github.com/prahalad-ship-it/knowable-/blob/main/episteme_research.py) (Inference benchmark)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User experience"]
  node_app["Application state<br/>[App.jsx]"]
  node_query["Question input<br/>[QueryInput.jsx]"]
  node_stream["Audit phase display<br/>[LiveStream.jsx]"]
  node_response["Calibrated results UI<br/>[ResponseCard.jsx]"]
  node_examples["Scenario examples<br/>[mockData.js]"]
  node_frontend_api["HTTP client<br/>[api.js]"]
end

subgraph group_inference["Inference and confidence"]
  node_backend["Flask API and orchestration<br/>[index.py]"]
  node_nim["NVIDIA-compatible model"]
  node_triage["Confidence and triage processor"]
end

subgraph group_flywheel["Uncertainty flywheel"]
  node_flywheel_store[("Flywheel JSONL data")]
end

subgraph group_research["Empirical evaluation"]
  node_research["Inference benchmark"]
  node_truthfulqa["Benchmark questions<br/>[TruthfulQA.csv]"]
  node_results["Empirical results"]
  node_analysis["Uncertainty analysis"]
  node_dashboard_metrics["Dashboard metrics"]
  node_error_analysis["Error analysis<br/>[error_analysis.py]"]
end

node_user(("Question asker"))
node_flywheel_webhook["Flywheel webhook"]

node_user -->|"enters question"| node_query
node_query -->|"submits text"| node_app
node_app -->|"requests answer"| node_frontend_api
node_app -->|"renders"| node_query
node_app -->|"renders phases"| node_stream
node_app -->|"renders result"| node_response
node_app -->|"loads examples"| node_examples
node_frontend_api -->|"POSTs question"| node_backend
node_backend -->|"returns payload"| node_frontend_api
node_backend -->|"requests completion"| node_nim
node_backend -->|"uses processor"| node_triage
node_backend -.->|"captures locally"| node_flywheel_store
node_backend -.->|"hands off asynchronously"| node_flywheel_webhook
node_research -->|"reads benchmark"| node_truthfulqa
node_research -->|"requests completions"| node_nim
node_research -->|"records evaluations"| node_results
node_analysis -.->|"analyzes results"| node_results
node_dashboard_metrics -.->|"summarizes metrics"| node_results
node_error_analysis -.->|"examines errors"| node_results

click node_app "https://github.com/prahalad-ship-it/knowable-/blob/main/frontend/src/App.jsx"
click node_query "https://github.com/prahalad-ship-it/knowable-/blob/main/frontend/src/components/QueryInput.jsx"
click node_stream "https://github.com/prahalad-ship-it/knowable-/blob/main/frontend/src/components/LiveStream.jsx"
click node_response "https://github.com/prahalad-ship-it/knowable-/blob/main/frontend/src/components/ResponseCard.jsx"
click node_examples "https://github.com/prahalad-ship-it/knowable-/blob/main/frontend/src/mockData.js"
click node_frontend_api "https://github.com/prahalad-ship-it/knowable-/blob/main/frontend/src/api.js"
click node_backend "https://github.com/prahalad-ship-it/knowable-/blob/main/api/index.py"
click node_triage "https://github.com/prahalad-ship-it/knowable-/blob/main/triage_protocol_processor.py"
click node_flywheel_store "https://github.com/prahalad-ship-it/knowable-/tree/main/data"
click node_research "https://github.com/prahalad-ship-it/knowable-/blob/main/episteme_research.py"
click node_truthfulqa "https://github.com/prahalad-ship-it/knowable-/blob/main/TruthfulQA.csv"
click node_results "https://github.com/prahalad-ship-it/knowable-/blob/main/episteme_empirical_results.csv"
click node_analysis "https://github.com/prahalad-ship-it/knowable-/blob/main/analyze_uncertainty_patterns.py"
click node_dashboard_metrics "https://github.com/prahalad-ship-it/knowable-/blob/main/episteme_dashboard_metrics.py"
click node_error_analysis "https://github.com/prahalad-ship-it/knowable-/blob/main/error_analysis.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_query,node_stream,node_response,node_examples,node_frontend_api toneBlue
class node_backend,node_nim,node_triage toneAmber
class node_flywheel_store,node_flywheel_webhook toneMint
class node_research,node_truthfulqa,node_results,node_analysis,node_dashboard_metrics,node_error_analysis toneRose
class node_user toneIndigo
```

## Components

### User experience

- [Application state](https://github.com/prahalad-ship-it/knowable-/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Question input](https://github.com/prahalad-ship-it/knowable-/blob/main/frontend/src/components/QueryInput.jsx): `frontend/src/components/QueryInput.jsx`
- [Audit phase display](https://github.com/prahalad-ship-it/knowable-/blob/main/frontend/src/components/LiveStream.jsx): `frontend/src/components/LiveStream.jsx`
- [Calibrated results UI](https://github.com/prahalad-ship-it/knowable-/blob/main/frontend/src/components/ResponseCard.jsx): `frontend/src/components/ResponseCard.jsx`
- [Scenario examples](https://github.com/prahalad-ship-it/knowable-/blob/main/frontend/src/mockData.js): `frontend/src/mockData.js`
- [HTTP client](https://github.com/prahalad-ship-it/knowable-/blob/main/frontend/src/api.js): `frontend/src/api.js`

### Inference and confidence

- [Flask API and orchestration](https://github.com/prahalad-ship-it/knowable-/blob/main/api/index.py): `api/index.py`
- **NVIDIA-compatible model**
- [Confidence and triage processor](https://github.com/prahalad-ship-it/knowable-/blob/main/triage_protocol_processor.py): `triage_protocol_processor.py`

### Uncertainty flywheel

- [Flywheel JSONL data](https://github.com/prahalad-ship-it/knowable-/tree/main/data): `data`

### Empirical evaluation

- [Inference benchmark](https://github.com/prahalad-ship-it/knowable-/blob/main/episteme_research.py): `episteme_research.py`
- [Benchmark questions](https://github.com/prahalad-ship-it/knowable-/blob/main/TruthfulQA.csv): `TruthfulQA.csv`
- [Empirical results](https://github.com/prahalad-ship-it/knowable-/blob/main/episteme_empirical_results.csv): `episteme_empirical_results.csv`
- [Uncertainty analysis](https://github.com/prahalad-ship-it/knowable-/blob/main/analyze_uncertainty_patterns.py): `analyze_uncertainty_patterns.py`
- [Dashboard metrics](https://github.com/prahalad-ship-it/knowable-/blob/main/episteme_dashboard_metrics.py): `episteme_dashboard_metrics.py`
- [Error analysis](https://github.com/prahalad-ship-it/knowable-/blob/main/error_analysis.py): `error_analysis.py`

### Other components

- **Question asker**
- **Flywheel webhook**

## Connections

- Question asker → Question input: enters question (evidence: `frontend/src/components/QueryInput.jsx`)
- Question input → Application state: submits text (evidence: `frontend/src/components/QueryInput.jsx`)
- Application state → HTTP client: requests answer (evidence: `frontend/src/App.jsx`)
- Application state → Question input: renders (evidence: `frontend/src/App.jsx`)
- Application state → Audit phase display: renders phases (evidence: `frontend/src/App.jsx`)
- Application state → Calibrated results UI: renders result (evidence: `frontend/src/App.jsx`)
- Application state → Scenario examples: loads examples (evidence: `frontend/src/App.jsx`)
- HTTP client → Flask API and orchestration: POSTs question (evidence: `frontend/src/api.js`)
- Flask API and orchestration → HTTP client: returns payload (evidence: `README.md`)
- Flask API and orchestration → NVIDIA-compatible model: requests completion (evidence: `api/index.py`)
- Flask API and orchestration → Confidence and triage processor: uses processor (evidence: `api/index.py`)
- Flask API and orchestration → Flywheel JSONL data: captures locally
- Flask API and orchestration → Flywheel webhook: hands off asynchronously
- Inference benchmark → Benchmark questions: reads benchmark (evidence: `episteme_research.py`)
- Inference benchmark → NVIDIA-compatible model: requests completions (evidence: `episteme_research.py`)
- Inference benchmark → Empirical results: records evaluations (evidence: `episteme_research.py`)
- Uncertainty analysis → Empirical results: analyzes results
- Dashboard metrics → Empirical results: summarizes metrics
- Error analysis → Empirical results: examines errors
