# hms-dbmi/cvh architecture

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

- Interactive diagram: https://gitdiagram.com/hms-dbmi/cvh
- Repository: https://github.com/hms-dbmi/cvh

## Overview

Community Visualization Hub is a web platform for creating, organizing, and sharing genomic and single-cell visualizations. Users authenticate, work in shared or private workspaces, add and process datasets, then create and publish Gosling or Vitessce visualizations. The frontend feature hooks call the backend API; the Python client offers a separate programmatic interface. The tree and excerpts establish the frontend API calls and client behavior, but do not expose backend handler internals, so uncertain service wiring is omitted.

Main entry points: [`backend/core/api/api.py`](https://github.com/hms-dbmi/cvh/blob/main/backend/core/api/api.py) (API application), [`frontend/src/api/client.ts`](https://github.com/hms-dbmi/cvh/blob/main/frontend/src/api/client.ts) (Web API client), [`frontend/src/main.tsx`](https://github.com/hms-dbmi/cvh/blob/main/frontend/src/main.tsx) (Web app), [`frontend/src/features/visualizations/api/useVisualizations.ts`](https://github.com/hms-dbmi/cvh/blob/main/frontend/src/features/visualizations/api/useVisualizations.ts) (Visualization features)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web application"]
  node_frontend["Web app<br/>[main.tsx]"]
  node_workspace_ui["Workspace features<br/>[useProjects.ts]"]
  node_dataset_ui["Dataset features<br/>[useDatasets.ts]"]
  node_api_client["Web API client<br/>[client.ts]"]
end

subgraph group_backend["Backend platform"]
  node_backend_api["API application<br/>[api.py]"]
  node_workspace_routes["Workspace routes<br/>[workspaces.py]"]
  node_dataset_routes["Dataset routes<br/>[datasets.py]"]
  node_viz_routes["Visualization routes<br/>[visualizations.py]"]
  node_models["Domain models<br/>[models.py]"]
  node_database[("PostgreSQL")]
  node_cfdb["Processing integration<br/>[cfdb.py]"]
  node_ingest["Dataset ingestion<br/>[ingest_datasets.py]"]
end

subgraph group_visualization["Visualization"]
  node_viz_ui["Visualization features"]
  node_gosling["Gosling viewer<br/>[GoslingViewer.tsx]"]
  node_vitessce["Vitessce viewer<br/>[VitessceViewer.tsx]"]
end

subgraph group_clients["API clients"]
  node_python_client["Python client<br/>[client.py]"]
end

node_user(("Hub user"))
node_auth0["Auth0"]

node_user -->|"uses"| node_frontend
node_frontend -->|"manages workspaces"| node_workspace_ui
node_frontend -->|"manages datasets"| node_dataset_ui
node_frontend -->|"creates visualizations"| node_viz_ui
node_workspace_ui -->|"requests workspace API"| node_api_client
node_dataset_ui -->|"requests dataset API"| node_api_client
node_viz_ui -->|"requests visualization API"| node_api_client
node_api_client -->|"sends API requests"| node_backend_api
node_user -->|"authenticates"| node_auth0
node_api_client -->|"gets access token"| node_auth0
node_backend_api -->|"dispatches"| node_workspace_routes
node_backend_api -->|"dispatches"| node_dataset_routes
node_backend_api -->|"dispatches"| node_viz_routes
node_viz_ui -->|"renders Gosling"| node_gosling
node_viz_ui -->|"renders Vitessce"| node_vitessce
node_python_client -->|"sends API requests"| node_backend_api
node_ingest -->|"creates records"| node_models
node_ingest -->|"writes datasets"| node_database

click node_frontend "https://github.com/hms-dbmi/cvh/blob/main/frontend/src/main.tsx"
click node_workspace_ui "https://github.com/hms-dbmi/cvh/blob/main/frontend/src/features/projects/api/useProjects.ts"
click node_dataset_ui "https://github.com/hms-dbmi/cvh/blob/main/frontend/src/features/datasets/api/useDatasets.ts"
click node_viz_ui "https://github.com/hms-dbmi/cvh/blob/main/frontend/src/features/visualizations/api/useVisualizations.ts"
click node_api_client "https://github.com/hms-dbmi/cvh/blob/main/frontend/src/api/client.ts"
click node_backend_api "https://github.com/hms-dbmi/cvh/blob/main/backend/core/api/api.py"
click node_workspace_routes "https://github.com/hms-dbmi/cvh/blob/main/backend/core/api/routers/workspaces.py"
click node_dataset_routes "https://github.com/hms-dbmi/cvh/blob/main/backend/core/api/routers/datasets.py"
click node_viz_routes "https://github.com/hms-dbmi/cvh/blob/main/backend/core/api/routers/visualizations.py"
click node_models "https://github.com/hms-dbmi/cvh/blob/main/backend/core/api/models.py"
click node_cfdb "https://github.com/hms-dbmi/cvh/blob/main/backend/core/api/cfdb.py"
click node_gosling "https://github.com/hms-dbmi/cvh/blob/main/frontend/src/features/visualizations/components/GoslingViewer.tsx"
click node_vitessce "https://github.com/hms-dbmi/cvh/blob/main/frontend/src/features/visualizations/components/VitessceViewer.tsx"
click node_python_client "https://github.com/hms-dbmi/cvh/blob/main/python-client/src/cvh_client/client.py"
click node_ingest "https://github.com/hms-dbmi/cvh/blob/main/backend/core/api/management/commands/ingest_datasets.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_frontend,node_workspace_ui,node_dataset_ui,node_api_client,node_user toneBlue
class node_backend_api,node_workspace_routes,node_dataset_routes,node_viz_routes,node_models,node_database,node_cfdb,node_ingest toneAmber
class node_viz_ui,node_gosling,node_vitessce toneMint
class node_python_client toneRose
class node_auth0 toneIndigo
```

## Components

### Web application

- [Web app](https://github.com/hms-dbmi/cvh/blob/main/frontend/src/main.tsx): `frontend/src/main.tsx`
- [Workspace features](https://github.com/hms-dbmi/cvh/blob/main/frontend/src/features/projects/api/useProjects.ts): `frontend/src/features/projects/api/useProjects.ts`
- [Dataset features](https://github.com/hms-dbmi/cvh/blob/main/frontend/src/features/datasets/api/useDatasets.ts): `frontend/src/features/datasets/api/useDatasets.ts`
- [Web API client](https://github.com/hms-dbmi/cvh/blob/main/frontend/src/api/client.ts): `frontend/src/api/client.ts`

### Backend platform

- [API application](https://github.com/hms-dbmi/cvh/blob/main/backend/core/api/api.py): `backend/core/api/api.py`
- [Workspace routes](https://github.com/hms-dbmi/cvh/blob/main/backend/core/api/routers/workspaces.py): `backend/core/api/routers/workspaces.py`
- [Dataset routes](https://github.com/hms-dbmi/cvh/blob/main/backend/core/api/routers/datasets.py): `backend/core/api/routers/datasets.py`
- [Visualization routes](https://github.com/hms-dbmi/cvh/blob/main/backend/core/api/routers/visualizations.py): `backend/core/api/routers/visualizations.py`
- [Domain models](https://github.com/hms-dbmi/cvh/blob/main/backend/core/api/models.py): `backend/core/api/models.py`
- **PostgreSQL**
- [Processing integration](https://github.com/hms-dbmi/cvh/blob/main/backend/core/api/cfdb.py): `backend/core/api/cfdb.py`
- [Dataset ingestion](https://github.com/hms-dbmi/cvh/blob/main/backend/core/api/management/commands/ingest_datasets.py): `backend/core/api/management/commands/ingest_datasets.py`

### Visualization

- [Visualization features](https://github.com/hms-dbmi/cvh/blob/main/frontend/src/features/visualizations/api/useVisualizations.ts): `frontend/src/features/visualizations/api/useVisualizations.ts`
- [Gosling viewer](https://github.com/hms-dbmi/cvh/blob/main/frontend/src/features/visualizations/components/GoslingViewer.tsx): `frontend/src/features/visualizations/components/GoslingViewer.tsx`
- [Vitessce viewer](https://github.com/hms-dbmi/cvh/blob/main/frontend/src/features/visualizations/components/VitessceViewer.tsx): `frontend/src/features/visualizations/components/VitessceViewer.tsx`

### API clients

- [Python client](https://github.com/hms-dbmi/cvh/blob/main/python-client/src/cvh_client/client.py): `python-client/src/cvh_client/client.py`

### Other components

- **Hub user**
- **Auth0**

## Connections

- Hub user → Web app: uses
- Web app → Workspace features: manages workspaces
- Web app → Dataset features: manages datasets
- Web app → Visualization features: creates visualizations
- Workspace features → Web API client: requests workspace API
- Dataset features → Web API client: requests dataset API
- Visualization features → Web API client: requests visualization API
- Web API client → API application: sends API requests
- Hub user → Auth0: authenticates
- Web API client → Auth0: gets access token
- API application → Workspace routes: dispatches
- API application → Dataset routes: dispatches
- API application → Visualization routes: dispatches
- Visualization features → Gosling viewer: renders Gosling
- Visualization features → Vitessce viewer: renders Vitessce
- Python client → API application: sends API requests
- Dataset ingestion → Domain models: creates records
- Dataset ingestion → PostgreSQL: writes datasets