# simonrw/rust-fitsio architecture

> Architecture diagram of the GitHub repository simonrw/rust-fitsio, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2024-12-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/simonrw/rust-fitsio
- Repository: https://github.com/simonrw/rust-fitsio

## Overview

##### Layer Structure (Top to bottom)

- [User Application Layer]
- ↓
- [Rust High-level API (fitsio)]
- ↓
- [Custom Derives (fitsio-derive)]
- ↓
- [FFI Bindings (fitsio-sys)]
- ↓
- [CFITSIO C Library]

- fitsio → fitsio-sys
- fitsio → fitsio-derive
- fitsio-sys → CFITSIO

- Build System → fitsio-sys
- Build System → CFITSIO

##### Feature Components (Hexagons)
- Thread-safe Operations
- FITS File Operations
- Image Handling
- Table Operations
- Header Management

##### Integration Points (Diamonds)
- Platform-specific Builds
- NDArray Support
- Memory Management
- Error Handling

Special Considerations:

##### Platform Support Tiers
- A side panel showing the three-tier platform support system

##### Build Variants
- Alternative compilation paths:
- Default build
- Bindgen-based build
- Source compilation with fitsio-src feature

##### Threading Model
- Thread-safe nature of the implementation
- Reentrant support requirements

##### Error Handling Flow
- Demonstrate error propagation from C to Rust
- Safety boundary between unsafe FFI and safe Rust code

##### Maintain clear separation between
- Build-time vs. Runtime components
- Safe vs. Unsafe boundaries
- Public vs. Internal APIs

Remember to include version compatibility information and note the relationship with the underlying CFITSIO version requirements (>= 3.37).

This design should help developers understand both the high-level architecture and the detailed interactions between components while maintaining focus on the library's primary purpose as a FITS file manipulation tool.

## Diagram (Mermaid)

```mermaid
%%{init: {
  'theme': 'base',
  'themeVariables': {
    'primaryColor': '#2b2b2b',
    'primaryTextColor': '#fff',
    'primaryBorderColor': '#7C0000',
    'lineColor': '#F8B229',
    'secondaryColor': '#006100',
    'tertiaryColor': '#0000ff'
  }
}}%%

flowchart TB
    classDef core fill:#2b2b2b,stroke:#333,stroke-width:2px,color:#fff
    classDef support fill:#4A90E2,stroke:#2171C7,stroke-width:2px,color:#fff
    classDef feature fill:#50C878,stroke:#2E8B57,stroke-width:2px,color:#fff
    classDef integration fill:#FFD700,stroke:#DAA520,stroke-width:2px,color:#000
    classDef external fill:#FF6B6B,stroke:#CD5C5C,stroke-width:2px,color:#fff
    classDef unsafe fill:#FF4500,stroke:#8B0000,stroke-width:2px,color:#fff

    subgraph UserLayer
        UA[User Application]
    end

    subgraph RustAPI
        Fitsio[Main Rust Interface]:::core
        TypeSystem[Type System]:::core
        ErrorHandling[Error Handling]:::core
    end

    subgraph CoreFeatures
        ThreadSafe[Thread-safe Operations]:::feature
        FitsOps[FITS File Operations]:::feature
        ImageHandling[Image Handling]:::feature
        TableOps[Table Operations]:::feature
        HeaderMgmt[Header Management]:::feature
        HDUMgmt[HDU Management]:::feature
    end

    subgraph Integration
        NDArray[NDArray Support]:::integration
        MemoryMgmt[Memory Management]:::integration
    end

    subgraph FFILayer
        FitsioDeriv[Custom Derives]:::core
        FitsioSys[FFI Bindings]:::unsafe
    end

    subgraph External
        CFITSIO[CFITSIO C Library]:::external
        BuildSystem[Build System]:::support
    end

    UA --> Fitsio
    Fitsio --> FitsioDeriv
    Fitsio --> FitsioSys
    FitsioSys --> CFITSIO
    BuildSystem -.-> FitsioSys
    BuildSystem -.-> CFITSIO

    Fitsio --> TypeSystem
    Fitsio --> ErrorHandling
    Fitsio --> CoreFeatures
    Fitsio --> Integration

    click Fitsio "https://github.com/simonrw/rust-fitsio/blob/main/fitsio/src/lib.rs"
    click FitsioSys "https://github.com/simonrw/rust-fitsio/blob/main/fitsio-sys/src/lib.rs"
    click FitsioDeriv "https://github.com/simonrw/rust-fitsio/blob/main/fitsio-derive/src/lib.rs"
    click CFITSIO "https://github.com/simonrw/rust-fitsio/tree/main/fitsio-sys/ext/cfitsio/"
    click ThreadSafe "https://github.com/simonrw/rust-fitsio/blob/main/fitsio/src/threadsafe_fitsfile.rs"
    click ImageHandling "https://github.com/simonrw/rust-fitsio/blob/main/fitsio/src/images.rs"
    click TableOps "https://github.com/simonrw/rust-fitsio/blob/main/fitsio/src/tables.rs"
    click HeaderMgmt "https://github.com/simonrw/rust-fitsio/blob/main/fitsio/src/headers/mod.rs"
    click ErrorHandling "https://github.com/simonrw/rust-fitsio/blob/main/fitsio/src/errors.rs"
    click FitsOps "https://github.com/simonrw/rust-fitsio/blob/main/fitsio/src/fitsfile.rs"
    click HDUMgmt "https://github.com/simonrw/rust-fitsio/blob/main/fitsio/src/hdu.rs"
    click TypeSystem "https://github.com/simonrw/rust-fitsio/blob/main/fitsio/src/types.rs"
    click NDArray "https://github.com/simonrw/rust-fitsio/blob/main/fitsio/src/ndarray_compat.rs"
    click BuildSystem "https://github.com/simonrw/rust-fitsio/blob/main/fitsio-sys/build.rs"

    %% Legend
    subgraph Legend
        L1[Core Components]:::core
        L2[Support Components]:::support
        L3[Features]:::feature
        L4[Integration Points]:::integration
        L5[External Dependencies]:::external
        L6[Unsafe Boundary]:::unsafe
    end
```
