# sushantgautam/medvqa architecture

> Architecture diagram of the GitHub repository sushantgautam/medvqa, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sushantgautam/medvqa
- Repository: https://github.com/sushantgautam/medvqa

## Overview

##### Project type and purpose
- Project type: A Python-based CLI tool with an optional Gradio web interface.
- Purpose: Facilitate validation and submission of models to the MedVQA competition (ImageCLEFmed-MEDVQA-GI-2025). It provides a consistent CLI (“medvqa validate_and_submit …”) and a demo UI via Gradio, plus GitHub workflows for packaging and deployment.

##### File structure
- Top-level scripts:
- gradio_interface.py – launches a Gradio app
- medvqa/cli.py – entry point for the `medvqa` console command
- medvqa/competitions/gi-2025/task_1.py & task_2.py – competition-specific submission logic
- medvqa/submission_samples/… – sample scripts matching organizer requirements
- Config and packaging:
- pyproject.toml – project metadata, dependencies
- .gitignore, .gitmodules
- CI/CD:
- .github/workflows/publish.yml – PyPI publishing
- .github/workflows/gradio-app-HuggingFaceSpace.yml – deploy Gradio app to HF Spaces
- README.md outlines installation, usage, and links to competition repo.

##### README for additional insights
- Confirms CLI command and parameters (`--competition`, `--task`, `--repo_id`)
- Points to Gradio SDK config for Spaces deployment
- Emphasizes extensibility via competition modules

a. Main components
- User Interfaces
– CLI (shell)
– Gradio Web UI
- Core Library
– medvqa package (CLI handler, shared utilities)
- Competition Modules
– GI-2025 Task 1 & Task 2 logic
– Submission samples
- CI/CD Pipelines
– GitHub Actions (Publish to PyPI, Deploy to HF Spaces)
- External Services
– PyPI (package distribution)
– HuggingFace Model Hub (model repo for `repo_id`)
– HuggingFace Spaces (hosted Gradio app)
– ImageCLEFmed competition platform (validation rules)
b. Relationships and interactions
- User invokes CLI → medvqa/cli → loads competition module → validates & packages submission script → calls HF Hub API → pushes to model repo
- User opens Gradio UI → gradio_interface.py → uses medvqa core & competition modules to run inference or simulate submission → displays results
- GitHub commit → workflows trigger → publish new medvqa version to PyPI AND deploy updated Gradio app to HF Spaces
c. Architectural patterns and principles
- Modular design: core library + competition-specific plugins
- Separation of concerns: CLI logic, UI logic, competition logic
- Extensibility: additional competition folders can be added without touching core
- CI/CD automation for distribution and hosting
d. Key technologies and libraries
- Python packaging (pyproject.toml, pip)
- Click or argparse (implicit in cli.py)
- Gradio SDK (for web UI)
- GitHub Actions (CI/CD)
- HuggingFace Hub API
- Competition repo integration

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User Interfaces
    subgraph "User Interfaces"
        CLI["CLI Shell UI"]:::ui
        Gradio["Gradio Web UI"]:::ui
    end

    %% Core Library
    subgraph "Core Library"
        Core["medvqa Core Library"]:::code
    end

    %% Config & Packaging
    subgraph "Config & Packaging"
        Packaging["pyproject.toml"]:::code
    end

    %% Competition Modules
    subgraph "Competition Modules"
        PluginFolder["GI-2025 Plugin"]:::code
        Task1["Task 1 Logic"]:::code
        Task2["Task 2 Logic"]:::code
        Sample1["Sample Task1 Submission"]:::code
        Sample2["Sample Task2 Submission"]:::code
    end

    %% CI/CD Pipelines
    subgraph "CI/CD Pipelines"
        Publish["Publish to PyPI"]:::ci
        Deploy["Deploy Gradio App to HF Spaces"]:::ci
    end

    %% External Services
    subgraph "External Services"
        PyPI["PyPI"]:::ext
        HFHub["HuggingFace Hub"]:::ext
        HFSpaces["HF Spaces"]:::ext
        CompetitionPlatform["ImageCLEFmed Platform"]:::ext
    end

    %% Connections
    CLI -->|"invoke validate & submit"| Core
    Gradio -->|"launch web UI"| Core
    Core -->|uses config| Packaging
    Core -->|"loads plugin"| PluginFolder
    PluginFolder --> Task1
    PluginFolder --> Task2
    Task1 -->|"validate & package"| HFHub
    Task2 -->|"validate & package"| HFHub
    Task1 -->|"check rules"| CompetitionPlatform
    Task2 -->|"check rules"| CompetitionPlatform
    Core -->|"simulate submission"| Sample1
    Core -->|"simulate submission"| Sample2
    Core -.-> Publish
    Core -.-> Deploy
    Publish -->|"publish package"| PyPI
    Deploy -->|"deploy app"| HFSpaces

    %% Click Events
    click CLI "https://github.com/sushantgautam/medvqa/blob/main/medvqa/cli.py"
    click Gradio "https://github.com/sushantgautam/medvqa/blob/main/gradio_interface.py"
    click Core "https://github.com/sushantgautam/medvqa/blob/main/medvqa/__init__.py"
    click PluginFolder "https://github.com/sushantgautam/medvqa/tree/main/medvqa/competitions/gi-2025/"
    click Task1 "https://github.com/sushantgautam/medvqa/blob/main/medvqa/competitions/gi-2025/task_1.py"
    click Task2 "https://github.com/sushantgautam/medvqa/blob/main/medvqa/competitions/gi-2025/task_2.py"
    click Sample1 "https://github.com/sushantgautam/medvqa/blob/main/medvqa/submission_samples/gi-2025/submission_task1.py"
    click Sample2 "https://github.com/sushantgautam/medvqa/blob/main/medvqa/submission_samples/gi-2025/submission_task2.py"
    click Packaging "https://github.com/sushantgautam/medvqa/blob/main/pyproject.toml"
    click Publish "https://github.com/sushantgautam/medvqa/blob/main/.github/workflows/publish.yml"
    click Deploy "https://github.com/sushantgautam/medvqa/blob/main/.github/workflows/gradio-app-HuggingFaceSpace.yml"

    %% Styles
    classDef code fill:#D0E8FF,stroke:#4A90E2,stroke-width:1px
    classDef ui fill:#DFFFD0,stroke:#3C763D,stroke-width:1px
    classDef ci fill:#FFE0B2,stroke:#E69138,stroke-width:1px
    classDef ext fill:#F0F0F0,stroke:#999999,stroke-width:1px
```
