# xdas-dev/xdas architecture

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

- Interactive diagram: https://gitdiagram.com/xdas-dev/xdas
- Repository: https://github.com/xdas-dev/xdas

## Overview

##### Project type and purpose
- This is a domain-specific Python framework (an open‐source library) for ingesting, representing, processing, and visualizing Distributed Acoustic Sensing (DAS) data.
- It exposes a set of self-describing, N-dimensional data abstractions (built on xarray) and leverages lazy or parallel execution (inspired by Dask).

##### File structure
- Top-level module “xdas” contains all functionality, broken into subpackages:
- io – various DAS file‐format readers (miniseed, ASN, TDMS, etc.)
- core – fundamental data types and I/O abstraction core.py, dataarray.py, datacollection.py, coordinates.py, routines, numpy wrappers
- dask – adapters to allow larger-than-memory, parallel execution (core, serial)
- processing – higher-level processing pipelines (monitor, core)
- atoms – atomic operations and small building blocks (signal, ML helpers)
- fft, spectral, synthetics, trigger, virtual – specialized signal‐processing utilities
- config, parallel – global configuration and parallel orchestration
- tests/ exercises each module
- docs/ holds end-user guides and API references

##### README for insights
- Confirms reliance on xarray, NumPy/SciPy, Dask
- Emphasizes extensibility (pipelines mixing Xdas primitives with custom code)

##### Final recommendations
- Format-specific readers together; group signal routines together.
- Validate your draft against the file tree to ensure every major module is represented.
- Save it in a vector format (SVG) so it can be refined and embedded in the documentation.
- Review with domain experts to confirm nomenclature (e.g., “DataCollection” vs. “DataArray”).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Entities
    subgraph "External Dependencies"
        XR["xarray"]:::external
        NP["numpy"]:::external
        SP["scipy"]:::external
        DK["dask"]:::external
    end

    UR["User Notebooks/Scripts"]:::user

    %% Core Library
    subgraph "xdas Library"
        subgraph "I/O Layer"
            IO["xdas/io"]:::coremod
        end
        subgraph "Core Data Model"
            CD["xdas/core"]:::coremod
        end
        subgraph "Atomic Operations"
            AT["xdas/atoms"]:::coremod
        end
        subgraph "Processing Pipelines"
            PP["xdas/processing"]:::coremod
        end
        subgraph "Parallel Engine"
            subgraph "Dask Integration"
                DKint["xdas/dask"]:::coremod
            end
            PAR["xdas/parallel.py"]:::coremod
        end
        subgraph "Signal Utilities"
            FFT["xdas/fft.py"]:::coremod
            SPEC["xdas/spectral.py"]:::coremod
            SYN["xdas/synthetics.py"]:::coremod
            TRG["xdas/trigger.py"]:::coremod
            VIR["xdas/virtual.py"]:::coremod
        end
        CFG["xdas/config.py"]:::coremod
    end

    %% Data Flow
    UR -->|uses API| IO
    UR -->|uses API| CD
    UR -->|uses API| PP

    IO -->|reads raw files| CD
    CD -->|provides DataModel| AT
    CD -->|provides DataModel| FFT
    CD -->|provides DataModel| SPEC
    CD -->|provides DataModel| SYN
    CD -->|provides DataModel| TRG
    CD -->|provides DataModel| VIR

    AT -->|operations| PP
    PP -->|orchestrates| AT
    PP -->|outputs DataModel| CD

    %% Dependency Arrows (dashed)
    DKint -.->|extends| CD
    DKint -.->|extends| PP
    PAR -.->|orchestrates| DKint
    PAR -.->|orchestrates| PP

    XR -.-> CD
    NP -.-> IO
    NP -.-> AT
    SP -.-> PP
    DK -.-> DKint

    %% Click Events
    click IO "https://github.com/xdas-dev/xdas/tree/main/xdas/io/"
    click CD "https://github.com/xdas-dev/xdas/tree/main/xdas/core/"
    click AT "https://github.com/xdas-dev/xdas/tree/main/xdas/atoms/"
    click PP "https://github.com/xdas-dev/xdas/tree/main/xdas/processing/"
    click DKint "https://github.com/xdas-dev/xdas/tree/main/xdas/dask/"
    click PAR "https://github.com/xdas-dev/xdas/blob/main/xdas/parallel.py"
    click FFT "https://github.com/xdas-dev/xdas/blob/main/xdas/fft.py"
    click SPEC "https://github.com/xdas-dev/xdas/blob/main/xdas/spectral.py"
    click SYN "https://github.com/xdas-dev/xdas/blob/main/xdas/synthetics.py"
    click TRG "https://github.com/xdas-dev/xdas/blob/main/xdas/trigger.py"
    click VIR "https://github.com/xdas-dev/xdas/blob/main/xdas/virtual.py"
    click CFG "https://github.com/xdas-dev/xdas/blob/main/xdas/config.py"

    %% Styles
    classDef external fill:#a2fca2,stroke:#032d02
    classDef coremod fill:#a0c4ff,stroke:#001f3f
    classDef user fill:#ffd6a5,stroke:#663300
```
