# hyperjeff/physical architecture

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

- Interactive diagram: https://gitdiagram.com/hyperjeff/physical
- Repository: https://github.com/hyperjeff/physical

## Overview

##### Main Components

a. Core System Layer:
- Physical Type System
- Unit Conversion Engine
- Dimensional Analysis System
- Numeric Operations Handler

b. Generated Components:
- Unit Definitions
- Conversion Types
- Floating Point Units

c. Experimental Features:
- Constants System
- Statistical Operations
- Array Operations
- Special Functions (dB calculations)

**┌─────────────────────────────────────────────────┐**
- Client Code                     │
- ┘
- ↓
**┌─────────────────────────────────────────────────┐**
- Public API Layer                   │
- Unit Extensions (.meters, .kelvin, etc.)     │
- Operator Overloads                           │
- Conversion Functions                         │
- ┘
- ↓
**┌─────────────────────────────────────────────────┐**
- Core System Layer                  │
- ┬─────────────────┬────────────────┤
- Physical    │   Dimensional   │    Unit        │
- Value Type  │   Analysis      │  Conversion    │
- ┴─────────────────┴────────────────┘
- ↓
**┌─────────────────────────────────────────────────┐**
- Generated Components                  │
- PhysicalUnits                               │
- FloatingPointUnits                          │
- PhysicalConversionType                      │
- ┘
- ↓
**┌─────────────────────────────────────────────────┐**
- Experimental Features                 │
- Constants                                    │
- Array Operations                             │
- Statistics                                   │
- Special Functions (dB)                       │
- ┘

##### Important Relationships

a. Data Flow:
- How unit conversions flow through the system
- How dimensional analysis validates operations
- Demonstrate type checking paths

b. Dependencies:
- Connection to Foundation's Measurement framework
- Relationship between core types and generated code
- Integration of experimental features

##### Implementation Details to Highlight

- How the Physical type composes with various units
- Where type checking occurs (runtime vs. compile-time)
- Demonstrate error handling paths (NotAThing propagation)
- Precision tracking flow

##### Notes for Implementation

- Keep the core Physical type system central
- Extensibility points
- Clear boundaries between generated and hand-written code
- Where experimental features can be opted into

Remember to include notes about the framework's unique features like automatic precision tracking, dimensional analysis, and the special handling of temperature and angle calculations.

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph Client["Client Code Layer"]
        CC[Client Application]
    end

    subgraph API["Public API Layer"]
        UE["Unit Extensions"]:::api
        OO["Operator Overloads"]:::api
        CF["Conversion Functions"]:::api
    end

    subgraph Core["Core System Layer"]
        PTS["Physical Type System"]:::core
        click PTS "https://github.com/hyperjeff/Physical/blob/main/Sources/Physical/Core/Physical.swift"
        
        DAS["Dimensional Analysis"]:::core
        click DAS "https://github.com/hyperjeff/Physical/blob/main/Sources/Physical/Core/Undetermined/Dimension.swift"
        
        UCE["Unit Conversion Engine"]:::core
        click UCE "https://github.com/hyperjeff/Physical/blob/main/Sources/Physical/Core/Physical/Conversions.swift"
        
        NOH["Numeric Operations"]:::core
        click NOH "https://github.com/hyperjeff/Physical/blob/main/Sources/Physical/Core/Numerics.swift"
        
        ALS["Algebra System"]:::core
        click ALS "https://github.com/hyperjeff/Physical/blob/main/Sources/Physical/Core/Physical/Algebra.swift"
        
        ERR["Error Handling"]:::core
        click ERR "https://github.com/hyperjeff/Physical/blob/main/Sources/Physical/Core/Physical/NotAThing.swift"
        
        TC["Type Composition"]:::core
        click TC "https://github.com/hyperjeff/Physical/blob/main/Sources/Physical/Core/Physical/Composition.swif"
    end

    subgraph Generated["Generated Components Layer"]
        UD["Unit Definitions"]:::generated
        click UD "https://github.com/hyperjeff/Physical/blob/main/Sources/Physical/Core/Generated/PhysicalUnits.swift"
        
        CT["Conversion Types"]:::generated
        click CT "https://github.com/hyperjeff/Physical/blob/main/Sources/Physical/Core/Generated/PhysicalConversionType.swift"
        
        FPU["Floating Point Units"]:::generated
        click FPU "https://github.com/hyperjeff/Physical/blob/main/Sources/Physical/Core/Generated/FloatingPointUnits.swift"
    end

    subgraph Experimental["Experimental Features Layer"]
        CS["Constants System"]:::experimental
        click CS "https://github.com/hyperjeff/Physical/blob/main/Sources/Physical/Experimental/Constants.swift"
        
        SO["Statistical Operations"]:::experimental
        click SO "https://github.com/hyperjeff/Physical/blob/main/Sources/Physical/Experimental/PhysicalStatistics.swift"
        
        AO["Array Operations"]:::experimental
        click AO "https://github.com/hyperjeff/Physical/blob/main/Sources/Physical/Core/Physical/Arrays.swift"
        
        SF["Special Functions (dB)"]:::experimental
        click SF "https://github.com/hyperjeff/Physical/blob/main/Sources/Physical/Experimental/dB.swift"
    end

    %% Relationships
    CC --> UE & OO & CF
    UE & OO & CF --> PTS
    PTS --> DAS & UCE & NOH
    DAS --> UCE
    NOH --> ALS
    PTS --> ERR
    PTS --> TC
    UCE --> UD & CT & FPU
    PTS --> CS & SO & AO & SF

    %% Styles
    classDef core fill:#3498db,stroke:#2980b9,color:white
    classDef generated fill:#2ecc71,stroke:#27ae60,color:white
    classDef experimental fill:#e67e22,stroke:#d35400,color:white
    classDef api fill:#9b59b6,stroke:#8e44ad,color:white

    %% Legend
    subgraph Legend
        L1["Core Component"]:::core
        L2["Generated Component"]:::generated
        L3["Experimental Feature"]:::experimental
        L4["Public API"]:::api
    end
```
