# lus105/deepvisionxplain architecture

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

- Interactive diagram: https://gitdiagram.com/lus105/deepvisionxplain
- Repository: https://github.com/lus105/deepvisionxplain

## Overview

##### Project Type & Purpose
- This is a deep learning experimentation framework focused on comparing the explainability of CNNs (using Class Activation Maps) with Vision Transformers (using attention rollout).
- It leverages PyTorch (and PyTorch Lightning), Hydra (for configuration management), and various MLOps/logging tools (e.g., WandB, MLflow) to facilitate training, evaluation, and experimentation.
- The README indicates that this project builds upon the DeepTrainer framework, modifying ViT and CNN architectures for explainability studies.

##### Analyzing the File Structure
- The top-level directories and files provide clear insights:
- The “configs” directory contains extensive configuration files:
- Callbacks, data configs, experiment configs, debug settings, hyperparameter search, logger setups, model specifications, and trainer configurations.
- This signals a strong emphasis on flexibility and reproducibility using Hydra-based configuration.
- The “src” directory is where the main code lives:
- Under “src/data”, you have modules for data loading (datamodules, datasets, preprocessing pipelines).
- Under “src/models”, you have model definition and components for both CNN and ViT architectures, including explainability-specific modifications.
- “src/train.py” and “src/eval.py” are core to executing training and evaluation routines.
- Additional directories like “notebooks” (interactive experiments and demonstration notebooks), “scripts” (for evaluations and scheduling), “tests” (test cases for components) and “docs” (documentation and assets) complete the ecosystem.
- Docker and environment configuration files indicate containerization and dependency management.

##### Key Components to Illustrate
a. Configuration and Experiment Management:
- Config system (Hydra-based) with its hierarchy: callbacks, trainer configs (cpu, gpu, ddp, etc.), model definitions, and hyperparameter search.

b. Data Pipeline:
- Data ingestion & preprocessing workflows are encapsulated in “src/data”.
- Split out “Data Module” which includes custom dataset components, label parsing, and preprocessing strategies.

c. Model Modules:
- Divide into two submodules: one for CNN (with its modifications for CAM explainability) and one for ViT (with attention rollout).
- Inside each, include the model definition and any explainability components.
- That these modules are accessed during both training and evaluation.

d. Training / Evaluation Engine:
- Primary executables: “src/train.py” for training routines and “src/eval.py” for evaluation/inference.
- Integration with PyTorch Lightning if applicable.
- This engine to both the configuration system and the model modules.

e. Logging & MLOps:
- External logging/instrumentation tools (WandB, Comet, Tensorboard, etc.) which are configured under “configs/logger”.
- Elements as external services with two-way interactions (upload training logs, experiment metrics, model checkpoints).

f. External Tools & Deployment:
- Docker, Conda environments, and CI/CD pipeline (GitHub Actions under .github/workflows) as supporting infrastructure.
- “Notebooks” as separate interactive components that demonstrate how to download, infer, and convert models.

g. Testing:

##### Architectural Patterns & Data Flow
- Separation of concerns:
- The configuration layer (Hydra) decouples the experiment specifications from code logic.
- Data processing and model components are modular so that various pipelines can plug into different experiments.
- Training and evaluation modules are designed to work with multiple settings (trainer types, hyperparameter search, etc.).
- Configuration → Data Pipeline & Model Modules
- Data Pipeline & Model Modules → Training Engine
- Training Engine <→ Logging & Callbacks (feedback loop)
- Training Engine → Evaluation Module → External Outputs (e.g., notebooks, logs)

##### Final Advice
- Directional flow: from configuration to data to models to training/evaluation, and finally to external logging and inference.
- Don’t hesitate to break down modules (such as the Data Module and Model Module) further into sub-components if needed.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Level 1: Configuration Manager
    A["Configuration Manager (Hydra Configs)"]:::config

    %% Level 2: Data Pipeline and Model Modules
    B["Data Pipeline (src/data)"]:::pipeline
    subgraph "Model Modules"
        C1["CNN Module (CAM)"]:::model
        C2["ViT Module (Attention Rollout)"]:::model
    end

    %% Level 3: Training Engine
    D["Training Engine (src/train.py)"]:::engine

    %% Level 4: Evaluation Module and Logging & Callbacks
    E["Evaluation Module (src/eval.py & Notebooks)"]:::evaluation
    F["Logging & Callbacks"]:::logging

    %% Level 5: External Tools & Deployment and Testing Suite
    G["External Tools & Deployment"]:::external
    H["Testing Suite"]:::testing

    %% Connections from Configuration Manager
    A -->|"feeds"| B
    A -->|"feeds"| C1
    A -->|"feeds"| C2
    A -->|"configures"| D
    A -->|"configures"| F
    A -->|"validated by"| H

    %% Data Pipeline to Training Engine
    B -->|"provides data"| D

    %% Model Modules to Training Engine
    C1 -->|"model input"| D
    C2 -->|"model input"| D

    %% Training Engine to Evaluation Module and Logging & Callbacks
    D -->|"triggers"| E
    D <-->|"communicates"| F

    %% Evaluation Module to External Tools
    E -->|"outputs to"| G
    F -->|"integrates with"| G

    %% Testing Suite interaction
    H -->|"verifies"| A

    %% Click Events
    click A "https://github.com/lus105/deepvisionxplain/tree/main/configs/"
    click B "https://github.com/lus105/deepvisionxplain/tree/main/src/data/"
    click C1 "https://github.com/lus105/deepvisionxplain/blob/main/src/models/components/cnn_cam_multihead.py"
    click C2 "https://github.com/lus105/deepvisionxplain/blob/main/src/models/components/vit_rollout_multihead.py"
    click D "https://github.com/lus105/deepvisionxplain/blob/main/src/train.py"
    click E "https://github.com/lus105/deepvisionxplain/blob/main/src/eval.py"
    click F "https://github.com/lus105/deepvisionxplain/tree/main/configs/logger/"
    click G "https://github.com/lus105/deepvisionxplain/blob/main/.github/workflows/test.yml"
    click H "https://github.com/lus105/deepvisionxplain/tree/main/tests/"

    %% Styles
    classDef config fill:#f9c,stroke:#333,stroke-width:2px;
    classDef pipeline fill:#ccf,stroke:#333,stroke-width:2px;
    classDef model fill:#cfc,stroke:#333,stroke-width:2px;
    classDef engine fill:#fc9,stroke:#333,stroke-width:2px;
    classDef evaluation fill:#cff,stroke:#333,stroke-width:2px;
    classDef logging fill:#ff9,stroke:#333,stroke-width:2px;
    classDef external fill:#efe,stroke:#333,stroke-width:2px;
    classDef testing fill:#fcc,stroke:#333,stroke-width:2px;
```
