# yash-ranjan-124/ultrasound_automation architecture

> Architecture diagram of the GitHub repository yash-ranjan-124/ultrasound_automation, 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/yash-ranjan-124/ultrasound_automation
- Repository: https://github.com/yash-ranjan-124/ultrasound_automation

## Overview

MedVision AI Lab is a research-and-education imaging workstation, currently focused on registering imaging studies rather than running analysis. Users can browse the registry and inspect a study’s technical metadata; uploads accept video, NIfTI, DICOM, and image files with a declared modality. The frontend overview also presents tracking, segmentation, and detection as planned workflows, not implemented results. The sampled backend shows upload orchestration and configured persistence/storage; relationships for unsampled details are omitted. Root-level prototype scripts are separate from the browser application.

Main entry points: [`backend/src/medvision/application/services/create_study.py`](https://github.com/yash-ranjan-124/ultrasound_automation/blob/master/backend/src/medvision/application/services/create_study.py) (Study ingestion), [`backend/src/medvision/main.py`](https://github.com/yash-ranjan-124/ultrasound_automation/blob/master/backend/src/medvision/main.py) (FastAPI application), [`frontend/src/main.tsx`](https://github.com/yash-ranjan-124/ultrasound_automation/blob/master/frontend/src/main.tsx) (Browser workstation), [`frontend/src/features/overview/WorkflowCard.tsx`](https://github.com/yash-ranjan-124/ultrasound_automation/blob/master/frontend/src/features/overview/WorkflowCard.tsx) (Workflow cards)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web experience"]
  node_browser["Browser workstation<br/>[main.tsx]"]
  node_overview["Overview and roadmap<br/>[App.tsx]"]
  node_workflowcards["Workflow cards<br/>[WorkflowCard.tsx]"]
  node_healthview["Service status<br/>[ServiceStatus.tsx]"]
  node_healthhook["Health query"]
  node_studiespage["Study catalog view<br/>[StudiesPage.tsx]"]
  node_detailpage["Study detail view"]
  node_studylayout["Study layout<br/>[StudyLayout.tsx]"]
  node_studyformat["Study formatting<br/>[study-format.ts]"]
  node_studyhook["Study queries<br/>[use-studies.ts]"]
  node_studyapi["Study API client<br/>[studies.ts]"]
  node_studytypes["Study response types<br/>[study.ts]"]
  node_healthapi["Health API client<br/>[health.ts]"]
  node_plannedtracking{{"Ultrasound tracking<br/>[App.tsx]"}}
  node_plannedsegmentation{{"Brain MRI segmentation<br/>[App.tsx]"}}
  node_plannedetection{{"Lung CT detection<br/>[App.tsx]"}}
end

subgraph group_api["API and application"]
  node_backend["FastAPI application<br/>[main.py]"]
  node_healthroute["Health endpoint<br/>[health.py]"]
  node_studiesroute["Study endpoints<br/>[studies.py]"]
  node_createservice["Study ingestion<br/>[create_study.py]"]
  node_catalogservice["Study catalog service<br/>[study_catalog.py]"]
end

subgraph group_domain["Study domain"]
  node_studyentity["Imaging study records<br/>[__init__.py]"]
  node_studytypeserver["Study types and modalities<br/>[__init__.py]"]
end

subgraph group_infra["Persistence and files"]
  node_metadatareader["Technical metadata reader<br/>[metadata.py]"]
  node_localstorage["Local file storage<br/>[local_file.py]"]
  node_repository["SQL study repository"]
  node_dbmodels["Database study models<br/>[models.py]"]
  node_database[("PostgreSQL")]
end

node_researcher(("Research user"))

node_researcher -->|"uses"| node_browser
node_browser -->|"routes to"| node_overview
node_browser -->|"routes to"| node_studiespage
node_browser -->|"routes to"| node_detailpage
node_overview -->|"renders"| node_workflowcards
node_overview -->|"renders"| node_healthview
node_healthview -->|"queries"| node_healthhook
node_healthhook -->|"calls"| node_healthapi
node_studiespage -->|"queries"| node_studyhook
node_detailpage -->|"queries"| node_studyhook
node_studiespage -->|"renders"| node_studylayout
node_detailpage -->|"renders"| node_studylayout
node_studiespage -->|"formats"| node_studyformat
node_detailpage -->|"formats"| node_studyformat
node_studyhook -->|"calls"| node_studyapi
node_studyapi -->|"uses"| node_studytypes
node_studyformat -->|"uses"| node_studytypes
node_healthapi -.->|"requests health"| node_healthroute
node_studyapi -.->|"requests studies"| node_studiesroute
node_backend -->|"registers"| node_healthroute
node_backend -->|"registers"| node_studiesroute
node_studiesroute -->|"invokes"| node_createservice
node_studiesroute -->|"invokes"| node_catalogservice
node_backend -->|"configures"| node_createservice
node_backend -->|"configures"| node_catalogservice
node_createservice -->|"saves files"| node_localstorage
node_createservice -->|"extracts metadata"| node_metadatareader
node_createservice -->|"saves record"| node_repository
node_createservice -->|"creates"| node_studyentity
node_createservice -->|"resolves type"| node_studytypeserver
node_repository -->|"maps to"| node_dbmodels
node_repository -.->|"reads and writes"| node_database
node_workflowcards -->|"presents planned"| node_plannedtracking
node_workflowcards -->|"presents planned"| node_plannedsegmentation
node_workflowcards -->|"presents planned"| node_plannedetection

click node_browser "https://github.com/yash-ranjan-124/ultrasound_automation/blob/master/frontend/src/main.tsx"
click node_overview "https://github.com/yash-ranjan-124/ultrasound_automation/blob/master/frontend/src/app/App.tsx"
click node_workflowcards "https://github.com/yash-ranjan-124/ultrasound_automation/blob/master/frontend/src/features/overview/WorkflowCard.tsx"
click node_healthview "https://github.com/yash-ranjan-124/ultrasound_automation/blob/master/frontend/src/components/ServiceStatus.tsx"
click node_healthhook "https://github.com/yash-ranjan-124/ultrasound_automation/blob/master/frontend/src/hooks/use-health-status.ts"
click node_studiespage "https://github.com/yash-ranjan-124/ultrasound_automation/blob/master/frontend/src/features/studies/StudiesPage.tsx"
click node_detailpage "https://github.com/yash-ranjan-124/ultrasound_automation/blob/master/frontend/src/features/studies/StudyDetailPage.tsx"
click node_studylayout "https://github.com/yash-ranjan-124/ultrasound_automation/blob/master/frontend/src/features/studies/StudyLayout.tsx"
click node_studyformat "https://github.com/yash-ranjan-124/ultrasound_automation/blob/master/frontend/src/features/studies/study-format.ts"
click node_studyhook "https://github.com/yash-ranjan-124/ultrasound_automation/blob/master/frontend/src/hooks/use-studies.ts"
click node_studyapi "https://github.com/yash-ranjan-124/ultrasound_automation/blob/master/frontend/src/api/studies.ts"
click node_studytypes "https://github.com/yash-ranjan-124/ultrasound_automation/blob/master/frontend/src/types/study.ts"
click node_healthapi "https://github.com/yash-ranjan-124/ultrasound_automation/blob/master/frontend/src/api/health.ts"
click node_backend "https://github.com/yash-ranjan-124/ultrasound_automation/blob/master/backend/src/medvision/main.py"
click node_healthroute "https://github.com/yash-ranjan-124/ultrasound_automation/blob/master/backend/src/medvision/api/routers/health.py"
click node_studiesroute "https://github.com/yash-ranjan-124/ultrasound_automation/blob/master/backend/src/medvision/api/routers/studies.py"
click node_createservice "https://github.com/yash-ranjan-124/ultrasound_automation/blob/master/backend/src/medvision/application/services/create_study.py"
click node_catalogservice "https://github.com/yash-ranjan-124/ultrasound_automation/blob/master/backend/src/medvision/application/services/study_catalog.py"
click node_studyentity "https://github.com/yash-ranjan-124/ultrasound_automation/blob/master/backend/src/medvision/domain/entities/__init__.py"
click node_studytypeserver "https://github.com/yash-ranjan-124/ultrasound_automation/blob/master/backend/src/medvision/domain/enums/__init__.py"
click node_metadatareader "https://github.com/yash-ranjan-124/ultrasound_automation/blob/master/backend/src/medvision/infrastructure/imaging/metadata.py"
click node_localstorage "https://github.com/yash-ranjan-124/ultrasound_automation/blob/master/backend/src/medvision/infrastructure/storage/local_file.py"
click node_repository "https://github.com/yash-ranjan-124/ultrasound_automation/blob/master/backend/src/medvision/infrastructure/persistence/sqlalchemy_repository.py"
click node_dbmodels "https://github.com/yash-ranjan-124/ultrasound_automation/blob/master/backend/src/medvision/infrastructure/persistence/models.py"
click node_plannedtracking "https://github.com/yash-ranjan-124/ultrasound_automation/blob/master/frontend/src/app/App.tsx"
click node_plannedsegmentation "https://github.com/yash-ranjan-124/ultrasound_automation/blob/master/frontend/src/app/App.tsx"
click node_plannedetection "https://github.com/yash-ranjan-124/ultrasound_automation/blob/master/frontend/src/app/App.tsx"

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_browser,node_overview,node_workflowcards,node_healthview,node_healthhook,node_studiespage,node_detailpage,node_studylayout,node_studyformat,node_studyhook,node_studyapi,node_studytypes,node_healthapi,node_plannedtracking,node_plannedsegmentation,node_plannedetection,node_researcher toneBlue
class node_backend,node_healthroute,node_studiesroute,node_createservice,node_catalogservice toneAmber
class node_studyentity,node_studytypeserver toneMint
class node_metadatareader,node_localstorage,node_repository,node_dbmodels,node_database toneRose
```

## Components

### Web experience

- [Browser workstation](https://github.com/yash-ranjan-124/ultrasound_automation/blob/master/frontend/src/main.tsx): `frontend/src/main.tsx`
- [Overview and roadmap](https://github.com/yash-ranjan-124/ultrasound_automation/blob/master/frontend/src/app/App.tsx): `frontend/src/app/App.tsx`
- [Workflow cards](https://github.com/yash-ranjan-124/ultrasound_automation/blob/master/frontend/src/features/overview/WorkflowCard.tsx): `frontend/src/features/overview/WorkflowCard.tsx`
- [Service status](https://github.com/yash-ranjan-124/ultrasound_automation/blob/master/frontend/src/components/ServiceStatus.tsx): `frontend/src/components/ServiceStatus.tsx`
- [Health query](https://github.com/yash-ranjan-124/ultrasound_automation/blob/master/frontend/src/hooks/use-health-status.ts): `frontend/src/hooks/use-health-status.ts`
- [Study catalog view](https://github.com/yash-ranjan-124/ultrasound_automation/blob/master/frontend/src/features/studies/StudiesPage.tsx): `frontend/src/features/studies/StudiesPage.tsx`
- [Study detail view](https://github.com/yash-ranjan-124/ultrasound_automation/blob/master/frontend/src/features/studies/StudyDetailPage.tsx): `frontend/src/features/studies/StudyDetailPage.tsx`
- [Study layout](https://github.com/yash-ranjan-124/ultrasound_automation/blob/master/frontend/src/features/studies/StudyLayout.tsx): `frontend/src/features/studies/StudyLayout.tsx`
- [Study formatting](https://github.com/yash-ranjan-124/ultrasound_automation/blob/master/frontend/src/features/studies/study-format.ts): `frontend/src/features/studies/study-format.ts`
- [Study queries](https://github.com/yash-ranjan-124/ultrasound_automation/blob/master/frontend/src/hooks/use-studies.ts): `frontend/src/hooks/use-studies.ts`
- [Study API client](https://github.com/yash-ranjan-124/ultrasound_automation/blob/master/frontend/src/api/studies.ts): `frontend/src/api/studies.ts`
- [Study response types](https://github.com/yash-ranjan-124/ultrasound_automation/blob/master/frontend/src/types/study.ts): `frontend/src/types/study.ts`
- [Health API client](https://github.com/yash-ranjan-124/ultrasound_automation/blob/master/frontend/src/api/health.ts): `frontend/src/api/health.ts`
- [Ultrasound tracking](https://github.com/yash-ranjan-124/ultrasound_automation/blob/master/frontend/src/app/App.tsx): `frontend/src/app/App.tsx`
- [Brain MRI segmentation](https://github.com/yash-ranjan-124/ultrasound_automation/blob/master/frontend/src/app/App.tsx): `frontend/src/app/App.tsx`
- [Lung CT detection](https://github.com/yash-ranjan-124/ultrasound_automation/blob/master/frontend/src/app/App.tsx): `frontend/src/app/App.tsx`

### API and application

- [FastAPI application](https://github.com/yash-ranjan-124/ultrasound_automation/blob/master/backend/src/medvision/main.py): `backend/src/medvision/main.py`
- [Health endpoint](https://github.com/yash-ranjan-124/ultrasound_automation/blob/master/backend/src/medvision/api/routers/health.py): `backend/src/medvision/api/routers/health.py`
- [Study endpoints](https://github.com/yash-ranjan-124/ultrasound_automation/blob/master/backend/src/medvision/api/routers/studies.py): `backend/src/medvision/api/routers/studies.py`
- [Study ingestion](https://github.com/yash-ranjan-124/ultrasound_automation/blob/master/backend/src/medvision/application/services/create_study.py): `backend/src/medvision/application/services/create_study.py`
- [Study catalog service](https://github.com/yash-ranjan-124/ultrasound_automation/blob/master/backend/src/medvision/application/services/study_catalog.py): `backend/src/medvision/application/services/study_catalog.py`

### Study domain

- [Imaging study records](https://github.com/yash-ranjan-124/ultrasound_automation/blob/master/backend/src/medvision/domain/entities/__init__.py): `backend/src/medvision/domain/entities/__init__.py`
- [Study types and modalities](https://github.com/yash-ranjan-124/ultrasound_automation/blob/master/backend/src/medvision/domain/enums/__init__.py): `backend/src/medvision/domain/enums/__init__.py`

### Persistence and files

- [Technical metadata reader](https://github.com/yash-ranjan-124/ultrasound_automation/blob/master/backend/src/medvision/infrastructure/imaging/metadata.py): `backend/src/medvision/infrastructure/imaging/metadata.py`
- [Local file storage](https://github.com/yash-ranjan-124/ultrasound_automation/blob/master/backend/src/medvision/infrastructure/storage/local_file.py): `backend/src/medvision/infrastructure/storage/local_file.py`
- [SQL study repository](https://github.com/yash-ranjan-124/ultrasound_automation/blob/master/backend/src/medvision/infrastructure/persistence/sqlalchemy_repository.py): `backend/src/medvision/infrastructure/persistence/sqlalchemy_repository.py`
- [Database study models](https://github.com/yash-ranjan-124/ultrasound_automation/blob/master/backend/src/medvision/infrastructure/persistence/models.py): `backend/src/medvision/infrastructure/persistence/models.py`
- **PostgreSQL**

### Other components

- **Research user**

## Connections

- Research user → Browser workstation: uses (evidence: `frontend/src/main.tsx`)
- Browser workstation → Overview and roadmap: routes to (evidence: `frontend/src/main.tsx`)
- Browser workstation → Study catalog view: routes to (evidence: `frontend/src/main.tsx`)
- Browser workstation → Study detail view: routes to (evidence: `frontend/src/main.tsx`)
- Overview and roadmap → Workflow cards: renders (evidence: `frontend/src/app/App.tsx`)
- Overview and roadmap → Service status: renders (evidence: `frontend/src/app/App.tsx`)
- Service status → Health query: queries (evidence: `frontend/src/components/ServiceStatus.tsx`)
- Health query → Health API client: calls (evidence: `frontend/src/hooks/use-health-status.ts`)
- Study catalog view → Study queries: queries (evidence: `frontend/src/features/studies/StudiesPage.tsx`)
- Study detail view → Study queries: queries (evidence: `frontend/src/features/studies/StudyDetailPage.tsx`)
- Study catalog view → Study layout: renders (evidence: `frontend/src/features/studies/StudiesPage.tsx`)
- Study detail view → Study layout: renders (evidence: `frontend/src/features/studies/StudyDetailPage.tsx`)
- Study catalog view → Study formatting: formats (evidence: `frontend/src/features/studies/StudiesPage.tsx`)
- Study detail view → Study formatting: formats (evidence: `frontend/src/features/studies/StudyDetailPage.tsx`)
- Study queries → Study API client: calls (evidence: `frontend/src/hooks/use-studies.ts`)
- Study API client → Study response types: uses (evidence: `frontend/src/api/studies.ts`)
- Study formatting → Study response types: uses (evidence: `frontend/src/features/studies/study-format.ts`)
- Health API client → Health endpoint: requests health
- Study API client → Study endpoints: requests studies
- FastAPI application → Health endpoint: registers (evidence: `backend/src/medvision/main.py`)
- FastAPI application → Study endpoints: registers (evidence: `backend/src/medvision/main.py`)
- Study endpoints → Study ingestion: invokes (evidence: `backend/src/medvision/api/routers/studies.py`)
- Study endpoints → Study catalog service: invokes (evidence: `backend/src/medvision/api/routers/studies.py`)
- FastAPI application → Study ingestion: configures (evidence: `backend/src/medvision/main.py`)
- FastAPI application → Study catalog service: configures (evidence: `backend/src/medvision/main.py`)
- Study ingestion → Local file storage: saves files (evidence: `backend/src/medvision/application/services/create_study.py`)
- Study ingestion → Technical metadata reader: extracts metadata (evidence: `backend/src/medvision/application/services/create_study.py`)
- Study ingestion → SQL study repository: saves record (evidence: `backend/src/medvision/application/services/create_study.py`)
- Study ingestion → Imaging study records: creates (evidence: `backend/src/medvision/application/services/create_study.py`)
- Study ingestion → Study types and modalities: resolves type (evidence: `backend/src/medvision/application/services/create_study.py`)
- SQL study repository → Database study models: maps to (evidence: `backend/src/medvision/infrastructure/persistence/sqlalchemy_repository.py`)
- SQL study repository → PostgreSQL: reads and writes
- Workflow cards → Ultrasound tracking: presents planned (evidence: `frontend/src/app/App.tsx`)
- Workflow cards → Brain MRI segmentation: presents planned (evidence: `frontend/src/app/App.tsx`)
- Workflow cards → Lung CT detection: presents planned (evidence: `frontend/src/app/App.tsx`)
