# bcb-unl/run_dbcan architecture

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

- Interactive diagram: https://gitdiagram.com/bcb-unl/run_dbcan
- Repository: https://github.com/bcb-unl/run_dbcan

## Overview

##### Project Type and Purpose
- run_dbcan is a standalone bioinformatics tool for automated CAZyme annotation, as part of the dbCAN suite (currently dbCAN3). It incorporates several bioinformatics engines (HMMER, Diamond, and dbCAN_sub), and it also adds features for visualizing CAZyme gene clusters (CGCs) and substrate prediction.
- The tool is designed for processing genomic data files (like FASTA and GFF), annotating enzyme families, and creating graphical outputs.
- Key indicators from the README (e.g., usage discussion, installation instructions, and citation requirements) confirm that it is an advanced command-line tool meant for researchers in bioinformatics.

##### Analyzing the File Structure
- The top-level directory contains configuration files (e.g., .dockerignore, .editorconfig, .gitignore, etc.), Docker and environment configuration folders (docker, envs, environment.yml), and documentation (docs, README.md).
- The main source package is in the "dbcan" directory, which is structured in several sub-modules:
- IO: Handles input file operations (OverviewGenerator.py, fasta.py, gff.py).
- annotation: Contains modules applying various annotation algorithms (CGCFinder.py, cgc_substrate_prediction.py, diamond.py, pyhmmer_search.py).
- plot: Provides plotting capabilities and visualization (plot_cgc_circle.py, syntenic_plot.py).
- process: Manages processing pipelines and utility functions that execute the annotation workflow.
- utils: Houses supporting functions for database operations, diamond unassembly, and general utilities.
- Core and main modules that likely serve as the central workflow coordinator.
- The "tests" directory ensures code quality through test cases – an important architectural element to note.
- Extra directories (docker, docs, envs) imply that containerization, documentation generation, and environment management are integral to the project.

##### Architectural Components and Relationships
- Main Executable & Orchestration:
- dbcan/main.py (and possibly dbcan/core.py) acts as the entry point; it coordinates the overall annotation workflow.
- I/O Module:
- The dbcan/IO package is responsible for file handling and parsing different input formats (FASTA, GFF, etc.), essentially ingesting raw genomic data.
- Annotation Module:
- Located in dbcan/annotation, this module includes various functional units (e.g., CGCFinder, Diamond, pyhmmer_search) that apply distinct annotation techniques to the input data.
- Process Pipeline:
- The dbcan/process package likely orchestrates running the sub-tools in the correct order, managing intermediate data, and ensuring that comprehensive analysis (for CAZyme families and CGC predictions) is performed.
- Visualization:
- Utility Functions:
- The dbcan/utils package supports database configuration, additional plotting functions, and code helpers that tie these components together.
- Additional Layers:
- Docker support (in the docker folder) encapsulates the application environment, ensuring reproducible and portable executions.
- Environment and dependency management (via conda environment files in envs and environment.yml) further illustrate how the tool is managed and deployed.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Core Workflow"
        A1["Main Executable - dbcan/main.py"]:::core
        A2["Core Module - dbcan/core.py"]:::core
        A1 --> A2
        B["Data Ingestion (IO)"]:::io
        A2 --> B
        C["Annotation Engines"]:::annotation
        B --> C
        D["Processing Pipeline"]:::process
        C --> D
        E["Visualization Module"]:::visualization
        D --> E
    end

    F["Utility Functions"]:::utils
    %% Utility functions assist multiple core components
    A1 --- F
    A2 --- F
    B --- F
    C --- F
    D --- F

    subgraph "Deployment & Support"
        G["Docker Configuration"]:::env
        H["Conda Environments"]:::env
        I["Documentation"]:::docs
        J["Testing"]:::test
    end

    %% Core workflow interacts with deployment and support components
    A1 ---|"config"| G
    A1 ---|"config"| H
    A1 ---|"info"| I
    A1 ---|"QA"| J

    %% External Dependencies (illustrative, part of annotation engines)
    K["External: HMMER & Diamond"]:::external
    C ---|"calls"| K

    %% Click Events
    click A1 "https://github.com/bcb-unl/run_dbcan/blob/master/dbcan/main.py"
    click A2 "https://github.com/bcb-unl/run_dbcan/blob/master/dbcan/core.py"
    click B "https://github.com/bcb-unl/run_dbcan/tree/master/dbcan/IO"
    click C "https://github.com/bcb-unl/run_dbcan/tree/master/dbcan/annotation"
    click D "https://github.com/bcb-unl/run_dbcan/tree/master/dbcan/process"
    click E "https://github.com/bcb-unl/run_dbcan/tree/master/dbcan/plot"
    click F "https://github.com/bcb-unl/run_dbcan/tree/master/dbcan/utils"
    click G "https://github.com/bcb-unl/run_dbcan/tree/master/docker"
    click H "https://github.com/bcb-unl/run_dbcan/tree/master/envs"
    click I "https://github.com/bcb-unl/run_dbcan/tree/master/docs"
    click J "https://github.com/bcb-unl/run_dbcan/tree/master/tests"

    %% Class Definitions for styling
    classDef core fill:#FFC0CB,stroke:#333,stroke-width:2px;
    classDef io fill:#E6E6FA,stroke:#333,stroke-width:2px;
    classDef annotation fill:#98FB98,stroke:#333,stroke-width:2px;
    classDef process fill:#ADD8E6,stroke:#333,stroke-width:2px;
    classDef visualization fill:#FFFACD,stroke:#333,stroke-width:2px;
    classDef utils fill:#D3D3D3,stroke:#333,stroke-width:2px;
    classDef env fill:#E0FFFF,stroke:#333,stroke-width:2px;
    classDef docs fill:#FFE4B5,stroke:#333,stroke-width:2px;
    classDef test fill:#FFDAB9,stroke:#333,stroke-width:2px;
    classDef external fill:#F5DEB3,stroke:#333,stroke-width:2px;
    
    %% Legend (as notes)
    subgraph "Legend"
        L1["Core Modules (Pink)"]:::core
        L2["I/O Modules (Lavender)"]:::io
        L3["Annotation Engines (Pale Green)"]:::annotation
        L4["Processing Pipeline (Light Blue)"]:::process
        L5["Visualization Modules (Light Yellow)"]:::visualization
        L6["Utility Functions (Gray)"]:::utils
        L7["Deployment & Environments (Light Cyan)"]:::env
        L8["Documentation (Moccasin)"]:::docs
        L9["Testing (Peach Puff)"]:::test
        L10["External Tools (Wheat)"]:::external
    end
    style Legend fill:#fff,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5
    %% Arrange legend vertically
    L1 --- L2
    L2 --- L3
    L3 --- L4
    L4 --- L5
    L5 --- L6
    L6 --- L7
    L7 --- L8
    L8 --- L9
    L9 --- L10
```
