# maastrichtu-ids/cohort-explorer architecture

> Architecture diagram of the GitHub repository maastrichtu-ids/cohort-explorer, 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/maastrichtu-ids/cohort-explorer
- Repository: https://github.com/maastrichtu-ids/cohort-explorer

## Overview

iCARE4CVD Cohort Explorer lets custodians upload and map cohort metadata, and lets scientists explore cohorts, analyze metadata, and configure Data Clean Rooms (DCRs). The main flow runs from the web UI through FastAPI routes to RDF metadata in a triplestore; selected cohort metadata is then used to provision a DCR through Decentriq. The graph preserves documented mapping, EDA, and no-code analysis branches. Backend route wiring is sampled; several feature details and the database implementation are documented but not present in the supplied tree.

Main entry points: [`frontend/src/pages`](https://github.com/maastrichtu-ids/cohort-explorer/tree/main/frontend/src/pages) (Explorer UI), [`backend/src/mapping.py`](https://github.com/maastrichtu-ids/cohort-explorer/blob/main/backend/src/mapping.py) (Mapping API), [`backend/src/decentriq.py`](https://github.com/maastrichtu-ids/cohort-explorer/blob/main/backend/src/decentriq.py) (DCR management), [`frontend/src/pages/cohorts.tsx`](https://github.com/maastrichtu-ids/cohort-explorer/blob/main/frontend/src/pages/cohorts.tsx) (Cohort explorer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web experience"]
  node_webapp["Explorer UI"]
  node_cohort_explore["Cohort explorer<br/>[cohorts.tsx]"]
  node_metadata_upload_ui["Metadata upload<br/>[upload.tsx]"]
  node_mapping_ui["Mapping UI<br/>[mapping.tsx]"]
  node_eda_ui["EDA dashboard<br/>[EdaDashboard.tsx]"]
  node_nocode_ui["No-code wizard<br/>[NocodeWizard.tsx]"]
end

subgraph group_api["Backend services"]
  node_api["FastAPI application<br/>[main.py]"]
  node_auth["OAuth and sessions<br/>[auth.py]"]
  node_upload["Metadata ingestion<br/>[upload.py]"]
  node_explore["Explore API<br/>[explore.py]"]
  node_mapping_api["Mapping API<br/>[mapping.py]"]
  node_dcr_api["DCR management<br/>[decentriq.py]"]
  node_analysis_api["Analysis API<br/>[data_analysis.py]"]
end

subgraph group_metadata["Metadata and mapping"]
  node_cross_mapping["Cross-study linker<br/>[main.py]"]
  node_triplestore[("RDF triplestore")]
end

subgraph group_analysis["Analysis tools"]
  node_eda_api["EDA services<br/>[eda_scripts.py]"]
  node_nocode_api["No-code analysis<br/>[nocode.py]"]
end

subgraph group_integrations["External platforms"]
  node_decentriq["Decentriq platform"]
  node_athena["OHDSI Athena"]
end

node_custodian(("Data custodian"))
node_scientist(("Data scientist"))

node_custodian -->|"uses"| node_webapp
node_scientist -->|"uses"| node_webapp
node_webapp -->|"authenticates"| node_auth
node_auth -->|"OAuth"| node_decentriq
node_webapp -->|"uploads through"| node_metadata_upload_ui
node_metadata_upload_ui -->|"sends metadata"| node_upload
node_upload -->|"writes RDF"| node_triplestore
node_webapp -->|"explores through"| node_cohort_explore
node_cohort_explore -->|"requests metadata"| node_explore
node_explore -->|"queries"| node_triplestore
node_webapp -->|"maps through"| node_mapping_ui
node_mapping_ui -->|"submits mappings"| node_mapping_api
node_mapping_api -->|"stores mappings"| node_triplestore
node_mapping_api -.->|"retrieves concepts"| node_athena
node_mapping_api -->|"generates mappings"| node_cross_mapping
node_webapp -->|"views EDA"| node_eda_ui
node_eda_ui -->|"requests summaries"| node_eda_api
node_webapp -->|"configures analysis"| node_nocode_ui
node_nocode_ui -->|"submits analysis"| node_nocode_api
node_nocode_api -->|"runs in DCR"| node_decentriq
node_webapp -->|"requests DCR"| node_dcr_api
node_dcr_api -->|"reads cohort metadata"| node_triplestore
node_dcr_api -->|"provisions DCR"| node_decentriq
node_webapp -->|"requests analysis"| node_analysis_api
node_analysis_api -->|"accesses DCR"| node_decentriq

click node_webapp "https://github.com/maastrichtu-ids/cohort-explorer/tree/main/frontend/src/pages"
click node_cohort_explore "https://github.com/maastrichtu-ids/cohort-explorer/blob/main/frontend/src/pages/cohorts.tsx"
click node_metadata_upload_ui "https://github.com/maastrichtu-ids/cohort-explorer/blob/main/frontend/src/pages/upload.tsx"
click node_mapping_ui "https://github.com/maastrichtu-ids/cohort-explorer/blob/main/frontend/src/pages/mapping.tsx"
click node_eda_ui "https://github.com/maastrichtu-ids/cohort-explorer/blob/main/frontend/src/components/eda/EdaDashboard.tsx"
click node_nocode_ui "https://github.com/maastrichtu-ids/cohort-explorer/blob/main/frontend/src/components/nocode/NocodeWizard.tsx"
click node_api "https://github.com/maastrichtu-ids/cohort-explorer/blob/main/backend/src/main.py"
click node_auth "https://github.com/maastrichtu-ids/cohort-explorer/blob/main/backend/src/auth.py"
click node_upload "https://github.com/maastrichtu-ids/cohort-explorer/blob/main/backend/src/upload.py"
click node_explore "https://github.com/maastrichtu-ids/cohort-explorer/blob/main/backend/src/explore.py"
click node_mapping_api "https://github.com/maastrichtu-ids/cohort-explorer/blob/main/backend/src/mapping.py"
click node_dcr_api "https://github.com/maastrichtu-ids/cohort-explorer/blob/main/backend/src/decentriq.py"
click node_analysis_api "https://github.com/maastrichtu-ids/cohort-explorer/blob/main/backend/src/data_analysis.py"
click node_eda_api "https://github.com/maastrichtu-ids/cohort-explorer/blob/main/backend/src/eda_scripts.py"
click node_nocode_api "https://github.com/maastrichtu-ids/cohort-explorer/blob/main/backend/src/nocode.py"
click node_cross_mapping "https://github.com/maastrichtu-ids/cohort-explorer/blob/main/backend/CohortVarLinker/main.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_webapp,node_cohort_explore,node_metadata_upload_ui,node_mapping_ui,node_eda_ui,node_nocode_ui toneBlue
class node_api,node_auth,node_upload,node_explore,node_mapping_api,node_dcr_api,node_analysis_api toneAmber
class node_cross_mapping,node_triplestore toneMint
class node_eda_api,node_nocode_api toneRose
class node_decentriq,node_athena,node_custodian,node_scientist toneIndigo
```

## Components

### Web experience

- [Explorer UI](https://github.com/maastrichtu-ids/cohort-explorer/tree/main/frontend/src/pages): `frontend/src/pages`
- [Cohort explorer](https://github.com/maastrichtu-ids/cohort-explorer/blob/main/frontend/src/pages/cohorts.tsx): `frontend/src/pages/cohorts.tsx`
- [Metadata upload](https://github.com/maastrichtu-ids/cohort-explorer/blob/main/frontend/src/pages/upload.tsx): `frontend/src/pages/upload.tsx`
- [Mapping UI](https://github.com/maastrichtu-ids/cohort-explorer/blob/main/frontend/src/pages/mapping.tsx): `frontend/src/pages/mapping.tsx`
- [EDA dashboard](https://github.com/maastrichtu-ids/cohort-explorer/blob/main/frontend/src/components/eda/EdaDashboard.tsx): `frontend/src/components/eda/EdaDashboard.tsx`
- [No-code wizard](https://github.com/maastrichtu-ids/cohort-explorer/blob/main/frontend/src/components/nocode/NocodeWizard.tsx): `frontend/src/components/nocode/NocodeWizard.tsx`

### Backend services

- [FastAPI application](https://github.com/maastrichtu-ids/cohort-explorer/blob/main/backend/src/main.py): `backend/src/main.py`
- [OAuth and sessions](https://github.com/maastrichtu-ids/cohort-explorer/blob/main/backend/src/auth.py): `backend/src/auth.py`
- [Metadata ingestion](https://github.com/maastrichtu-ids/cohort-explorer/blob/main/backend/src/upload.py): `backend/src/upload.py`
- [Explore API](https://github.com/maastrichtu-ids/cohort-explorer/blob/main/backend/src/explore.py): `backend/src/explore.py`
- [Mapping API](https://github.com/maastrichtu-ids/cohort-explorer/blob/main/backend/src/mapping.py): `backend/src/mapping.py`
- [DCR management](https://github.com/maastrichtu-ids/cohort-explorer/blob/main/backend/src/decentriq.py): `backend/src/decentriq.py`
- [Analysis API](https://github.com/maastrichtu-ids/cohort-explorer/blob/main/backend/src/data_analysis.py): `backend/src/data_analysis.py`

### Metadata and mapping

- [Cross-study linker](https://github.com/maastrichtu-ids/cohort-explorer/blob/main/backend/CohortVarLinker/main.py): `backend/CohortVarLinker/main.py`
- **RDF triplestore**

### Analysis tools

- [EDA services](https://github.com/maastrichtu-ids/cohort-explorer/blob/main/backend/src/eda_scripts.py): `backend/src/eda_scripts.py`
- [No-code analysis](https://github.com/maastrichtu-ids/cohort-explorer/blob/main/backend/src/nocode.py): `backend/src/nocode.py`

### External platforms

- **Decentriq platform**
- **OHDSI Athena**

### Other components

- **Data custodian**
- **Data scientist**

## Connections

- Data custodian → Explorer UI: uses
- Data scientist → Explorer UI: uses
- Explorer UI → OAuth and sessions: authenticates
- OAuth and sessions → Decentriq platform: OAuth
- Explorer UI → Metadata upload: uploads through
- Metadata upload → Metadata ingestion: sends metadata
- Metadata ingestion → RDF triplestore: writes RDF
- Explorer UI → Cohort explorer: explores through
- Cohort explorer → Explore API: requests metadata
- Explore API → RDF triplestore: queries
- Explorer UI → Mapping UI: maps through
- Mapping UI → Mapping API: submits mappings
- Mapping API → RDF triplestore: stores mappings
- Mapping API → OHDSI Athena: retrieves concepts
- Mapping API → Cross-study linker: generates mappings
- Explorer UI → EDA dashboard: views EDA
- EDA dashboard → EDA services: requests summaries
- Explorer UI → No-code wizard: configures analysis
- No-code wizard → No-code analysis: submits analysis
- No-code analysis → Decentriq platform: runs in DCR
- Explorer UI → DCR management: requests DCR
- DCR management → RDF triplestore: reads cohort metadata
- DCR management → Decentriq platform: provisions DCR
- Explorer UI → Analysis API: requests analysis
- Analysis API → Decentriq platform: accesses DCR