# mrqasimasif/cliniq architecture

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

- Interactive diagram: https://gitdiagram.com/mrqasimasif/cliniq
- Repository: https://github.com/mrqasimasif/cliniq

## Overview

ClinIQ lets researchers describe a trial search in conversational language, refine it over multiple turns, and receive ranked trial cards with an AI-written explanation. The main request flows from the chat UI through a Next.js proxy to the FastAPI chat handler, which restores session filters, parses intent, runs hard-filter and semantic retrieval, generates a response, and persists the session and matches. A separate ingestion job seeds and refreshes the trial store from ClinicalTrials.gov. The matcher excerpt is partial; links are shown only where supported by the supplied source or README.

Main entry points: [`backend/app/routers/chat.py`](https://github.com/mrqasimasif/cliniq/blob/master/backend/app/routers/chat.py) (Chat and session handler), [`frontend/app/page.tsx`](https://github.com/mrqasimasif/cliniq/blob/master/frontend/app/page.tsx) (Chat and results UI), [`frontend/app/api/chat/route.ts`](https://github.com/mrqasimasif/cliniq/blob/master/frontend/app/api/chat/route.ts) (Chat API proxy), [`backend/services/intent_parser.py`](https://github.com/mrqasimasif/cliniq/blob/master/backend/services/intent_parser.py) (Intent and response LLM)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["Researcher interface"]
  node_chat_ui["Chat and results UI<br/>[page.tsx]"]
  node_filter_badges["Filter badges<br/>[FilterBadges.tsx]"]
  node_trial_card["Trial cards<br/>[TrialCard.tsx]"]
  node_web_proxy["Chat API proxy<br/>[route.ts]"]
end

subgraph group_conversation["Conversation API"]
  node_chat_api["Chat and session handler<br/>[chat.py]"]
  node_intent_response["Intent and response LLM<br/>[intent_parser.py]"]
end

subgraph group_retrieval["Trial retrieval"]
  node_matcher["Two-stage matcher<br/>[matcher.py]"]
end

subgraph group_catalog["Trial catalog"]
  node_trial_db[("PostgreSQL trial store<br/>[001_init.sql]")]
  node_ingestion["Trial ingestion and embeddings<br/>[ingest_trials.py]"]
end

node_researcher(("Researcher"))
node_groq{{"Groq LLM"}}
node_ctg{{"ClinicalTrials.gov API"}}

node_researcher -->|"enters query"| node_chat_ui
node_chat_ui -->|"posts message"| node_web_proxy
node_web_proxy -->|"forwards request"| node_chat_api
node_chat_api -->|"parses intent"| node_intent_response
node_intent_response -->|"calls LLM"| node_groq
node_chat_api -->|"runs retrieval"| node_matcher
node_matcher -->|"queries trials"| node_trial_db
node_chat_api -->|"generates explanation"| node_intent_response
node_chat_api -->|"loads and saves session; saves matches"| node_trial_db
node_chat_api -->|"returns filters, trials, reply"| node_web_proxy
node_web_proxy -->|"returns response"| node_chat_ui
node_chat_ui -->|"shows active filters"| node_filter_badges
node_chat_ui -->|"renders matches"| node_trial_card
node_ingestion -->|"fetches studies"| node_ctg
node_ingestion -->|"upserts trials and embeddings"| node_trial_db

click node_chat_ui "https://github.com/mrqasimasif/cliniq/blob/master/frontend/app/page.tsx"
click node_filter_badges "https://github.com/mrqasimasif/cliniq/blob/master/frontend/components/FilterBadges.tsx"
click node_trial_card "https://github.com/mrqasimasif/cliniq/blob/master/frontend/components/TrialCard.tsx"
click node_web_proxy "https://github.com/mrqasimasif/cliniq/blob/master/frontend/app/api/chat/route.ts"
click node_chat_api "https://github.com/mrqasimasif/cliniq/blob/master/backend/app/routers/chat.py"
click node_intent_response "https://github.com/mrqasimasif/cliniq/blob/master/backend/services/intent_parser.py"
click node_matcher "https://github.com/mrqasimasif/cliniq/blob/master/backend/services/matcher.py"
click node_trial_db "https://github.com/mrqasimasif/cliniq/blob/master/001_init.sql"
click node_ingestion "https://github.com/mrqasimasif/cliniq/blob/master/backend/scripts/ingest_trials.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_filter_badges,node_trial_card,node_web_proxy toneBlue
class node_chat_api,node_intent_response toneAmber
class node_matcher,node_ctg toneMint
class node_trial_db,node_ingestion toneRose
class node_researcher,node_groq toneIndigo
```

## Components

### Researcher interface

- [Chat and results UI](https://github.com/mrqasimasif/cliniq/blob/master/frontend/app/page.tsx): `frontend/app/page.tsx`
- [Filter badges](https://github.com/mrqasimasif/cliniq/blob/master/frontend/components/FilterBadges.tsx): `frontend/components/FilterBadges.tsx`
- [Trial cards](https://github.com/mrqasimasif/cliniq/blob/master/frontend/components/TrialCard.tsx): `frontend/components/TrialCard.tsx`
- [Chat API proxy](https://github.com/mrqasimasif/cliniq/blob/master/frontend/app/api/chat/route.ts): `frontend/app/api/chat/route.ts`

### Conversation API

- [Chat and session handler](https://github.com/mrqasimasif/cliniq/blob/master/backend/app/routers/chat.py): `backend/app/routers/chat.py`
- [Intent and response LLM](https://github.com/mrqasimasif/cliniq/blob/master/backend/services/intent_parser.py): `backend/services/intent_parser.py`

### Trial retrieval

- [Two-stage matcher](https://github.com/mrqasimasif/cliniq/blob/master/backend/services/matcher.py): `backend/services/matcher.py`

### Trial catalog

- [PostgreSQL trial store](https://github.com/mrqasimasif/cliniq/blob/master/001_init.sql): `001_init.sql`
- [Trial ingestion and embeddings](https://github.com/mrqasimasif/cliniq/blob/master/backend/scripts/ingest_trials.py): `backend/scripts/ingest_trials.py`

### Other components

- **Researcher**
- **Groq LLM**
- **ClinicalTrials.gov API**

## Connections

- Researcher → Chat and results UI: enters query
- Chat and results UI → Chat API proxy: posts message
- Chat API proxy → Chat and session handler: forwards request
- Chat and session handler → Intent and response LLM: parses intent
- Intent and response LLM → Groq LLM: calls LLM
- Chat and session handler → Two-stage matcher: runs retrieval
- Two-stage matcher → PostgreSQL trial store: queries trials
- Chat and session handler → Intent and response LLM: generates explanation
- Chat and session handler → PostgreSQL trial store: loads and saves session; saves matches
- Chat and session handler → Chat API proxy: returns filters, trials, reply
- Chat API proxy → Chat and results UI: returns response
- Chat and results UI → Filter badges: shows active filters
- Chat and results UI → Trial cards: renders matches
- Trial ingestion and embeddings → ClinicalTrials.gov API: fetches studies
- Trial ingestion and embeddings → PostgreSQL trial store: upserts trials and embeddings