# irukoa/mac architecture

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

- Interactive diagram: https://gitdiagram.com/irukoa/mac
- Repository: https://github.com/irukoa/mac

## Overview

##### Project Type and Purpose
- This is a tiny open-source Fortran library (“MAC”) that provides rank-agnostic multidimensional array containers. It’s designed as a reusable component for Fortran projects, distributed via the Fortran Package Manager (fpm), with examples and a test suite.

##### File-Structure Analysis
- Top-level:
- .github/workflows/CI.yml – GitHub Actions CI pipeline
- fpm.toml – Fortran Package Manager configuration
- app/ – demonstration programs (runtime_error_detection, main.F90)
- src/ – core library modules (MAC.F90, MAC_kinds.F90, MAC.fpp)
- example/ – example usage programs
- test/ – test driver and test suites
- Key patterns:
- Modular code in src/ defining types container_specifier & container
- Client programs in app/ and example/ import the modules
- test/ invokes the library to validate behavior
- CI orchestrates build & test via fpm and GitHub Actions

##### README Insights
- Core API revolves around two derived types: container_specifier and container
- Interfaces for constructors, getters/setters, indexing, slicing, reduction
- Build & distribution via fpm; CI ensures correctness

##### Components
a. Main components
1. Library Module Layer (src/)
– MAC module files
– Defines container_specifier & container types
2. Client Layer
– app/ (runtime_error_detection, main.F90)
– example/ (example_basic, example_container, example_partial_permutation)
3. Test Layer (test/)
– driver.F90 + multiple suites
4. Build & CI Infrastructure
– fpm.toml & Fortran compiler
– GitHub Actions CI workflow
5. External Integrations
– Fortran Package Manager registry
– GitHub/Git hosting
b. Relationships & Data Flows
– CI workflow triggers fpm build & test → CI status reporting
– GitHub → CI trigger on pushes/pull requests
c. Architectural Patterns & Principles
– Modular layering: core library decoupled from clients & tests
– Single responsibility: modules focus on array handle logic
– Test-driven development: multiple suites validate each feature
– Packaging: fpm for dependency management
d. Key Technologies & Frameworks
– Fortran 2008+
– Fortran Package Manager (fpm)
– GitHub Actions for CI
– Pre-commit hooks (.pre-commit-config.yaml)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Services
    subgraph "External Services"
        GH("GitHub"):::external
        FPMREG("Fortran Package Manager Registry"):::external
    end

    %% Build & CI Infrastructure
    subgraph "Build & CI Infrastructure"
        TOML["fpm.toml"]:::config
        CI["CI Pipeline (CI.yml)"]:::config
        PRE[".pre-commit-config.yaml"]:::config
    end

    %% Core Library
    subgraph "MAC Library (src/)"
        M1["MAC.F90"]:::lib
        M2["MAC_kinds.F90"]:::lib
        M3["MAC.fpp"]:::lib
    end

    %% Client Layer
    subgraph "Client Layer"
        subgraph "App Programs (app/)"
            A1["main.F90"]:::client
            A2["Integer_Overflow_Happens.F90"]:::client
            A3["Integer_Overflow_Does_Not_Happen.F90"]:::client
        end
        subgraph "Example Programs (example/)"
            E1["example_basic.F90"]:::client
            E2["example_container.F90"]:::client
            E3["example_partial_permutation.F90"]:::client
        end
    end

    %% Test Suites
    subgraph "Test Suites (test/)"
        D["driver.F90"]:::test
        subgraph "Suites"
            T1["Expected_Behaviour_Suite.F90"]:::test
            T2["Integer_Overflow_Suite.F90"]:::test
            T3["Randomized_Suite.F90"]:::test
            T4["Reduction_Suite.F90"]:::test
            T5["Sections_Suite.F90"]:::test
        end
    end

    %% Relationships
    GH -->|triggers CI| CI
    FPMREG -->|provides registry| TOML
    CI -->|build & test| M1
    CI -->|build & test| A1
    CI -->|build & test| D
    TOML -->|configures build| M1
    TOML -->|configures build| A1
    TOML -->|configures build| D
    M1 -->|used by| A1
    M1 -->|used by| A2
    M1 -->|used by| A3
    M1 -->|used by| E1
    M1 -->|used by| E2
    M1 -->|used by| E3
    M1 -->|tested by| T1
    M1 -->|tested by| T2
    M1 -->|tested by| T3
    M1 -->|tested by| T4
    M1 -->|tested by| T5

    %% Click Events
    click M1 "https://github.com/irukoa/mac/blob/main/src/MAC.F90"
    click M2 "https://github.com/irukoa/mac/blob/main/src/MAC_kinds.F90"
    click M3 "https://github.com/irukoa/mac/blob/main/src/MAC.fpp"
    click A1 "https://github.com/irukoa/mac/blob/main/app/main.F90"
    click A2 "https://github.com/irukoa/mac/blob/main/app/runtime_error_detection/Integer_Overflow_Happens.F90"
    click A3 "https://github.com/irukoa/mac/blob/main/app/runtime_error_detection/Integer_Overflow_Does_Not_Happen.F90"
    click E1 "https://github.com/irukoa/mac/blob/main/example/example_basic.F90"
    click E2 "https://github.com/irukoa/mac/blob/main/example/example_container.F90"
    click E3 "https://github.com/irukoa/mac/blob/main/example/example_partial_permutation.F90"
    click D "https://github.com/irukoa/mac/blob/main/test/driver.F90"
    click T1 "https://github.com/irukoa/mac/blob/main/test/suites/Expected_Behaviour_Suite.F90"
    click T2 "https://github.com/irukoa/mac/blob/main/test/suites/Integer_Overflow_Suite.F90"
    click T3 "https://github.com/irukoa/mac/blob/main/test/suites/Randomized_Suite.F90"
    click T4 "https://github.com/irukoa/mac/blob/main/test/suites/Reduction_Suite.F90"
    click T5 "https://github.com/irukoa/mac/blob/main/test/suites/Sections_Suite.F90"
    click TOML "https://github.com/irukoa/mac/blob/main/fpm.toml"
    click CI "https://github.com/irukoa/mac/blob/main/.github/workflows/CI.yml"
    click PRE "https://github.com/irukoa/mac/blob/main/.pre-commit-config.yaml"
    click GH "https://github.com/irukoa/mac/tree/main/.github/"
    click FPMREG "https://github.com/irukoa/mac/blob/main/fpm.toml"

    %% Styles
    classDef lib fill:#cce5ff,stroke:#004085,color:#004085;
    classDef client fill:#d4edda,stroke:#155724,color:#155724;
    classDef test fill:#fff3cd,stroke:#856404,color:#856404;
    classDef config fill:#e2e3e5,stroke:#6c757d,color:#6c757d;
    classDef external fill:#f8d7da,stroke:#721c24,color:#721c24,stroke-dasharray: 5 5;
```
