# larib-data/clinical-scope architecture

> Architecture diagram of the GitHub repository larib-data/clinical-scope, 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/larib-data/clinical-scope
- Repository: https://github.com/larib-data/clinical-scope

## Overview

ClinicalScope is a browser-based clinical time-series dashboard with a parallel Python/CLI extraction workflow. The main user journey is to load database options and patient data, process device recordings into aligned signals, view interactive plots, annotate them, and save annotations or exports. The graph also preserves inspection and standalone processing as distinct capabilities. Some connections reflect README-documented behavior; unsampled implementations are represented by their existing directories rather than inferred module names.

Main entry points: [`src/clinical_scope/datasource/base.py`](https://github.com/larib-data/clinical-scope/blob/main/src/clinical_scope/datasource/base.py) (Source processing), [`src/clinical_scope/datasource/registry.py`](https://github.com/larib-data/clinical-scope/blob/main/src/clinical_scope/datasource/registry.py) (Source registry), [`src/clinical_scope/config/parsing.py`](https://github.com/larib-data/clinical-scope/blob/main/src/clinical_scope/config/parsing.py) (Options parsing), [`src/clinical_scope/dash_api/core_api.py`](https://github.com/larib-data/clinical-scope/blob/main/src/clinical_scope/dash_api/core_api.py) (Dashboard API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_configuration["Configuration"]
  node_options["Options parsing<br/>[parsing.py]"]
  node_options_validation["Options validation"]
  node_xlsx_options["XLSX options"]
end

subgraph group_processing["Data processing"]
  node_datasource_registry["Source registry<br/>[registry.py]"]
  node_source_adapters["Device adapters"]
  node_datasource_base["Source processing<br/>[base.py]"]
  node_time_axis["Time-axis detection<br/>[time_axis.py]"]
  node_timezone["Time normalization<br/>[timezone.py]"]
  node_inspection["Data inspection<br/>[inspection.py]"]
  node_export["Data export<br/>[export.py]"]
  node_cache[("Parquet cache<br/>[base.py]")]
end

subgraph group_visualization["Visualization"]
  node_signal_container["Signal model"]
  node_plot_registry["Plot types<br/>[registry.py]"]
  node_plot_assembly["Plot assembly<br/>[plot_assembly.py]"]
end

subgraph group_interaction["Dashboard and annotations"]
  node_dashboard["Dashboard API<br/>[core_api.py]"]
  node_callbacks["Dashboard callbacks"]
  node_annotations["Annotation model<br/>[model.py]"]
  node_annotation_io["Annotation storage<br/>[io.py]"]
end

subgraph group_api["Standalone API"]
  node_cli["CLI<br/>[cli.py]"]
  node_wrapper["Extraction API<br/>[wrapper.py]"]
end

node_researcher(("Researcher"))
node_patient_data["Patient recordings"]
node_browser(("Web browser"))

node_researcher -->|"uses"| node_browser
node_researcher -->|"runs"| node_cli
node_patient_data -->|"provides recordings"| node_datasource_registry
node_researcher -->|"loads config"| node_options
node_options -->|"parses XLSX"| node_xlsx_options
node_options -->|"validates options"| node_options_validation
node_datasource_registry -->|"dispatches sources"| node_source_adapters
node_datasource_registry -->|"registers processor"| node_datasource_base
node_source_adapters -->|"use common processing"| node_datasource_base
node_datasource_base -->|"detects time axis"| node_time_axis
node_datasource_base -->|"formats timestamps"| node_timezone
node_datasource_base -->|"reads and writes"| node_cache
node_datasource_base -->|"creates signals"| node_signal_container
node_researcher -->|"inspects recordings"| node_inspection
node_signal_container -->|"provides plot inputs"| node_plot_registry
node_plot_registry -->|"selects plot types"| node_plot_assembly
node_researcher -->|"processes visualization"| node_dashboard
node_dashboard -->|"registers callbacks"| node_callbacks
node_callbacks -->|"updates annotations"| node_annotations
node_callbacks -->|"saves annotations"| node_annotation_io
node_dashboard -->|"serves dashboard"| node_browser
node_researcher -->|"creates marks"| node_annotations
node_researcher -->|"extracts data"| node_export
node_cli -.->|"runs extraction"| node_wrapper
node_wrapper -->|"selects sources"| node_datasource_registry
node_wrapper -->|"returns signals"| node_signal_container

click node_cli "https://github.com/larib-data/clinical-scope/blob/main/src/clinical_scope/cli.py"
click node_options "https://github.com/larib-data/clinical-scope/blob/main/src/clinical_scope/config/parsing.py"
click node_options_validation "https://github.com/larib-data/clinical-scope/blob/main/src/clinical_scope/database_options_parser.py"
click node_xlsx_options "https://github.com/larib-data/clinical-scope/blob/main/src/clinical_scope/database_options_xlsx.py"
click node_datasource_registry "https://github.com/larib-data/clinical-scope/blob/main/src/clinical_scope/datasource/registry.py"
click node_source_adapters "https://github.com/larib-data/clinical-scope/tree/main/src/clinical_scope/datasource/sources"
click node_datasource_base "https://github.com/larib-data/clinical-scope/blob/main/src/clinical_scope/datasource/base.py"
click node_time_axis "https://github.com/larib-data/clinical-scope/blob/main/src/clinical_scope/io/time_axis.py"
click node_timezone "https://github.com/larib-data/clinical-scope/blob/main/src/clinical_scope/datasource/formatting/timezone.py"
click node_inspection "https://github.com/larib-data/clinical-scope/blob/main/src/clinical_scope/datasource/inspection.py"
click node_signal_container "https://github.com/larib-data/clinical-scope/blob/main/src/clinical_scope/signal_container.py"
click node_plot_registry "https://github.com/larib-data/clinical-scope/blob/main/src/clinical_scope/plot_types/registry.py"
click node_plot_assembly "https://github.com/larib-data/clinical-scope/blob/main/src/clinical_scope/plot_assembly.py"
click node_dashboard "https://github.com/larib-data/clinical-scope/blob/main/src/clinical_scope/dash_api/core_api.py"
click node_callbacks "https://github.com/larib-data/clinical-scope/tree/main/src/clinical_scope/dash_api/callbacks"
click node_annotations "https://github.com/larib-data/clinical-scope/blob/main/src/clinical_scope/dash_api/annotations/model.py"
click node_annotation_io "https://github.com/larib-data/clinical-scope/blob/main/src/clinical_scope/dash_api/annotations/io.py"
click node_export "https://github.com/larib-data/clinical-scope/blob/main/src/clinical_scope/io/export.py"
click node_wrapper "https://github.com/larib-data/clinical-scope/blob/main/src/clinical_scope/wrapper.py"
click node_cache "https://github.com/larib-data/clinical-scope/blob/main/src/clinical_scope/datasource/base.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_options,node_options_validation,node_xlsx_options,node_browser toneBlue
class node_datasource_registry,node_source_adapters,node_datasource_base,node_time_axis,node_timezone,node_inspection,node_export,node_cache toneAmber
class node_signal_container,node_plot_registry,node_plot_assembly toneMint
class node_dashboard,node_callbacks,node_annotations,node_annotation_io toneRose
class node_cli,node_wrapper,node_researcher,node_patient_data toneIndigo
```

## Components

### Configuration

- [Options parsing](https://github.com/larib-data/clinical-scope/blob/main/src/clinical_scope/config/parsing.py): `src/clinical_scope/config/parsing.py`
- [Options validation](https://github.com/larib-data/clinical-scope/blob/main/src/clinical_scope/database_options_parser.py): `src/clinical_scope/database_options_parser.py`
- [XLSX options](https://github.com/larib-data/clinical-scope/blob/main/src/clinical_scope/database_options_xlsx.py): `src/clinical_scope/database_options_xlsx.py`

### Data processing

- [Source registry](https://github.com/larib-data/clinical-scope/blob/main/src/clinical_scope/datasource/registry.py): `src/clinical_scope/datasource/registry.py`
- [Device adapters](https://github.com/larib-data/clinical-scope/tree/main/src/clinical_scope/datasource/sources): `src/clinical_scope/datasource/sources`
- [Source processing](https://github.com/larib-data/clinical-scope/blob/main/src/clinical_scope/datasource/base.py): `src/clinical_scope/datasource/base.py`
- [Time-axis detection](https://github.com/larib-data/clinical-scope/blob/main/src/clinical_scope/io/time_axis.py): `src/clinical_scope/io/time_axis.py`
- [Time normalization](https://github.com/larib-data/clinical-scope/blob/main/src/clinical_scope/datasource/formatting/timezone.py): `src/clinical_scope/datasource/formatting/timezone.py`
- [Data inspection](https://github.com/larib-data/clinical-scope/blob/main/src/clinical_scope/datasource/inspection.py): `src/clinical_scope/datasource/inspection.py`
- [Data export](https://github.com/larib-data/clinical-scope/blob/main/src/clinical_scope/io/export.py): `src/clinical_scope/io/export.py`
- [Parquet cache](https://github.com/larib-data/clinical-scope/blob/main/src/clinical_scope/datasource/base.py): `src/clinical_scope/datasource/base.py`

### Visualization

- [Signal model](https://github.com/larib-data/clinical-scope/blob/main/src/clinical_scope/signal_container.py): `src/clinical_scope/signal_container.py`
- [Plot types](https://github.com/larib-data/clinical-scope/blob/main/src/clinical_scope/plot_types/registry.py): `src/clinical_scope/plot_types/registry.py`
- [Plot assembly](https://github.com/larib-data/clinical-scope/blob/main/src/clinical_scope/plot_assembly.py): `src/clinical_scope/plot_assembly.py`

### Dashboard and annotations

- [Dashboard API](https://github.com/larib-data/clinical-scope/blob/main/src/clinical_scope/dash_api/core_api.py): `src/clinical_scope/dash_api/core_api.py`
- [Dashboard callbacks](https://github.com/larib-data/clinical-scope/tree/main/src/clinical_scope/dash_api/callbacks): `src/clinical_scope/dash_api/callbacks`
- [Annotation model](https://github.com/larib-data/clinical-scope/blob/main/src/clinical_scope/dash_api/annotations/model.py): `src/clinical_scope/dash_api/annotations/model.py`
- [Annotation storage](https://github.com/larib-data/clinical-scope/blob/main/src/clinical_scope/dash_api/annotations/io.py): `src/clinical_scope/dash_api/annotations/io.py`

### Standalone API

- [CLI](https://github.com/larib-data/clinical-scope/blob/main/src/clinical_scope/cli.py): `src/clinical_scope/cli.py`
- [Extraction API](https://github.com/larib-data/clinical-scope/blob/main/src/clinical_scope/wrapper.py): `src/clinical_scope/wrapper.py`

### Other components

- **Researcher**
- **Patient recordings**
- **Web browser**

## Connections

- Researcher → Web browser: uses (evidence: `README.md`)
- Researcher → CLI: runs (evidence: `README.md`)
- Patient recordings → Source registry: provides recordings (evidence: `README.md`)
- Researcher → Options parsing: loads config (evidence: `README.md`)
- Options parsing → XLSX options: parses XLSX (evidence: `src/clinical_scope/config/parsing.py`)
- Options parsing → Options validation: validates options (evidence: `src/clinical_scope/config/parsing.py`)
- Source registry → Device adapters: dispatches sources (evidence: `src/clinical_scope/datasource/registry.py`)
- Source registry → Source processing: registers processor (evidence: `src/clinical_scope/datasource/registry.py`)
- Device adapters → Source processing: use common processing (evidence: `src/clinical_scope/datasource/sources/edf/find_load_format.py`)
- Source processing → Time-axis detection: detects time axis (evidence: `src/clinical_scope/datasource/base.py`)
- Source processing → Time normalization: formats timestamps (evidence: `src/clinical_scope/datasource/base.py`)
- Source processing → Parquet cache: reads and writes (evidence: `src/clinical_scope/datasource/base.py`)
- Source processing → Signal model: creates signals (evidence: `src/clinical_scope/datasource/base.py`)
- Researcher → Data inspection: inspects recordings (evidence: `README.md`)
- Signal model → Plot types: provides plot inputs
- Plot types → Plot assembly: selects plot types (evidence: `src/clinical_scope/plot_types/registry.py`)
- Researcher → Dashboard API: processes visualization (evidence: `README.md`)
- Dashboard API → Dashboard callbacks: registers callbacks (evidence: `src/clinical_scope/dash_api/core_api.py`)
- Dashboard callbacks → Annotation model: updates annotations (evidence: `src/clinical_scope/dash_api/callbacks/annotation_callbacks.py`)
- Dashboard callbacks → Annotation storage: saves annotations (evidence: `src/clinical_scope/dash_api/callbacks/annotation_callbacks.py`)
- Dashboard API → Web browser: serves dashboard (evidence: `README.md`)
- Researcher → Annotation model: creates marks (evidence: `README.md`)
- Researcher → Data export: extracts data (evidence: `README.md`)
- CLI → Extraction API: runs extraction
- Extraction API → Source registry: selects sources (evidence: `scripts/process_patient_data.py`)
- Extraction API → Signal model: returns signals (evidence: `scripts/visualization_patient_data.py`)
