# ga4gh/ga4gh_workflow_clinic_gsoc_2026 architecture

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

- Interactive diagram: https://gitdiagram.com/ga4gh/ga4gh_workflow_clinic_gsoc_2026
- Repository: https://github.com/ga4gh/ga4gh_workflow_clinic_gsoc_2026

## Overview

Workflow Clinic analyzes scientific workflow files by parsing them into a language-neutral WorkflowBundle, running portability rules and optional AI review, then producing a diagnosis report. A separate repair command loads findings and delegates proposed fixes to the Doctor cascade; publishing can turn findings into GitHub issues. The README also describes Snakemake support and metadata/structure validation as planned capabilities, but the supplied tree currently shows a Nextflow parser and only some rule implementations. Edges reflect the README or SOURCE INDEX references; unsampled implementation details are not assumed.

Main entry points: [`src/workflow_clinic/services/coordinator.py`](https://github.com/ga4gh/ga4gh_workflow_clinic_gsoc_2026/blob/main/src/workflow_clinic/services/coordinator.py) (Examine Coordinator), [`src/workflow_clinic/cli.py`](https://github.com/ga4gh/ga4gh_workflow_clinic_gsoc_2026/blob/main/src/workflow_clinic/cli.py) (CLI Commands), [`src/workflow_clinic/critic/agent.py`](https://github.com/ga4gh/ga4gh_workflow_clinic_gsoc_2026/blob/main/src/workflow_clinic/critic/agent.py) (AI Critic), [`src/workflow_clinic/services/fix_coordinator.py`](https://github.com/ga4gh/ga4gh_workflow_clinic_gsoc_2026/blob/main/src/workflow_clinic/services/fix_coordinator.py) (Fix Coordinator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["CLI and Coordination"]
  node_cli["CLI Commands<br/>[cli.py]"]
  node_examine["Examine Coordinator<br/>[coordinator.py]"]
  node_fix_coord["Fix Coordinator<br/>[fix_coordinator.py]"]
end

subgraph group_analysis["Workflow Analysis"]
  node_parser["Parser Registry<br/>[registry.py]"]
  node_nextflow["Nextflow Parser<br/>[nextflow.py]"]
  node_bundle["WorkflowBundle<br/>[workflow_bundle.py]"]
  node_rules["Rule Engine"]
  node_diagnosis["Diagnosis Models<br/>[diagnosis.py]"]
  node_diagnosis_file["Diagnosis Report<br/>[diagnosis.py]"]
end

subgraph group_review["AI Review"]
  node_critic["AI Critic<br/>[agent.py]"]
  node_knowledge["Remediation Knowledge<br/>[retriever.py]"]
  node_llm["LLM Utilities<br/>[llm.py]"]
end

subgraph group_repair["Repair"]
  node_doctor["Doctor Runner<br/>[runner.py]"]
  node_fixers["Fixer Strategies"]
  node_patcher["File Patcher<br/>[patcher.py]"]
  node_fix_models["Fix Proposals<br/>[fix.py]"]
end

subgraph group_publish["Reporting"]
  node_publisher_coord["Publish Coordinator"]
  node_issue_generator["Issue Generator<br/>[issue_generator.py]"]
  node_github_publisher["GitHub Publisher"]
end

node_author(("Workflow Author"))
node_model_provider{{"LLM Provider"}}
node_github{{"GitHub"}}

node_author -->|"runs commands"| node_cli
node_cli -->|"starts examination"| node_examine
node_cli -->|"starts repair"| node_fix_coord
node_cli -->|"starts publishing"| node_publisher_coord
node_examine -->|"selects parser"| node_parser
node_parser -.->|"dispatches parsing"| node_nextflow
node_nextflow -->|"builds model"| node_bundle
node_examine -->|"analyzes workflow"| node_bundle
node_examine -->|"runs rules"| node_rules
node_examine -->|"runs optional audit"| node_critic
node_critic -->|"retrieves guidance"| node_knowledge
node_critic -->|"uses model utilities"| node_llm
node_llm -.->|"resolves provider"| node_model_provider
node_critic -->|"enriches findings"| node_diagnosis
node_examine -->|"builds report"| node_diagnosis
node_examine -->|"saves report"| node_diagnosis_file
node_fix_coord -->|"loads findings"| node_diagnosis_file
node_fix_coord -->|"runs cascade"| node_doctor
node_doctor -->|"selects strategies"| node_fixers
node_doctor -->|"records proposals"| node_fix_models
node_fixers -.->|"may delegate patching"| node_patcher
node_publisher_coord -->|"generates issues"| node_issue_generator
node_publisher_coord -->|"publishes issues"| node_github_publisher
node_github_publisher -->|"uses issue payloads"| node_issue_generator
node_github_publisher -->|"creates issues"| node_github

click node_cli "https://github.com/ga4gh/ga4gh_workflow_clinic_gsoc_2026/blob/main/src/workflow_clinic/cli.py"
click node_examine "https://github.com/ga4gh/ga4gh_workflow_clinic_gsoc_2026/blob/main/src/workflow_clinic/services/coordinator.py"
click node_fix_coord "https://github.com/ga4gh/ga4gh_workflow_clinic_gsoc_2026/blob/main/src/workflow_clinic/services/fix_coordinator.py"
click node_parser "https://github.com/ga4gh/ga4gh_workflow_clinic_gsoc_2026/blob/main/src/workflow_clinic/parsers/registry.py"
click node_nextflow "https://github.com/ga4gh/ga4gh_workflow_clinic_gsoc_2026/blob/main/src/workflow_clinic/parsers/nextflow.py"
click node_bundle "https://github.com/ga4gh/ga4gh_workflow_clinic_gsoc_2026/blob/main/src/workflow_clinic/models/workflow_bundle.py"
click node_rules "https://github.com/ga4gh/ga4gh_workflow_clinic_gsoc_2026/tree/main/src/workflow_clinic/rules"
click node_diagnosis "https://github.com/ga4gh/ga4gh_workflow_clinic_gsoc_2026/blob/main/src/workflow_clinic/models/diagnosis.py"
click node_critic "https://github.com/ga4gh/ga4gh_workflow_clinic_gsoc_2026/blob/main/src/workflow_clinic/critic/agent.py"
click node_knowledge "https://github.com/ga4gh/ga4gh_workflow_clinic_gsoc_2026/blob/main/src/workflow_clinic/advisor/retriever.py"
click node_llm "https://github.com/ga4gh/ga4gh_workflow_clinic_gsoc_2026/blob/main/src/workflow_clinic/utils/llm.py"
click node_diagnosis_file "https://github.com/ga4gh/ga4gh_workflow_clinic_gsoc_2026/blob/main/src/workflow_clinic/models/diagnosis.py"
click node_doctor "https://github.com/ga4gh/ga4gh_workflow_clinic_gsoc_2026/blob/main/src/workflow_clinic/doctor/runner.py"
click node_fixers "https://github.com/ga4gh/ga4gh_workflow_clinic_gsoc_2026/tree/main/src/workflow_clinic/doctor/fixers"
click node_patcher "https://github.com/ga4gh/ga4gh_workflow_clinic_gsoc_2026/blob/main/src/workflow_clinic/doctor/patcher.py"
click node_fix_models "https://github.com/ga4gh/ga4gh_workflow_clinic_gsoc_2026/blob/main/src/workflow_clinic/models/fix.py"
click node_publisher_coord "https://github.com/ga4gh/ga4gh_workflow_clinic_gsoc_2026/blob/main/src/workflow_clinic/services/publish_coordinator.py"
click node_issue_generator "https://github.com/ga4gh/ga4gh_workflow_clinic_gsoc_2026/blob/main/src/workflow_clinic/reporting/issue_generator.py"
click node_github_publisher "https://github.com/ga4gh/ga4gh_workflow_clinic_gsoc_2026/blob/main/src/workflow_clinic/reporting/github_publisher.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_cli,node_examine,node_fix_coord toneBlue
class node_parser,node_nextflow,node_bundle,node_rules,node_diagnosis,node_diagnosis_file toneAmber
class node_critic,node_knowledge,node_llm toneMint
class node_doctor,node_fixers,node_patcher,node_fix_models toneRose
class node_publisher_coord,node_issue_generator,node_github_publisher,node_author,node_model_provider,node_github toneIndigo
```

## Components

### CLI and Coordination

- [CLI Commands](https://github.com/ga4gh/ga4gh_workflow_clinic_gsoc_2026/blob/main/src/workflow_clinic/cli.py): `src/workflow_clinic/cli.py`
- [Examine Coordinator](https://github.com/ga4gh/ga4gh_workflow_clinic_gsoc_2026/blob/main/src/workflow_clinic/services/coordinator.py): `src/workflow_clinic/services/coordinator.py`
- [Fix Coordinator](https://github.com/ga4gh/ga4gh_workflow_clinic_gsoc_2026/blob/main/src/workflow_clinic/services/fix_coordinator.py): `src/workflow_clinic/services/fix_coordinator.py`

### Workflow Analysis

- [Parser Registry](https://github.com/ga4gh/ga4gh_workflow_clinic_gsoc_2026/blob/main/src/workflow_clinic/parsers/registry.py): `src/workflow_clinic/parsers/registry.py`
- [Nextflow Parser](https://github.com/ga4gh/ga4gh_workflow_clinic_gsoc_2026/blob/main/src/workflow_clinic/parsers/nextflow.py): `src/workflow_clinic/parsers/nextflow.py`
- [WorkflowBundle](https://github.com/ga4gh/ga4gh_workflow_clinic_gsoc_2026/blob/main/src/workflow_clinic/models/workflow_bundle.py): `src/workflow_clinic/models/workflow_bundle.py`
- [Rule Engine](https://github.com/ga4gh/ga4gh_workflow_clinic_gsoc_2026/tree/main/src/workflow_clinic/rules): `src/workflow_clinic/rules`
- [Diagnosis Models](https://github.com/ga4gh/ga4gh_workflow_clinic_gsoc_2026/blob/main/src/workflow_clinic/models/diagnosis.py): `src/workflow_clinic/models/diagnosis.py`
- [Diagnosis Report](https://github.com/ga4gh/ga4gh_workflow_clinic_gsoc_2026/blob/main/src/workflow_clinic/models/diagnosis.py): `src/workflow_clinic/models/diagnosis.py`

### AI Review

- [AI Critic](https://github.com/ga4gh/ga4gh_workflow_clinic_gsoc_2026/blob/main/src/workflow_clinic/critic/agent.py): `src/workflow_clinic/critic/agent.py`
- [Remediation Knowledge](https://github.com/ga4gh/ga4gh_workflow_clinic_gsoc_2026/blob/main/src/workflow_clinic/advisor/retriever.py): `src/workflow_clinic/advisor/retriever.py`
- [LLM Utilities](https://github.com/ga4gh/ga4gh_workflow_clinic_gsoc_2026/blob/main/src/workflow_clinic/utils/llm.py): `src/workflow_clinic/utils/llm.py`

### Repair

- [Doctor Runner](https://github.com/ga4gh/ga4gh_workflow_clinic_gsoc_2026/blob/main/src/workflow_clinic/doctor/runner.py): `src/workflow_clinic/doctor/runner.py`
- [Fixer Strategies](https://github.com/ga4gh/ga4gh_workflow_clinic_gsoc_2026/tree/main/src/workflow_clinic/doctor/fixers): `src/workflow_clinic/doctor/fixers`
- [File Patcher](https://github.com/ga4gh/ga4gh_workflow_clinic_gsoc_2026/blob/main/src/workflow_clinic/doctor/patcher.py): `src/workflow_clinic/doctor/patcher.py`
- [Fix Proposals](https://github.com/ga4gh/ga4gh_workflow_clinic_gsoc_2026/blob/main/src/workflow_clinic/models/fix.py): `src/workflow_clinic/models/fix.py`

### Reporting

- [Publish Coordinator](https://github.com/ga4gh/ga4gh_workflow_clinic_gsoc_2026/blob/main/src/workflow_clinic/services/publish_coordinator.py): `src/workflow_clinic/services/publish_coordinator.py`
- [Issue Generator](https://github.com/ga4gh/ga4gh_workflow_clinic_gsoc_2026/blob/main/src/workflow_clinic/reporting/issue_generator.py): `src/workflow_clinic/reporting/issue_generator.py`
- [GitHub Publisher](https://github.com/ga4gh/ga4gh_workflow_clinic_gsoc_2026/blob/main/src/workflow_clinic/reporting/github_publisher.py): `src/workflow_clinic/reporting/github_publisher.py`

### Other components

- **Workflow Author**
- **LLM Provider**
- **GitHub**

## Connections

- Workflow Author → CLI Commands: runs commands (evidence: `README.md`)
- CLI Commands → Examine Coordinator: starts examination (evidence: `src/workflow_clinic/cli.py`)
- CLI Commands → Fix Coordinator: starts repair (evidence: `src/workflow_clinic/cli.py`)
- CLI Commands → Publish Coordinator: starts publishing (evidence: `src/workflow_clinic/cli.py`)
- Examine Coordinator → Parser Registry: selects parser (evidence: `src/workflow_clinic/services/coordinator.py`)
- Parser Registry → Nextflow Parser: dispatches parsing
- Nextflow Parser → WorkflowBundle: builds model (evidence: `src/workflow_clinic/parsers/nextflow.py`)
- Examine Coordinator → WorkflowBundle: analyzes workflow (evidence: `README.md`)
- Examine Coordinator → Rule Engine: runs rules (evidence: `src/workflow_clinic/services/coordinator.py`)
- Examine Coordinator → AI Critic: runs optional audit (evidence: `src/workflow_clinic/services/coordinator.py`)
- AI Critic → Remediation Knowledge: retrieves guidance (evidence: `src/workflow_clinic/critic/agent.py`)
- AI Critic → LLM Utilities: uses model utilities (evidence: `src/workflow_clinic/critic/agent.py`)
- LLM Utilities → LLM Provider: resolves provider
- AI Critic → Diagnosis Models: enriches findings (evidence: `src/workflow_clinic/critic/agent.py`)
- Examine Coordinator → Diagnosis Models: builds report (evidence: `src/workflow_clinic/services/coordinator.py`)
- Examine Coordinator → Diagnosis Report: saves report (evidence: `src/workflow_clinic/services/coordinator.py`)
- Fix Coordinator → Diagnosis Report: loads findings (evidence: `src/workflow_clinic/services/fix_coordinator.py`)
- Fix Coordinator → Doctor Runner: runs cascade (evidence: `src/workflow_clinic/services/fix_coordinator.py`)
- Doctor Runner → Fixer Strategies: selects strategies (evidence: `src/workflow_clinic/doctor/runner.py`)
- Doctor Runner → Fix Proposals: records proposals (evidence: `src/workflow_clinic/doctor/runner.py`)
- Fixer Strategies → File Patcher: may delegate patching (evidence: `src/workflow_clinic/doctor/fixers/paths.py`)
- Publish Coordinator → Issue Generator: generates issues (evidence: `src/workflow_clinic/services/publish_coordinator.py`)
- Publish Coordinator → GitHub Publisher: publishes issues (evidence: `src/workflow_clinic/services/publish_coordinator.py`)
- GitHub Publisher → Issue Generator: uses issue payloads (evidence: `src/workflow_clinic/reporting/github_publisher.py`)
- GitHub Publisher → GitHub: creates issues (evidence: `src/workflow_clinic/reporting/github_publisher.py`)
