# hippomasakib1/aegnyxzero architecture

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

- Interactive diagram: https://gitdiagram.com/hippomasakib1/aegnyxzero
- Repository: https://github.com/hippomasakib1/aegnyxzero

## Overview

AegnyxZero turns curated NASA combustion experiments into a decision dashboard: planners set conditions, inspect ranked material risks and experimental coverage, and can ask evidence-grounded questions. The backend serves the dashboard’s ranking and coverage requests and routes questions through retrieval, synthesis, and deterministic validation before returning an answer. Evidence details and comparisons are separate UI views. The README documents ingestion and offline snapshot capabilities, but those data-pipeline relationships are shown only at the documented level; some frontend-to-API and provider wiring is likewise not fully excerpted.

Main entry points: [`frontend/src/App.tsx`](https://github.com/hippomasakib1/aegnyxzero/blob/main/frontend/src/App.tsx) (Dashboard app), [`backend/app/main.py`](https://github.com/hippomasakib1/aegnyxzero/blob/main/backend/app/main.py) (FastAPI routes), [`backend/app/pipeline_v2.py`](https://github.com/hippomasakib1/aegnyxzero/blob/main/backend/app/pipeline_v2.py) (QA pipeline), [`backend/app/models.py`](https://github.com/hippomasakib1/aegnyxzero/blob/main/backend/app/models.py) (Experiment database)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["Decision dashboard"]
  node_app["Dashboard app<br/>[App.tsx]"]
  node_conditions["Scenario controls<br/>[ConditionsBar.tsx]"]
  node_ranked["Risk ranking<br/>[RankedTable.tsx]"]
  node_coverage_view["Coverage map<br/>[CoverageMap.tsx]"]
  node_evidence_view["Evidence drawer<br/>[EvidenceDrawer.tsx]"]
  node_charts["Comparison charts"]
  node_ask_view["Ask AI drawer<br/>[AskAIDrawer.tsx]"]
  node_modals["Review and info<br/>[Modals.tsx]"]
  node_snapshot["Offline snapshot<br/>[snapshot.json]"]
end

subgraph group_api["API and analysis"]
  node_api_service["FastAPI routes<br/>[main.py]"]
  node_risk_engine["Risk scoring<br/>[scoring.py]"]
  node_coverage_engine["Coverage computation<br/>[coverage.py]"]
end

subgraph group_qa["Grounded answers"]
  node_ask_legacy["Ask handler<br/>[ask_ai.py]"]
  node_pipeline["QA pipeline<br/>[pipeline_v2.py]"]
  node_retrieval["Evidence retrieval<br/>[retrieval.py]"]
  node_validators["Answer validators<br/>[validators.py]"]
  node_llm_gateway["LLM gateway<br/>[llm_gateway.py]"]
  node_llm_cache[("Completion cache<br/>[llm_gateway.py]")]
end

subgraph group_evidence["Experiment evidence"]
  node_experiment_store[("Experiment database<br/>[models.py]")]
  node_db_sessions["Database sessions<br/>[database.py]"]
  node_vector_store[("Vector index<br/>[retrieval.py]")]
  node_data_pipeline["Data preparation"]
end

node_planner(("Mission planner"))
node_llm_providers{{"LLM providers"}}

node_planner -->|"uses"| node_app
node_app -->|"renders"| node_conditions
node_app -->|"renders"| node_ranked
node_app -->|"renders"| node_coverage_view
node_app -->|"renders"| node_evidence_view
node_app -->|"renders"| node_charts
node_app -->|"renders"| node_ask_view
node_app -->|"renders"| node_modals
node_app -->|"loads"| node_snapshot
node_app -->|"requests ranking and coverage"| node_api_service
node_app -.->|"requests answers"| node_api_service
node_api_service -->|"queries experiments"| node_experiment_store
node_api_service -->|"computes ranking"| node_risk_engine
node_api_service -->|"computes coverage"| node_coverage_engine
node_api_service -->|"routes questions"| node_ask_legacy
node_api_service -->|"routes questions"| node_pipeline
node_api_service -->|"opens sessions"| node_db_sessions
node_experiment_store -->|"uses base"| node_db_sessions
node_ask_legacy -->|"validates answers"| node_validators
node_pipeline -->|"retrieves evidence"| node_retrieval
node_pipeline -->|"synthesizes answers"| node_llm_gateway
node_pipeline -->|"validates drafts"| node_validators
node_retrieval -->|"loads cited rows"| node_experiment_store
node_retrieval -.->|"searches chunks"| node_vector_store
node_llm_gateway -->|"reads and writes"| node_llm_cache
node_llm_gateway -->|"calls with fallback"| node_llm_providers
node_data_pipeline -->|"loads curated rows"| node_experiment_store
node_data_pipeline -->|"builds index"| node_vector_store
node_data_pipeline -->|"exports snapshot"| node_snapshot

click node_app "https://github.com/hippomasakib1/aegnyxzero/blob/main/frontend/src/App.tsx"
click node_conditions "https://github.com/hippomasakib1/aegnyxzero/blob/main/frontend/src/components/ConditionsBar.tsx"
click node_ranked "https://github.com/hippomasakib1/aegnyxzero/blob/main/frontend/src/components/RankedTable.tsx"
click node_coverage_view "https://github.com/hippomasakib1/aegnyxzero/blob/main/frontend/src/components/CoverageMap.tsx"
click node_evidence_view "https://github.com/hippomasakib1/aegnyxzero/blob/main/frontend/src/components/EvidenceDrawer.tsx"
click node_charts "https://github.com/hippomasakib1/aegnyxzero/blob/main/frontend/src/components/ComparisonCharts.tsx"
click node_ask_view "https://github.com/hippomasakib1/aegnyxzero/blob/main/frontend/src/components/AskAIDrawer.tsx"
click node_modals "https://github.com/hippomasakib1/aegnyxzero/blob/main/frontend/src/components/Modals.tsx"
click node_api_service "https://github.com/hippomasakib1/aegnyxzero/blob/main/backend/app/main.py"
click node_risk_engine "https://github.com/hippomasakib1/aegnyxzero/blob/main/backend/app/scoring.py"
click node_coverage_engine "https://github.com/hippomasakib1/aegnyxzero/blob/main/backend/app/coverage.py"
click node_experiment_store "https://github.com/hippomasakib1/aegnyxzero/blob/main/backend/app/models.py"
click node_db_sessions "https://github.com/hippomasakib1/aegnyxzero/blob/main/backend/app/database.py"
click node_ask_legacy "https://github.com/hippomasakib1/aegnyxzero/blob/main/backend/app/ask_ai.py"
click node_pipeline "https://github.com/hippomasakib1/aegnyxzero/blob/main/backend/app/pipeline_v2.py"
click node_retrieval "https://github.com/hippomasakib1/aegnyxzero/blob/main/backend/app/retrieval.py"
click node_validators "https://github.com/hippomasakib1/aegnyxzero/blob/main/backend/app/validators.py"
click node_llm_gateway "https://github.com/hippomasakib1/aegnyxzero/blob/main/backend/app/llm_gateway.py"
click node_llm_cache "https://github.com/hippomasakib1/aegnyxzero/blob/main/backend/app/llm_gateway.py"
click node_vector_store "https://github.com/hippomasakib1/aegnyxzero/blob/main/backend/app/retrieval.py"
click node_data_pipeline "https://github.com/hippomasakib1/aegnyxzero/tree/main/data_pipeline"
click node_snapshot "https://github.com/hippomasakib1/aegnyxzero/blob/main/frontend/src/data/snapshot.json"

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_conditions,node_ranked,node_coverage_view,node_evidence_view,node_charts,node_ask_view,node_modals,node_snapshot toneBlue
class node_api_service,node_risk_engine,node_coverage_engine toneAmber
class node_ask_legacy,node_pipeline,node_retrieval,node_validators,node_llm_gateway,node_llm_cache toneMint
class node_experiment_store,node_db_sessions,node_vector_store,node_data_pipeline toneRose
class node_planner,node_llm_providers toneIndigo
```

## Components

### Decision dashboard

- [Dashboard app](https://github.com/hippomasakib1/aegnyxzero/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Scenario controls](https://github.com/hippomasakib1/aegnyxzero/blob/main/frontend/src/components/ConditionsBar.tsx): `frontend/src/components/ConditionsBar.tsx`
- [Risk ranking](https://github.com/hippomasakib1/aegnyxzero/blob/main/frontend/src/components/RankedTable.tsx): `frontend/src/components/RankedTable.tsx`
- [Coverage map](https://github.com/hippomasakib1/aegnyxzero/blob/main/frontend/src/components/CoverageMap.tsx): `frontend/src/components/CoverageMap.tsx`
- [Evidence drawer](https://github.com/hippomasakib1/aegnyxzero/blob/main/frontend/src/components/EvidenceDrawer.tsx): `frontend/src/components/EvidenceDrawer.tsx`
- [Comparison charts](https://github.com/hippomasakib1/aegnyxzero/blob/main/frontend/src/components/ComparisonCharts.tsx): `frontend/src/components/ComparisonCharts.tsx`
- [Ask AI drawer](https://github.com/hippomasakib1/aegnyxzero/blob/main/frontend/src/components/AskAIDrawer.tsx): `frontend/src/components/AskAIDrawer.tsx`
- [Review and info](https://github.com/hippomasakib1/aegnyxzero/blob/main/frontend/src/components/Modals.tsx): `frontend/src/components/Modals.tsx`
- [Offline snapshot](https://github.com/hippomasakib1/aegnyxzero/blob/main/frontend/src/data/snapshot.json): `frontend/src/data/snapshot.json`

### API and analysis

- [FastAPI routes](https://github.com/hippomasakib1/aegnyxzero/blob/main/backend/app/main.py): `backend/app/main.py`
- [Risk scoring](https://github.com/hippomasakib1/aegnyxzero/blob/main/backend/app/scoring.py): `backend/app/scoring.py`
- [Coverage computation](https://github.com/hippomasakib1/aegnyxzero/blob/main/backend/app/coverage.py): `backend/app/coverage.py`

### Grounded answers

- [Ask handler](https://github.com/hippomasakib1/aegnyxzero/blob/main/backend/app/ask_ai.py): `backend/app/ask_ai.py`
- [QA pipeline](https://github.com/hippomasakib1/aegnyxzero/blob/main/backend/app/pipeline_v2.py): `backend/app/pipeline_v2.py`
- [Evidence retrieval](https://github.com/hippomasakib1/aegnyxzero/blob/main/backend/app/retrieval.py): `backend/app/retrieval.py`
- [Answer validators](https://github.com/hippomasakib1/aegnyxzero/blob/main/backend/app/validators.py): `backend/app/validators.py`
- [LLM gateway](https://github.com/hippomasakib1/aegnyxzero/blob/main/backend/app/llm_gateway.py): `backend/app/llm_gateway.py`
- [Completion cache](https://github.com/hippomasakib1/aegnyxzero/blob/main/backend/app/llm_gateway.py): `backend/app/llm_gateway.py`

### Experiment evidence

- [Experiment database](https://github.com/hippomasakib1/aegnyxzero/blob/main/backend/app/models.py): `backend/app/models.py`
- [Database sessions](https://github.com/hippomasakib1/aegnyxzero/blob/main/backend/app/database.py): `backend/app/database.py`
- [Vector index](https://github.com/hippomasakib1/aegnyxzero/blob/main/backend/app/retrieval.py): `backend/app/retrieval.py`
- [Data preparation](https://github.com/hippomasakib1/aegnyxzero/tree/main/data_pipeline): `data_pipeline`

### Other components

- **Mission planner**
- **LLM providers**

## Connections

- Mission planner → Dashboard app: uses (evidence: `README.md`)
- Dashboard app → Scenario controls: renders (evidence: `frontend/src/App.tsx`)
- Dashboard app → Risk ranking: renders (evidence: `frontend/src/App.tsx`)
- Dashboard app → Coverage map: renders (evidence: `frontend/src/App.tsx`)
- Dashboard app → Evidence drawer: renders (evidence: `frontend/src/App.tsx`)
- Dashboard app → Comparison charts: renders (evidence: `frontend/src/App.tsx`)
- Dashboard app → Ask AI drawer: renders (evidence: `frontend/src/App.tsx`)
- Dashboard app → Review and info: renders (evidence: `frontend/src/App.tsx`)
- Dashboard app → Offline snapshot: loads (evidence: `frontend/src/App.tsx`)
- Dashboard app → FastAPI routes: requests ranking and coverage (evidence: `frontend/src/App.tsx`)
- Dashboard app → FastAPI routes: requests answers
- FastAPI routes → Experiment database: queries experiments (evidence: `backend/app/main.py`)
- FastAPI routes → Risk scoring: computes ranking (evidence: `backend/app/main.py`)
- FastAPI routes → Coverage computation: computes coverage (evidence: `backend/app/main.py`)
- FastAPI routes → Ask handler: routes questions (evidence: `backend/app/main.py`)
- FastAPI routes → QA pipeline: routes questions (evidence: `backend/app/main.py`)
- FastAPI routes → Database sessions: opens sessions (evidence: `backend/app/main.py`)
- Experiment database → Database sessions: uses base (evidence: `backend/app/models.py`)
- Ask handler → Answer validators: validates answers (evidence: `backend/app/ask_ai.py`)
- QA pipeline → Evidence retrieval: retrieves evidence (evidence: `backend/app/pipeline_v2.py`)
- QA pipeline → LLM gateway: synthesizes answers (evidence: `backend/app/pipeline_v2.py`)
- QA pipeline → Answer validators: validates drafts (evidence: `backend/app/pipeline_v2.py`)
- Evidence retrieval → Experiment database: loads cited rows (evidence: `backend/app/retrieval.py`)
- Evidence retrieval → Vector index: searches chunks (evidence: `backend/app/retrieval.py`)
- LLM gateway → Completion cache: reads and writes (evidence: `backend/app/llm_gateway.py`)
- LLM gateway → LLM providers: calls with fallback (evidence: `backend/app/llm_gateway.py`)
- Data preparation → Experiment database: loads curated rows (evidence: `README.md`)
- Data preparation → Vector index: builds index (evidence: `README.md`)
- Data preparation → Offline snapshot: exports snapshot (evidence: `README.md`)
