# vatshal-venkat/aether architecture

> Architecture diagram of the GitHub repository vatshal-venkat/aether, 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/vatshal-venkat/aether
- Repository: https://github.com/vatshal-venkat/aether

## Overview

Aether is a clinical and billing data assistant: users ask questions in a web chat, receive streamed progress and an answer, and can inspect SQL, tables, and drug-label sources. The backend’s graph runner is the principal workflow entry point; its domain stages include routing, query planning and execution, retrieval, synthesis, and number verification. Supporting branches cover patient-scoped data access, saved queries, and operational endpoints. Several backend route and graph files were not sampled, so uncertain runtime links are left dashed rather than inferred.

Main entry points: [`backend/app/graph/deps.py`](https://github.com/vatshal-venkat/aether/blob/main/backend/app/graph/deps.py) (Runtime dependencies), [`backend/app/graph/runner.py`](https://github.com/vatshal-venkat/aether/blob/main/backend/app/graph/runner.py) (Question runner), [`backend/app/main.py`](https://github.com/vatshal-venkat/aether/blob/main/backend/app/main.py) (API application), [`backend/app/llm/client.py`](https://github.com/vatshal-venkat/aether/blob/main/backend/app/llm/client.py) (Model client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web application"]
  node_app["Chat interface<br/>[App.tsx]"]
  node_chat_state["Chat state<br/>[useChat.ts]"]
  node_api_client["Backend client<br/>[client.ts]"]
  node_answer_ui["Answer display<br/>[AnswerCard.tsx]"]
end

subgraph group_api["API service"]
  node_api_app["API application<br/>[main.py]"]
  node_chat_api["Chat endpoints<br/>[chat.py]"]
  node_catalog_api["Patient and schema API<br/>[catalog_routes.py]"]
  node_ops_api["Operations endpoints<br/>[ops_routes.py]"]
end

subgraph group_workflow["Question workflow"]
  node_runner["Question runner<br/>[runner.py]"]
  node_graph_builder["Graph construction<br/>[build.py]"]
  node_graph_nodes["Question stages"]
  node_deps["Runtime dependencies<br/>[deps.py]"]
  node_llm["Model client<br/>[client.py]"]
end

subgraph group_data["Data and retrieval"]
  node_db_engines[("Database connections<br/>[engines.py]")]
  node_catalog["Schema catalog<br/>[catalog.py]"]
  node_patient_data["Patient access<br/>[patients.py]"]
  node_rag[("Drug-label retrieval<br/>[store.py]")]
  node_memory[("Conversation memory<br/>[store.py]")]
  node_saved_queries[("Saved SQL queries<br/>[saved_queries.py]")]
end

subgraph group_support["Safety and operations"]
  node_safety["Query and answer safeguards"]
  node_ops["Audit and service controls<br/>[__init__.py]"]
  node_usage[("Model usage ledger<br/>[usage.py]")]
end

node_user(("Clinician or patient"))
node_database_services[("Clinical and billing databases")]
node_model_provider{{"LLM provider"}}

node_user -->|"asks question"| node_app
node_app -->|"uses chat state"| node_chat_state
node_chat_state -->|"streams request"| node_api_client
node_api_client -.->|"posts chat"| node_chat_api
node_chat_api -.->|"runs question"| node_runner
node_runner -->|"builds graph"| node_graph_builder
node_runner -->|"uses dependencies"| node_deps
node_graph_builder -.->|"dispatches stages"| node_graph_nodes
node_deps -->|"provides engines"| node_db_engines
node_deps -->|"provides catalog"| node_catalog
node_deps -->|"provides retrieval"| node_rag
node_deps -->|"provides memory"| node_memory
node_deps -->|"provides query store"| node_saved_queries
node_deps -->|"provides model"| node_llm
node_db_engines -->|"connects"| node_database_services
node_llm -.->|"invokes"| node_model_provider
node_catalog_api -->|"lists patients"| node_patient_data
node_catalog_api -->|"reads schema"| node_catalog
node_api_app -->|"registers routes"| node_chat_api
node_api_app -->|"registers routes"| node_catalog_api
node_api_app -->|"registers routes"| node_ops_api
node_ops_api -->|"serves operations"| node_ops
node_runner -.->|"saves query"| node_saved_queries
node_runner -.->|"applies safeguards"| node_safety
node_runner -->|"returns answer data"| node_answer_ui
node_answer_ui -->|"shows answer"| node_user
node_llm -->|"records usage"| node_usage

click node_app "https://github.com/vatshal-venkat/aether/blob/main/frontend/src/App.tsx"
click node_chat_state "https://github.com/vatshal-venkat/aether/blob/main/frontend/src/hooks/useChat.ts"
click node_api_client "https://github.com/vatshal-venkat/aether/blob/main/frontend/src/api/client.ts"
click node_answer_ui "https://github.com/vatshal-venkat/aether/blob/main/frontend/src/components/answer/AnswerCard.tsx"
click node_api_app "https://github.com/vatshal-venkat/aether/blob/main/backend/app/main.py"
click node_chat_api "https://github.com/vatshal-venkat/aether/blob/main/backend/app/api/chat.py"
click node_catalog_api "https://github.com/vatshal-venkat/aether/blob/main/backend/app/api/catalog_routes.py"
click node_ops_api "https://github.com/vatshal-venkat/aether/blob/main/backend/app/api/ops_routes.py"
click node_runner "https://github.com/vatshal-venkat/aether/blob/main/backend/app/graph/runner.py"
click node_graph_builder "https://github.com/vatshal-venkat/aether/blob/main/backend/app/graph/build.py"
click node_graph_nodes "https://github.com/vatshal-venkat/aether/tree/main/backend/app/graph/nodes"
click node_deps "https://github.com/vatshal-venkat/aether/blob/main/backend/app/graph/deps.py"
click node_llm "https://github.com/vatshal-venkat/aether/blob/main/backend/app/llm/client.py"
click node_db_engines "https://github.com/vatshal-venkat/aether/blob/main/backend/app/db/engines.py"
click node_catalog "https://github.com/vatshal-venkat/aether/blob/main/backend/app/db/catalog.py"
click node_patient_data "https://github.com/vatshal-venkat/aether/blob/main/backend/app/db/patients.py"
click node_rag "https://github.com/vatshal-venkat/aether/blob/main/backend/app/rag/store.py"
click node_memory "https://github.com/vatshal-venkat/aether/blob/main/backend/app/memory/store.py"
click node_saved_queries "https://github.com/vatshal-venkat/aether/blob/main/backend/app/memory/saved_queries.py"
click node_safety "https://github.com/vatshal-venkat/aether/tree/main/backend/app/safety"
click node_ops "https://github.com/vatshal-venkat/aether/blob/main/backend/app/ops/__init__.py"
click node_usage "https://github.com/vatshal-venkat/aether/blob/main/backend/app/llm/usage.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_chat_state,node_api_client,node_answer_ui toneBlue
class node_api_app,node_chat_api,node_catalog_api,node_ops_api,node_database_services toneAmber
class node_runner,node_graph_builder,node_graph_nodes,node_deps,node_llm toneMint
class node_db_engines,node_catalog,node_patient_data,node_rag,node_memory,node_saved_queries toneRose
class node_safety,node_ops,node_usage,node_user,node_model_provider toneIndigo
```

## Components

### Web application

- [Chat interface](https://github.com/vatshal-venkat/aether/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Chat state](https://github.com/vatshal-venkat/aether/blob/main/frontend/src/hooks/useChat.ts): `frontend/src/hooks/useChat.ts`
- [Backend client](https://github.com/vatshal-venkat/aether/blob/main/frontend/src/api/client.ts): `frontend/src/api/client.ts`
- [Answer display](https://github.com/vatshal-venkat/aether/blob/main/frontend/src/components/answer/AnswerCard.tsx): `frontend/src/components/answer/AnswerCard.tsx`

### API service

- [API application](https://github.com/vatshal-venkat/aether/blob/main/backend/app/main.py): `backend/app/main.py`
- [Chat endpoints](https://github.com/vatshal-venkat/aether/blob/main/backend/app/api/chat.py): `backend/app/api/chat.py`
- [Patient and schema API](https://github.com/vatshal-venkat/aether/blob/main/backend/app/api/catalog_routes.py): `backend/app/api/catalog_routes.py`
- [Operations endpoints](https://github.com/vatshal-venkat/aether/blob/main/backend/app/api/ops_routes.py): `backend/app/api/ops_routes.py`

### Question workflow

- [Question runner](https://github.com/vatshal-venkat/aether/blob/main/backend/app/graph/runner.py): `backend/app/graph/runner.py`
- [Graph construction](https://github.com/vatshal-venkat/aether/blob/main/backend/app/graph/build.py): `backend/app/graph/build.py`
- [Question stages](https://github.com/vatshal-venkat/aether/tree/main/backend/app/graph/nodes): `backend/app/graph/nodes`
- [Runtime dependencies](https://github.com/vatshal-venkat/aether/blob/main/backend/app/graph/deps.py): `backend/app/graph/deps.py`
- [Model client](https://github.com/vatshal-venkat/aether/blob/main/backend/app/llm/client.py): `backend/app/llm/client.py`

### Data and retrieval

- [Database connections](https://github.com/vatshal-venkat/aether/blob/main/backend/app/db/engines.py): `backend/app/db/engines.py`
- [Schema catalog](https://github.com/vatshal-venkat/aether/blob/main/backend/app/db/catalog.py): `backend/app/db/catalog.py`
- [Patient access](https://github.com/vatshal-venkat/aether/blob/main/backend/app/db/patients.py): `backend/app/db/patients.py`
- [Drug-label retrieval](https://github.com/vatshal-venkat/aether/blob/main/backend/app/rag/store.py): `backend/app/rag/store.py`
- [Conversation memory](https://github.com/vatshal-venkat/aether/blob/main/backend/app/memory/store.py): `backend/app/memory/store.py`
- [Saved SQL queries](https://github.com/vatshal-venkat/aether/blob/main/backend/app/memory/saved_queries.py): `backend/app/memory/saved_queries.py`

### Safety and operations

- [Query and answer safeguards](https://github.com/vatshal-venkat/aether/tree/main/backend/app/safety): `backend/app/safety`
- [Audit and service controls](https://github.com/vatshal-venkat/aether/blob/main/backend/app/ops/__init__.py): `backend/app/ops/__init__.py`
- [Model usage ledger](https://github.com/vatshal-venkat/aether/blob/main/backend/app/llm/usage.py): `backend/app/llm/usage.py`

### Other components

- **Clinician or patient**
- **Clinical and billing databases**
- **LLM provider**

## Connections

- Clinician or patient → Chat interface: asks question (evidence: `frontend/src/App.tsx`)
- Chat interface → Chat state: uses chat state (evidence: `frontend/src/App.tsx`)
- Chat state → Backend client: streams request (evidence: `frontend/src/hooks/useChat.ts`)
- Backend client → Chat endpoints: posts chat
- Chat endpoints → Question runner: runs question
- Question runner → Graph construction: builds graph (evidence: `backend/app/graph/runner.py`)
- Question runner → Runtime dependencies: uses dependencies (evidence: `backend/app/graph/runner.py`)
- Graph construction → Question stages: dispatches stages
- Runtime dependencies → Database connections: provides engines (evidence: `backend/app/graph/deps.py`)
- Runtime dependencies → Schema catalog: provides catalog (evidence: `backend/app/graph/deps.py`)
- Runtime dependencies → Drug-label retrieval: provides retrieval (evidence: `backend/app/graph/deps.py`)
- Runtime dependencies → Conversation memory: provides memory (evidence: `backend/app/graph/deps.py`)
- Runtime dependencies → Saved SQL queries: provides query store (evidence: `backend/app/graph/deps.py`)
- Runtime dependencies → Model client: provides model (evidence: `backend/app/graph/deps.py`)
- Database connections → Clinical and billing databases: connects (evidence: `backend/app/db/engines.py`)
- Model client → LLM provider: invokes
- Patient and schema API → Patient access: lists patients (evidence: `backend/app/api/catalog_routes.py`)
- Patient and schema API → Schema catalog: reads schema (evidence: `backend/app/api/catalog_routes.py`)
- API application → Chat endpoints: registers routes (evidence: `backend/app/main.py`)
- API application → Patient and schema API: registers routes (evidence: `backend/app/main.py`)
- API application → Operations endpoints: registers routes (evidence: `backend/app/main.py`)
- Operations endpoints → Audit and service controls: serves operations (evidence: `backend/app/api/ops_routes.py`)
- Question runner → Saved SQL queries: saves query (evidence: `backend/app/graph/runner.py`)
- Question runner → Query and answer safeguards: applies safeguards
- Question runner → Answer display: returns answer data (evidence: `backend/app/graph/runner.py`)
- Answer display → Clinician or patient: shows answer (evidence: `frontend/src/components/answer/AnswerCard.tsx`)
- Model client → Model usage ledger: records usage (evidence: `backend/app/llm/client.py`)
