# synbiodex/sbol-utilities architecture

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

- Interactive diagram: https://gitdiagram.com/synbiodex/sbol-utilities
- Repository: https://github.com/synbiodex/sbol-utilities

## Overview

##### Project Type and Its Purpose
- This project is a utilities library focused on SBOL data transformation and analysis—for both command-line usage and as an importable Python module.
- It is not a full-stack web application, but an open-source tool/library that exposes several independent command-line utilities and Python functions to work with SBOL data.

##### File Structure for Architectural Clues
- The top-level directories include:
- .github directory: Contains workflows for continuous integration (e.g., testing, docstring coverage) which indicate a CI/CD pipeline.
- docs: Documentation source files (using Sphinx with a Makefile, conf.py) for project documentation via ReadTheDocs.
- sbol_utilities: The core package where all main utility functions and scripts (such as conversion, graphing, sequence calculation, etc.) are found.
- test: A comprehensive test suite validating the various utilities and ensuring proper functioning.
- Files such as setup.py, setup.cfg, and pyproject.toml: Indicate packaging and dependency management.
- There are also external assets like the Excel template (sbol_library_template.xlsx) and several CSV files which seem crucial for conversions (e.g., gb2so.csv, so2gb.csv).

##### README for Further Architectural Insights
- The README describes multiple utilities (graphing, converting between SBOL and GenBank/FASTA, expanding combinatorial derivations, calculating sequences or synthesis complexities, and computing diffs between SBOL documents).
- Usage instructions are provided both for command-line interfaces and for integration within a host application.

a. Main Components:
- SBOL Core Library (represented by the sbol_utilities module) that contains common functions and classes for different operations.
- Individual Utilities:
- Excel-to-SBOL Converter: Processes an Excel library template file and converts it into SBOL.
- Format Converters: Utilities for converting between SBOL3, SBOL2, GenBank, and FASTA.
- Derivation Expander: Module that identifies combinatorial derivations and expands them.
- Sequence Calculator: Computes DNA sequences from component parts.
- Complexity Calculator: Evaluates sequence synthesis complexity via the external IDT API.
- SBOL Diff Tool: Compares two SBOL documents and identifies differences.
- External Dependencies:
- Node.js for execution of JavaScript components (e.g., sbolgraph-standalone.js).
- IDT’s API as an external service for the complexity score computation.
- Testing and CI:
- Continuous integration workflows (GitHub Actions) and a robust test suite ensure that any changes are validated.
- Packaging/Distribution:
- Setup and configuration files indicate the system’s preparedness for distribution via PyPI.

b. Relationships and Data Flow:
- The core library (sbol_utilities) serves as the “engine” that each utility leverages.

c. Architectural Patterns and Design Principles:
- Modular design: Each utility functions as an independent module, promoting separation of concerns within the core library.
- Command-line interface abstraction: Clearly separate functions meant for direct command-line execution (e.g., using if __name__ == '__main__') from those intended as callable Python functions.
- Integration with external tools: The design includes wrappers over third-party libraries and APIs, ensuring loose coupling between the core logic and external dependencies.

d. Technologies and Frameworks:
- Python as the programming language.
- Sphinx for documentation (as seen under docs/).
- Node.js for some SBOL conversion utilities.
- Pytest (and CI workflows) for testing.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Core Engine"
        CoreSBOL["Core SBOL Library"]:::core
    end

    subgraph "Utilities"
        subgraph "Graph SBOL Utility"
            GraphSBOLPython["Graph SBOL Utility (Python)"]:::utility
            GraphSBOLJS["SBOL Graph Standalone (JS)"]:::utility
            GraphSBOLPython -->|"uses"| GraphSBOLJS
        end

        subgraph "Excel-to-SBOL Utility"
            ExcelPython["Excel-to-SBOL Converter (Python)"]:::utility
            ExcelTemplate["Excel Template"]:::utility
        end

        subgraph "Format Converters"
            ConversionFunc["General Conversion Functions"]:::utility
            SBOL3ToGenBank["SBOL3 to GenBank Conversion"]:::utility
            CM_gb2so["Conversion Mapping Data (gb2so.csv)"]:::utility
            CM_so2gb["Conversion Mapping Data (so2gb.csv)"]:::utility
        end

        DerivationExpander["Derivation Expander"]:::utility
        subgraph "Sequence Processing"
            SequenceCalc["Sequence Calculator (Python)"]:::utility
            SequenceModule["Sequence Module"]:::utility
        end
        ComplexityCalc["Complexity Calculator"]:::utility
        SBOLDiff["SBOL Diff Tool"]:::utility
    end

    subgraph "External Dependencies"
        Graphviz["Graphviz"]:::external
        NodeJS["Node.js"]:::external
        IDTAPI["IDT API"]:::external
    end

    subgraph "CI & Testing"
        CIWorkflows1["CI Workflow (docstr coverage)"]:::ci
        CIWorkflows2["CI Workflow (python-app)"]:::ci
        TestSuite["Test Suite"]:::ci
    end

    subgraph "Documentation"
        Docs["Documentation"]:::docs
    end

    %% Relationships: Utilities depend on Core Library
    GraphSBOLPython -->|"uses"| CoreSBOL
    GraphSBOLJS -->|"uses"| CoreSBOL
    ExcelPython -->|"uses"| CoreSBOL
    ExcelTemplate -->|"feeds"| ExcelPython
    ConversionFunc -->|"uses"| CoreSBOL
    SBOL3ToGenBank -->|"uses"| CoreSBOL
    CM_gb2so -->|"supports"| ConversionFunc
    CM_so2gb -->|"supports"| ConversionFunc
    DerivationExpander -->|"uses"| CoreSBOL
    SequenceCalc -->|"uses"| CoreSBOL
    SequenceModule -->|"supports"| SequenceCalc
    ComplexityCalc -->|"uses"| CoreSBOL
    SBOLDiff -->|"compares"| CoreSBOL

    %% External dependencies interactions
    GraphSBOLPython ---|"renders diagram via"| Graphviz
    GraphSBOLJS ---|"executes in"| NodeJS
    ComplexityCalc ---|"queries"| IDTAPI

    %% CI & Testing relationships
    CIWorkflows1 -->|"triggers tests in"| TestSuite
    CIWorkflows2 -->|"triggers tests in"| TestSuite

    %% Documentation relationship
    CoreSBOL ---|"documented in"| Docs

    %% Click Events
    click CoreSBOL "https://github.com/synbiodex/sbol-utilities/blob/develop/sbol_utilities/__init__.py"
    
    click GraphSBOLPython "https://github.com/synbiodex/sbol-utilities/blob/develop/sbol_utilities/graph_sbol.py"
    click GraphSBOLJS "https://github.com/synbiodex/sbol-utilities/blob/develop/sbol_utilities/sbolgraph-standalone.js"
    
    click ExcelPython "https://github.com/synbiodex/sbol-utilities/blob/develop/sbol_utilities/excel_to_sbol.py"
    click ExcelTemplate "https://github.com/synbiodex/sbol-utilities/blob/develop/sbol_library_template.xlsx"
    
    click ConversionFunc "https://github.com/synbiodex/sbol-utilities/blob/develop/sbol_utilities/conversion.py"
    click SBOL3ToGenBank "https://github.com/synbiodex/sbol-utilities/blob/develop/sbol_utilities/sbol3_genbank_conversion.py"
    click CM_gb2so "https://github.com/synbiodex/sbol-utilities/blob/develop/sbol_utilities/gb2so.csv"
    click CM_so2gb "https://github.com/synbiodex/sbol-utilities/blob/develop/sbol_utilities/so2gb.csv"
    
    click DerivationExpander "https://github.com/synbiodex/sbol-utilities/blob/develop/sbol_utilities/expand_combinatorial_derivations.py"
    
    click SequenceCalc "https://github.com/synbiodex/sbol-utilities/blob/develop/sbol_utilities/calculate_sequences.py"
    click SequenceModule "https://github.com/synbiodex/sbol-utilities/blob/develop/sbol_utilities/sequence.py"
    
    click ComplexityCalc "https://github.com/synbiodex/sbol-utilities/blob/develop/sbol_utilities/calculate_complexity_scores.py"
    
    click SBOLDiff "https://github.com/synbiodex/sbol-utilities/blob/develop/sbol_utilities/sbol_diff.py"
    
    click CIWorkflows1 "https://github.com/synbiodex/sbol-utilities/blob/develop/.github/workflows/docstr-coverage.yml"
    click CIWorkflows2 "https://github.com/synbiodex/sbol-utilities/blob/develop/.github/workflows/python-app.yml"
    click TestSuite "https://github.com/synbiodex/sbol-utilities/tree/develop/test/"
    
    click Docs "https://github.com/synbiodex/sbol-utilities/tree/develop/docs/"

    %% Styles
    classDef core fill:#FFCC00,stroke:#333,stroke-width:2px;
    classDef utility fill:#A8DADC,stroke:#1D3557,stroke-width:2px;
    classDef external fill:#E63946,stroke:#720026,stroke-width:2px;
    classDef ci fill:#F4A261,stroke:#E76F51,stroke-width:2px;
    classDef docs fill:#457B9D,stroke:#1D3557,stroke-width:2px;
```
