# mfazrinizar/clc-yolo architecture

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

- Interactive diagram: https://gitdiagram.com/mfazrinizar/clc-yolo
- Repository: https://github.com/mfazrinizar/clc-yolo

## Overview

CLC-YOLO is a research and reproduction package for breast-ultrasound lesion segmentation. The main workflow converts author-provided datasets into image, label, and exact-mask assets; materializes leakage-aware grouped folds; trains baseline or prototype-refinement variants; predicts masks; and evaluates image-level and group-macro results. Its model layer extends YOLO26 prototype features with local-contrast and other registered modules, with optional image-presence supervision. The README documents additional evaluation and ablation capabilities. Some wiring is only described in the README, so uncertain internal call edges are omitted.

Main entry points: [`scripts/clc.py`](https://github.com/mfazrinizar/clc-yolo/blob/main/scripts/clc.py) (Experiment CLI), [`src/breast_lesion_seg/models/registry.py`](https://github.com/mfazrinizar/clc-yolo/blob/main/src/breast_lesion_seg/models/registry.py) (Custom layer registration), [`src/breast_lesion_seg/models/trainer.py`](https://github.com/mfazrinizar/clc-yolo/blob/main/src/breast_lesion_seg/models/trainer.py) (Training integration), [`src/breast_lesion_seg/evaluation/exact_masks.py`](https://github.com/mfazrinizar/clc-yolo/blob/main/src/breast_lesion_seg/evaluation/exact_masks.py) (Exact-mask evaluation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Data preparation"]
  node_conversion["Dataset conversion<br/>[convert.py]"]
  node_busbra["BUS-BRA handling<br/>[busbra.py]"]
  node_folds["Grouped folds"]
  node_development["Inner development split<br/>[development.py]"]
  node_fold_specs["Frozen fold specs"]
end

subgraph group_model["Model and training"]
  node_model_config["Model definitions"]
  node_registration["Custom layer registration<br/>[registry.py]"]
  node_proto_refinement["Prototype refinement"]
  node_prototype_heads["Prototype heads<br/>[p2_proto.py]"]
  node_presence_loss["Presence supervision<br/>[presence_loss.py]"]
  node_trainer["Training integration<br/>[trainer.py]"]
end

subgraph group_inference["Inference and evaluation"]
  node_prediction["Prediction outputs"]
  node_exact_eval["Exact-mask evaluation<br/>[exact_masks.py]"]
  node_presence_eval["Presence diagnostics<br/>[presence_gate.py]"]
  node_seg_metrics["Segmentation metrics<br/>[segmentation.py]"]
  node_group_metrics["Group-macro aggregation<br/>[grouped.py]"]
  node_aggregate_cli["Metrics aggregator<br/>[aggregate.py]"]
end

subgraph group_results["Results and configuration"]
  node_run_configs["Run configurations"]
  node_reported_results["Fold and primary results"]
end

node_researcher(("Researcher"))
node_source_data["Source datasets"]
node_cli["Experiment CLI<br/>[clc.py]"]
node_initial_weights["YOLO initializer"]

node_researcher -->|"runs commands"| node_cli
node_source_data -->|"provides archives"| node_conversion
node_cli -->|"converts datasets"| node_conversion
node_cli -->|"handles BUS-BRA"| node_busbra
node_conversion -->|"prepares samples"| node_folds
node_folds -->|"records partitions"| node_fold_specs
node_fold_specs -->|"guides fold runs"| node_cli
node_cli -->|"creates inner splits"| node_development
node_run_configs -->|"supplies run settings"| node_cli
node_model_config -->|"names custom layers"| node_registration
node_registration -->|"registers layers"| node_proto_refinement
node_registration -->|"registers heads"| node_prototype_heads
node_cli -->|"starts training"| node_trainer
node_trainer -->|"uses registered layers"| node_registration
node_trainer -.->|"uses presence criterion"| node_presence_loss
node_initial_weights -->|"initializes model"| node_trainer
node_cli -->|"writes predictions"| node_prediction
node_cli -->|"runs exact evaluation"| node_exact_eval
node_exact_eval -->|"computes image scores"| node_seg_metrics
node_cli -.->|"runs gate diagnostics"| node_presence_eval
node_cli -->|"aggregates fold scores"| node_aggregate_cli
node_aggregate_cli -->|"computes group means"| node_group_metrics
node_aggregate_cli -->|"writes aggregate results"| node_reported_results
node_exact_eval -->|"writes fold metrics"| node_reported_results

click node_cli "https://github.com/mfazrinizar/clc-yolo/blob/main/scripts/clc.py"
click node_conversion "https://github.com/mfazrinizar/clc-yolo/blob/main/src/breast_lesion_seg/data/convert.py"
click node_busbra "https://github.com/mfazrinizar/clc-yolo/blob/main/src/breast_lesion_seg/data/busbra.py"
click node_folds "https://github.com/mfazrinizar/clc-yolo/blob/main/src/breast_lesion_seg/data/cross_validation.py"
click node_development "https://github.com/mfazrinizar/clc-yolo/blob/main/src/breast_lesion_seg/data/development.py"
click node_fold_specs "https://github.com/mfazrinizar/clc-yolo/tree/main/splits"
click node_run_configs "https://github.com/mfazrinizar/clc-yolo/tree/main/configs/runs"
click node_model_config "https://github.com/mfazrinizar/clc-yolo/tree/main/configs/models"
click node_registration "https://github.com/mfazrinizar/clc-yolo/blob/main/src/breast_lesion_seg/models/registry.py"
click node_proto_refinement "https://github.com/mfazrinizar/clc-yolo/blob/main/src/breast_lesion_seg/models/components/local_contrast_proto.py"
click node_prototype_heads "https://github.com/mfazrinizar/clc-yolo/blob/main/src/breast_lesion_seg/models/components/p2_proto.py"
click node_presence_loss "https://github.com/mfazrinizar/clc-yolo/blob/main/src/breast_lesion_seg/models/presence_loss.py"
click node_trainer "https://github.com/mfazrinizar/clc-yolo/blob/main/src/breast_lesion_seg/models/trainer.py"
click node_exact_eval "https://github.com/mfazrinizar/clc-yolo/blob/main/src/breast_lesion_seg/evaluation/exact_masks.py"
click node_presence_eval "https://github.com/mfazrinizar/clc-yolo/blob/main/src/breast_lesion_seg/evaluation/presence_gate.py"
click node_seg_metrics "https://github.com/mfazrinizar/clc-yolo/blob/main/src/breast_lesion_seg/metrics/segmentation.py"
click node_group_metrics "https://github.com/mfazrinizar/clc-yolo/blob/main/src/breast_lesion_seg/metrics/grouped.py"
click node_aggregate_cli "https://github.com/mfazrinizar/clc-yolo/blob/main/scripts/aggregate.py"
click node_reported_results "https://github.com/mfazrinizar/clc-yolo/tree/main/results"

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_conversion,node_busbra,node_folds,node_development,node_fold_specs toneBlue
class node_model_config,node_registration,node_proto_refinement,node_prototype_heads,node_presence_loss,node_trainer toneAmber
class node_prediction,node_exact_eval,node_presence_eval,node_seg_metrics,node_group_metrics,node_aggregate_cli toneMint
class node_run_configs,node_reported_results toneRose
class node_researcher,node_source_data,node_initial_weights toneIndigo
class node_cli toneTeal
```

## Components

### Data preparation

- [Dataset conversion](https://github.com/mfazrinizar/clc-yolo/blob/main/src/breast_lesion_seg/data/convert.py): `src/breast_lesion_seg/data/convert.py`
- [BUS-BRA handling](https://github.com/mfazrinizar/clc-yolo/blob/main/src/breast_lesion_seg/data/busbra.py): `src/breast_lesion_seg/data/busbra.py`
- [Grouped folds](https://github.com/mfazrinizar/clc-yolo/blob/main/src/breast_lesion_seg/data/cross_validation.py): `src/breast_lesion_seg/data/cross_validation.py`
- [Inner development split](https://github.com/mfazrinizar/clc-yolo/blob/main/src/breast_lesion_seg/data/development.py): `src/breast_lesion_seg/data/development.py`
- [Frozen fold specs](https://github.com/mfazrinizar/clc-yolo/tree/main/splits): `splits`

### Model and training

- [Model definitions](https://github.com/mfazrinizar/clc-yolo/tree/main/configs/models): `configs/models`
- [Custom layer registration](https://github.com/mfazrinizar/clc-yolo/blob/main/src/breast_lesion_seg/models/registry.py): `src/breast_lesion_seg/models/registry.py`
- [Prototype refinement](https://github.com/mfazrinizar/clc-yolo/blob/main/src/breast_lesion_seg/models/components/local_contrast_proto.py): `src/breast_lesion_seg/models/components/local_contrast_proto.py`
- [Prototype heads](https://github.com/mfazrinizar/clc-yolo/blob/main/src/breast_lesion_seg/models/components/p2_proto.py): `src/breast_lesion_seg/models/components/p2_proto.py`
- [Presence supervision](https://github.com/mfazrinizar/clc-yolo/blob/main/src/breast_lesion_seg/models/presence_loss.py): `src/breast_lesion_seg/models/presence_loss.py`
- [Training integration](https://github.com/mfazrinizar/clc-yolo/blob/main/src/breast_lesion_seg/models/trainer.py): `src/breast_lesion_seg/models/trainer.py`

### Inference and evaluation

- **Prediction outputs**
- [Exact-mask evaluation](https://github.com/mfazrinizar/clc-yolo/blob/main/src/breast_lesion_seg/evaluation/exact_masks.py): `src/breast_lesion_seg/evaluation/exact_masks.py`
- [Presence diagnostics](https://github.com/mfazrinizar/clc-yolo/blob/main/src/breast_lesion_seg/evaluation/presence_gate.py): `src/breast_lesion_seg/evaluation/presence_gate.py`
- [Segmentation metrics](https://github.com/mfazrinizar/clc-yolo/blob/main/src/breast_lesion_seg/metrics/segmentation.py): `src/breast_lesion_seg/metrics/segmentation.py`
- [Group-macro aggregation](https://github.com/mfazrinizar/clc-yolo/blob/main/src/breast_lesion_seg/metrics/grouped.py): `src/breast_lesion_seg/metrics/grouped.py`
- [Metrics aggregator](https://github.com/mfazrinizar/clc-yolo/blob/main/scripts/aggregate.py): `scripts/aggregate.py`

### Results and configuration

- [Run configurations](https://github.com/mfazrinizar/clc-yolo/tree/main/configs/runs): `configs/runs`
- [Fold and primary results](https://github.com/mfazrinizar/clc-yolo/tree/main/results): `results`

### Other components

- **Researcher**
- **Source datasets**
- [Experiment CLI](https://github.com/mfazrinizar/clc-yolo/blob/main/scripts/clc.py): `scripts/clc.py`
- **YOLO initializer**

## Connections

- Researcher → Experiment CLI: runs commands
- Source datasets → Dataset conversion: provides archives
- Experiment CLI → Dataset conversion: converts datasets
- Experiment CLI → BUS-BRA handling: handles BUS-BRA
- Dataset conversion → Grouped folds: prepares samples
- Grouped folds → Frozen fold specs: records partitions
- Frozen fold specs → Experiment CLI: guides fold runs
- Experiment CLI → Inner development split: creates inner splits
- Run configurations → Experiment CLI: supplies run settings
- Model definitions → Custom layer registration: names custom layers
- Custom layer registration → Prototype refinement: registers layers
- Custom layer registration → Prototype heads: registers heads
- Experiment CLI → Training integration: starts training
- Training integration → Custom layer registration: uses registered layers
- Training integration → Presence supervision: uses presence criterion
- YOLO initializer → Training integration: initializes model
- Experiment CLI → Prediction outputs: writes predictions
- Experiment CLI → Exact-mask evaluation: runs exact evaluation
- Exact-mask evaluation → Segmentation metrics: computes image scores
- Experiment CLI → Presence diagnostics: runs gate diagnostics
- Experiment CLI → Metrics aggregator: aggregates fold scores
- Metrics aggregator → Group-macro aggregation: computes group means
- Metrics aggregator → Fold and primary results: writes aggregate results
- Exact-mask evaluation → Fold and primary results: writes fold metrics