# tgsai/mdio-python architecture

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

- Interactive diagram: https://gitdiagram.com/tgsai/mdio-python
- Repository: https://github.com/tgsai/mdio-python

## Overview

##### Main Components
- User Interface/CLI:
- Represented by the “commands” package. This component handles parsing user inputs and triggering the API.
- Python API:
- Located in the “api” package. It provides programmatic access to the library’s functionality and abstracts lower-level operations.
- Core Library:
- Found in the “core” folder. This includes data abstraction, dimension handling, grid management, and error handling.
- Data Converters:
- Under the “converters” directory, including modules that handle data format transformations (e.g., MDIO and SEG-Y converters).
- SEG-Y Specific Module:
- Under “segy” which includes functionality for blocked I/O, parsing, geometry, and exception handling for SEG-Y data.
- External Dependencies:
- External systems like Zarr (for cloud-native chunked storage), Dask (for distributed reading/writing), and other libraries such as segyio, Blosc, and ZFP.
- Testing:

##### Relationships and Data Flow
- The CLI/commands layer calls functions provided in the API package, which in turn orchestrates operations in the Core modules.
- When dealing with file formats (like SEG-Y), the API invokes the converters and segy modules.
- The converters utilize core utilities and also route to external libraries (e.g., segyio for SEG-Y, dask for parallel/distributed operations).
- Data storage and retrieval are managed via integrations with Zarr and storage backends via fsspec.
- Optional modules such as those for distributed computing or cloud I/O can be indicated as overlays around the core data processing flow.

##### Architectural Patterns
- Layered Architecture: Distinct layers (CLI, API, core logic, converters, external integrations) aid separation of concerns.
- Plugin/Extension Points: The organization into convertible modules and specialized SEG-Y handling signifies an extensible design that can integrate future features like wind resource assessment or additional energy data types.
- Modular Design: Clear division into independent directories and modules allows for the independent evolution of different functionalities.

##### Relevant Technologies
- Technologies: Zarr, Dask, Numba, segyio, Click, and additional libraries for distributed computing (distributed, bokeh) or cloud storage (s3fs, gcsfs, adlfs).
- Frameworks & Tools: The project uses GitHub workflows, pre-commit hooks, Docker (via devcontainer), and documentation managed with Sphinx (docs directory).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Internal Modules
    subgraph "Internal Modules"
        UI["User Interface / CLI"]:::frontend
        API["Python API"]:::api
        CORE["Core Library"]:::core
        CONV["Data Converters"]:::converters
        SEGY["SEG-Y Specific Module"]:::segy
    end

    %% External Dependencies
    subgraph "External Dependencies"
        ZARR["Storage (Zarr, fsspec)"]:::external
        DASK["Distributed Computing (Dask)"]:::external
        OTHERS["Other Libraries (segyio, Blosc, ZFP)"]:::external
    end

    %% Validation / Testing
    subgraph "Validation"
        TEST["Testing"]:::test
    end

    %% Data Flow Connections
    UI -->|"triggers"| API
    API -->|"orchestrates"| CORE
    API -->|"orchestrates"| CONV
    API -->|"orchestrates"| SEGY
    CONV -->|"leverages"| CORE
    CORE -->|"integrates with"| ZARR
    CORE -->|"integrates with"| DASK
    CONV -->|"utilizes"| ZARR
    CONV -->|"utilizes"| DASK
    SEGY -->|"utilizes"| OTHERS

    %% Testing validates modules
    TEST ---|"validates"| UI
    TEST ---|"validates"| API
    TEST ---|"validates"| CORE
    TEST ---|"validates"| CONV
    TEST ---|"validates"| SEGY

    %% Click Events
    click UI "https://github.com/tgsai/mdio-python/tree/main/src/mdio/commands"
    click API "https://github.com/tgsai/mdio-python/tree/main/src/mdio/api"
    click CORE "https://github.com/tgsai/mdio-python/tree/main/src/mdio/core"
    click CONV "https://github.com/tgsai/mdio-python/tree/main/src/mdio/converters"
    click SEGY "https://github.com/tgsai/mdio-python/tree/main/src/mdio/segy"
    click TEST "https://github.com/tgsai/mdio-python/tree/main/tests"

    %% Styles
    classDef frontend fill:#a7d8de,stroke:#333,stroke-width:2px;
    classDef api fill:#f9e79f,stroke:#333,stroke-width:2px;
    classDef core fill:#aed6f1,stroke:#333,stroke-width:2px;
    classDef converters fill:#d2b4de,stroke:#333,stroke-width:2px;
    classDef segy fill:#f5b7b1,stroke:#333,stroke-width:2px;
    classDef external fill:#d5f5e3,stroke:#333,stroke-width:2px;
    classDef test fill:#f7dc6f,stroke:#333,stroke-width:2px;
```
