# thepetabyteproject/your architecture

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

- Interactive diagram: https://gitdiagram.com/thepetabyteproject/your
- Repository: https://github.com/thepetabyteproject/your

## Overview

##### Project Type and Purpose
- Recognize that “your” is not a full-stack web or standalone GUI application but rather a Python library with associated command-line scripts.
- Its primary purpose is to read various pulsar data formats, convert between them, extract metadata, and assist in data ingestion for transient search pipelines.
- The README emphasizes its use in research environments, serving as both an educational tool and a robust utility for seasoned researchers.

##### File Structure
- Top-Level Directories:
- .github: Contains configuration for CI (e.g., pytest, python-publish), issue templates, and contributor guidelines.
- bin: Houses several executable scripts (e.g., your_bandpass.py, your_candmaker.py, your_heimdall.py) that likely serve as command-line entry points invoking various parts of the “your” functionality.
- docs: Documentation-related scripts and configuration (e.g., mkdocs.yml) which might not be part of the core runtime architecture but are useful for developer onboarding.
- examples: Contains Jupyter notebooks that demonstrate use cases.
- paper: Contains citation and paper details.
- tests: Contains test data and unit tests across various modules to validate functionality.
- your: The main library source code, including:
- your.py: Likely the core entry point or main API class of the library.
- candidate.py: A module to handle candidate information (likely related to pulsar/transient events).
- formats directory: Implements support for different data formats (dada, filterbank, fits, psrfits, pysigproc).
- utils directory: Contains various utility modules (astro, gpu, heimdall, math, misc, plotter, rfi) which support analysis and processing.
- writer.py: Likely centralizes the output or conversion functionalities.

##### Main Components
- Core Library/API:
- "your/your.py": Represents the unified interface/wrapper that ties together the various format readers and writers.
- "your/candidate.py": Handles metadata or candidate-related operations.
- Format Handlers:
- Located in "your/formats": Separate modules for each supported format (dada, filwriter, fitswriter, psrfits, pysigproc). These should be depicted as subcomponents within a “Format Adapters” or “Format Handlers” block.
- Utilities:
- Found in "your/utils": Modules providing support functions (astro, gpu for acceleration, math computations, miscellaneous helpers, plotting, and RFI filtering). Group these in a “Utility Layer” node.
- Command-Line Scripts:
- Located in the "bin" directory: Each script (your_bandpass.py, your_heimdall.py, etc.) provides examples of different access points for end users. These can be grouped in a “CLI Tools” component that communicates with the core library.
- External Dependencies:
- Mention interfaces with external libraries or tools, such as psrdada-python and Heimdall from the README. This node can be labeled “External Services/Libraries” and linked to relevant format handlers and command-line utilities.

##### Architectural Patterns or Design Principles
- Modular Design: Each directory (formats, utils, bin) is self-contained and represents a logical separation of concerns.
- Adapter/Facade Pattern: The core library acts as a unified facade, abstracting format-specific implementations from client code.
- Extensibility: The structure suggests clear extension points (e.g., adding more formats in “your/formats” or new utility functions in “your/utils”).

##### Incorporate Relevant Technologies and Libraries
- Python: The entire system is developed in Python.
- Documentation Tools: MkDocs (docs/mkdocs.yml) for generating documentation.
- Testing Framework: pytest (workflows and tests folder) to assure code quality.
- External Libraries: Heimdall and psrdada-python integration for specialized operations as noted in the README.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core Library
    subgraph "Core Library"
        coreAPI["Core API (your.py)"]:::library
        candidate["Candidate Handling (candidate.py)"]:::candidate
        conversion["Data Conversion/Ingestion"]:::library
    end

    %% Format Adapters
    subgraph "Format Adapters"
        dada["DADA Adapter"]:::adapter
        filwriter["Filterbank Writer"]:::adapter
        fitswriter["FITS Writer"]:::adapter
        psrfits["PSRFITS Handler"]:::adapter
        pysigproc["SIGPROC Adapter"]:::adapter
    end

    %% Utility Layer
    subgraph "Utility Layer"
        astro["Astro Utilities"]:::utility
        gpu["GPU Utilities"]:::utility
        heimdall["Heimdall Helpers"]:::utility
        math["Math Helpers"]:::utility
        misc["Miscellaneous Utilities"]:::utility
        plotter["Plotting Utilities"]:::utility
        rfi["RFI Tools"]:::utility
    end

    %% CLI Tools
    subgraph "CLI Tools"
        cli["CLI Scripts (bin)"]:::cli
    end

    %% External Libraries
    subgraph "External Services/Libraries"
        external["External Libraries (psrdada-python, Heimdall)"]:::external
    end

    %% Connections between components
    cli -->|"invokes"| coreAPI
    candidate -->|"integrated"| coreAPI
    coreAPI -->|"converts"| conversion

    coreAPI -->|"handles"| dada
    coreAPI -->|"handles"| filwriter
    coreAPI -->|"handles"| fitswriter
    coreAPI -->|"handles"| psrfits
    coreAPI -->|"handles"| pysigproc

    coreAPI -->|"uses"| astro
    coreAPI -->|"uses"| gpu
    coreAPI -->|"uses"| heimdall
    coreAPI -->|"uses"| math
    coreAPI -->|"uses"| misc
    coreAPI -->|"uses"| plotter
    coreAPI -->|"uses"| rfi

    cli -->|"calls"| external
    coreAPI -->|"integrates"| external

    %% Styles
    classDef library fill:#B3E5FC,stroke:#0277BD,stroke-width:2px;
    classDef adapter fill:#D1C4E9,stroke:#673AB7,stroke-width:2px;
    classDef utility fill:#C8E6C9,stroke:#388E3C,stroke-width:2px;
    classDef cli fill:#FFF9C4,stroke:#FBC02D,stroke-width:2px;
    classDef external fill:#FFCDD2,stroke:#C62828,stroke-width:2px;
    classDef candidate fill:#E1BEE7,stroke:#8E24AA,stroke-width:2px;

    %% Click Events
    click coreAPI "https://github.com/thepetabyteproject/your/blob/main/your/your.py"
    click candidate "https://github.com/thepetabyteproject/your/blob/main/your/candidate.py"
    click dada "https://github.com/thepetabyteproject/your/blob/main/your/formats/dada.py"
    click filwriter "https://github.com/thepetabyteproject/your/blob/main/your/formats/filwriter.py"
    click fitswriter "https://github.com/thepetabyteproject/your/blob/main/your/formats/fitswriter.py"
    click psrfits "https://github.com/thepetabyteproject/your/blob/main/your/formats/psrfits.py"
    click pysigproc "https://github.com/thepetabyteproject/your/blob/main/your/formats/pysigproc.py"
    click astro "https://github.com/thepetabyteproject/your/blob/main/your/utils/astro.py"
    click gpu "https://github.com/thepetabyteproject/your/blob/main/your/utils/gpu.py"
    click heimdall "https://github.com/thepetabyteproject/your/blob/main/your/utils/heimdall.py"
    click math "https://github.com/thepetabyteproject/your/blob/main/your/utils/math.py"
    click misc "https://github.com/thepetabyteproject/your/blob/main/your/utils/misc.py"
    click plotter "https://github.com/thepetabyteproject/your/blob/main/your/utils/plotter.py"
    click rfi "https://github.com/thepetabyteproject/your/blob/main/your/utils/rfi.py"
    click cli "https://github.com/thepetabyteproject/your/tree/main/bin/"
```
