# alfredqin/db-sam architecture

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

- Interactive diagram: https://gitdiagram.com/alfredqin/db-sam
- Repository: https://github.com/alfredqin/db-sam

## Overview

##### Project type and purpose
- This is a research‐oriented deep learning framework (“DB‐SAM”) for universal medical image segmentation, implementing the “Dual-Branch Adapted SAM” architecture on top of Meta’s Segment Anything Model.
- It provides configuration management, model definition (ViT branch + conv branch + fusion + decoder), training loops, inference scripts, experiment scaffolding, logging integrations, and CUDA operator compilation.

##### File structure
- Top‐level:
- configs/ (Hydra-style YAML presets for data, model, trainer, callbacks, logging, experiments)
- src/ (core library: data modules, model adapters/encoders/decoders, losses, ops, training engine, utils)
- projects/ (example applications: db_sam training pipeline, inference pipeline)
- scripts/, Makefile, environment.yaml, requirements.txt, setup.py/pyproject.toml (build & deployment)
- .github/, pre-commit, CI/CD workflows
- Patterns & frameworks:
- Hydra for config composition
- PyTorch + custom CUDA ops (Deformable Attention)
- Modular model registry (registry.py)
- Accelerate & custom Trainer classes
- Logging backends pluggable via configs (wandb, mlflow, comet, etc.)

##### README for additional insights
- Confirms dual‐branch (ViT + conv) architecture, cross‐attention fusion, mask decoder
- Usage instructions emphasize environment setup, CUDA op compilation, and standard training/inference entry scripts

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% CLI Entrypoints
    subgraph "CLI Entrypoints"
        TrainCLI["Train CLI"]:::code
        InferenceCLI["Inference CLI"]:::code
        BuilderCLI["Model Builder CLI"]:::code
    end

    %% Configuration Layer
    subgraph "Configuration Layer" 
        ConfigRoot["Hydra Configs (configs/)"]:::config
        DataConfigs["Data Configs (configs/data/)"]:::config
        ModelConfigs["Model Configs (configs/model/)"]:::config
        TrainerConfigs["Trainer Configs (configs/trainer/)"]:::config
        CallbackConfigs["Callback Configs (configs/callbacks/)"]:::config
        LoggerConfigs["Logger Configs (configs/logger/)"]:::config
        ProjectExpConfigs["Project Experiment Configs (projects/db_sam/configs/)"]:::config
        InferenceConfigs["Inference Configs (projects/inference/configs/)"]:::config
    end

    %% Data Ingestion & Preprocessing
    DataModule["DataModule (src/data/)"]:::code

    %% Model Builder
    ModelBuilder["ModelBuilder"]:::code

    %% Training Engine
    Trainer["Trainer (AccelerateSGTrainer)"]:::code
    subgraph "Callbacks"
        MetricsCB["Metrics Callback"]:::code
        SummaryCB["Summary Callback"]:::code
        StageCB["Training Stage Callback"]:::code
    end

    %% Logging & Monitoring
    Logger["Logger"]:::external

    %% Artifacts
    Checkpoint["Checkpoints & Logs (logs/)"]:::external

    %% Model Library
    subgraph "Model Library"
        subgraph Encoders
            SAMEnc["SAM Encoder"]:::code
            AdaptedSAM["Adapted SAM Encoder"]:::code
        end
        subgraph "Conv Branch Adapters"
            ConvAdapter["Conv-ViT Adapter"]:::code
            MultiBranch["Multi-Branches Adapter"]:::code
        end
        Fusion["Cross-Attention Fusion"]:::code
        Decoder["Mask Decoder"]:::code

        subgraph "Transformers & Ops"
            DeformFunc["Deformable Attention Func"]:::code
            DeformModule["Deformable Attention Module"]:::code
            TwoWayTrans["Two-Way Transformer"]:::code
            PosEncoding["Position Encoding"]:::code
        end
    end

    %% Inference Pipeline
    subgraph "Inference Pipeline"
        LoadedModel["Load Checkpoint + Config"]:::code
        InferenceRun["Run Inference & Output Masks"]:::code
    end

    %% Connections
    TrainCLI -->|loads| ConfigRoot
    InferenceCLI -->|loads| InferenceConfigs
    BuilderCLI -->|loads| ModelConfigs

    ConfigRoot --> DataModule
    ConfigRoot --> ModelBuilder
    ConfigRoot --> Trainer
    ConfigRoot --> Logger

    DataModule --> Trainer
    Trainer --> ModelBuilder
    Trainer --> MetricsCB
    Trainer --> SummaryCB
    Trainer --> StageCB
    Trainer --> Logger
    Trainer --> Checkpoint

    ModelBuilder --> Encoders
    ModelBuilder --> ConvAdapter
    ModelBuilder --> Fusion
    ModelBuilder --> Decoder
    ModelBuilder --> DeformFunc
    ModelBuilder --> DeformModule
    ModelBuilder --> TwoWayTrans
    ModelBuilder --> PosEncoding

    Encoders --> Fusion
    ConvAdapter --> Fusion
    Fusion --> Decoder

    InferenceCLI --> LoadedModel
    LoadedModel --> BN{{"Model (Builder)"}}
    BN --> InferenceRun

    %% Click Events
    click TrainCLI "https://github.com/alfredqin/db-sam/blob/main/projects/db_sam/train.py"
    click InferenceCLI "https://github.com/alfredqin/db-sam/blob/main/projects/inference/sam_inference.py"
    click BuilderCLI "https://github.com/alfredqin/db-sam/blob/main/projects/db_sam/builder.py"
    click ConfigRoot "https://github.com/alfredqin/db-sam/tree/main/configs/"
    click DataConfigs "https://github.com/alfredqin/db-sam/tree/main/configs/data/"
    click ModelConfigs "https://github.com/alfredqin/db-sam/tree/main/configs/model/"
    click TrainerConfigs "https://github.com/alfredqin/db-sam/tree/main/configs/trainer/"
    click CallbackConfigs "https://github.com/alfredqin/db-sam/tree/main/configs/callbacks/"
    click LoggerConfigs "https://github.com/alfredqin/db-sam/tree/main/configs/logger/"
    click ProjectExpConfigs "https://github.com/alfredqin/db-sam/tree/main/projects/db_sam/configs/"
    click InferenceConfigs "https://github.com/alfredqin/db-sam/tree/main/projects/inference/configs/"
    click DataModule "https://github.com/alfredqin/db-sam/tree/main/src/data/"
    click SAMEnc "https://github.com/alfredqin/db-sam/blob/main/src/models/encoders/sam_encoder.py"
    click AdaptedSAM "https://github.com/alfredqin/db-sam/blob/main/src/models/encoders/adapted_sam_encoder.py"
    click ConvAdapter "https://github.com/alfredqin/db-sam/blob/main/src/models/adapters/conv_vit_adapter/adapter.py"
    click MultiBranch "https://github.com/alfredqin/db-sam/blob/main/src/models/adapters/conv_vit_adapter/multi_branches_adapter.py"
    click Fusion "https://github.com/alfredqin/db-sam/blob/main/src/models/adapters/common/interact_block.py"
    click Decoder "https://github.com/alfredqin/db-sam/blob/main/src/models/decoders/sam_mask_decoder.py"
    click DeformFunc "https://github.com/alfredqin/db-sam/blob/main/src/models/ops/ms_deform_attn/functions/ms_deform_attn_func.py"
    click DeformModule "https://github.com/alfredqin/db-sam/blob/main/src/models/ops/ms_deform_attn/modules/ms_deform_attn.py"
    click TwoWayTrans "https://github.com/alfredqin/db-sam/blob/main/src/models/transformer/twoway_transformer.py"
    click Trainer "https://github.com/alfredqin/db-sam/blob/main/src/training/trainer/accelerate_sg_trainer.py"

    %% Styles
    classDef config fill:#cce5ff,stroke:#1f77b4,color:#1f77b4
    classDef code fill:#d4edda,stroke:#2e7d32,color:#2e7d32
    classDef external fill:#e2e3e5,stroke:#6c757d,color:#6c757d
```
