# cosinekitty/astronomy architecture

> Architecture diagram of the GitHub repository cosinekitty/astronomy, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/cosinekitty/astronomy
- Repository: https://github.com/cosinekitty/astronomy

## Overview

Astronomy Engine is a multi-language astronomy calculation library. A consumer supplies a date/time and, for observer-based calculations, a location; a language API returns positions, coordinate conversions, or predicted events. The README documents broad capabilities and consistent APIs across languages. The sampled C source is a large implementation file, so feature nodes use that exact path as a representative implementation; equivalent feature-level wiring in the other language ports was not inspected.

Main entry points: [`source/c/astronomy.c`](https://github.com/cosinekitty/astronomy/blob/master/source/c/astronomy.c) (C / C++ API), [`source/csharp/astronomy.cs`](https://github.com/cosinekitty/astronomy/blob/master/source/csharp/astronomy.cs) (C# API), [`source/js/astronomy.js`](https://github.com/cosinekitty/astronomy/blob/master/source/js/astronomy.js) (JavaScript API), [`source/python/astronomy/astronomy.py`](https://github.com/cosinekitty/astronomy/blob/master/source/python/astronomy/astronomy.py) (Python API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_apis["Language APIs"]
  node_c_api["C / C++ API<br/>[astronomy.c]"]
  node_cs_api["C&#35; API<br/>[astronomy.cs]"]
  node_js_api["JavaScript API<br/>[astronomy.js]"]
  node_py_api["Python API<br/>[astronomy.py]"]
  node_kt_api["Kotlin API<br/>[astronomy.kt]"]
end

subgraph group_core["Astronomical Core"]
  node_body_states["Body positions<br/>[astronomy.c]"]
  node_vectors["Vectors and frames<br/>[astronomy.c]"]
  node_time["Time handling<br/>[astronomy.c]"]
  node_magnitudes["Visual magnitudes<br/>[astronomy.c]"]
end

subgraph group_observer["Observer Calculations"]
  node_observer_pos["Topocentric positions<br/>[astronomy.c]"]
  node_refraction["Atmospheric refraction<br/>[astronomy.c]"]
  node_gravity["Observer gravity<br/>[astronomy.c]"]
end

subgraph group_events["Event Searches"]
  node_rise_set["Rise and set<br/>[astronomy.c]"]
  node_twilight["Twilight searches<br/>[astronomy.c]"]
  node_phases["Lunar phases<br/>[astronomy.c]"]
  node_eclipses["Eclipse predictions<br/>[astronomy.c]"]
  node_transits["Planetary transits<br/>[astronomy.c]"]
  node_season_events["Seasons<br/>[astronomy.c]"]
  node_planet_events["Planet events<br/>[astronomy.c]"]
end

subgraph group_special["Specialized Results"]
  node_jupiter_moons["Jupiter moons<br/>[astronomy.c]"]
  node_small_bodies["Small-body simulation<br/>[astronomy.c]"]
  node_constellations["Constellations<br/>[astronomy.c]"]
  node_lunar_details["Lunar details<br/>[astronomy.c]"]
  node_rotation["Body orientation<br/>[astronomy.c]"]
end

node_consumer(("Library consumer"))

node_consumer -->|"calls"| node_c_api
node_consumer -->|"calls"| node_cs_api
node_consumer -->|"calls"| node_js_api
node_consumer -->|"calls"| node_py_api
node_consumer -->|"calls"| node_kt_api
node_c_api -->|"calculates"| node_body_states
node_c_api -->|"converts"| node_vectors
node_c_api -->|"handles"| node_time
node_c_api -->|"calculates"| node_magnitudes
node_c_api -->|"calculates"| node_observer_pos
node_c_api -->|"corrects"| node_refraction
node_c_api -->|"calculates"| node_gravity
node_c_api -->|"searches"| node_rise_set
node_c_api -->|"searches"| node_twilight
node_c_api -->|"searches"| node_phases
node_c_api -->|"predicts"| node_eclipses
node_c_api -->|"predicts"| node_transits
node_c_api -->|"predicts"| node_season_events
node_c_api -->|"predicts"| node_planet_events
node_c_api -->|"calculates"| node_jupiter_moons
node_c_api -->|"simulates"| node_small_bodies
node_c_api -->|"identifies"| node_constellations
node_c_api -->|"calculates"| node_lunar_details
node_c_api -->|"calculates"| node_rotation

click node_c_api "https://github.com/cosinekitty/astronomy/blob/master/source/c/astronomy.c"
click node_cs_api "https://github.com/cosinekitty/astronomy/blob/master/source/csharp/astronomy.cs"
click node_js_api "https://github.com/cosinekitty/astronomy/blob/master/source/js/astronomy.js"
click node_py_api "https://github.com/cosinekitty/astronomy/blob/master/source/python/astronomy/astronomy.py"
click node_kt_api "https://github.com/cosinekitty/astronomy/blob/master/source/kotlin/src/main/kotlin/io/github/cosinekitty/astronomy/astronomy.kt"
click node_body_states "https://github.com/cosinekitty/astronomy/blob/master/source/c/astronomy.c"
click node_vectors "https://github.com/cosinekitty/astronomy/blob/master/source/c/astronomy.c"
click node_time "https://github.com/cosinekitty/astronomy/blob/master/source/c/astronomy.c"
click node_magnitudes "https://github.com/cosinekitty/astronomy/blob/master/source/c/astronomy.c"
click node_observer_pos "https://github.com/cosinekitty/astronomy/blob/master/source/c/astronomy.c"
click node_refraction "https://github.com/cosinekitty/astronomy/blob/master/source/c/astronomy.c"
click node_gravity "https://github.com/cosinekitty/astronomy/blob/master/source/c/astronomy.c"
click node_rise_set "https://github.com/cosinekitty/astronomy/blob/master/source/c/astronomy.c"
click node_twilight "https://github.com/cosinekitty/astronomy/blob/master/source/c/astronomy.c"
click node_phases "https://github.com/cosinekitty/astronomy/blob/master/source/c/astronomy.c"
click node_eclipses "https://github.com/cosinekitty/astronomy/blob/master/source/c/astronomy.c"
click node_transits "https://github.com/cosinekitty/astronomy/blob/master/source/c/astronomy.c"
click node_season_events "https://github.com/cosinekitty/astronomy/blob/master/source/c/astronomy.c"
click node_planet_events "https://github.com/cosinekitty/astronomy/blob/master/source/c/astronomy.c"
click node_jupiter_moons "https://github.com/cosinekitty/astronomy/blob/master/source/c/astronomy.c"
click node_small_bodies "https://github.com/cosinekitty/astronomy/blob/master/source/c/astronomy.c"
click node_constellations "https://github.com/cosinekitty/astronomy/blob/master/source/c/astronomy.c"
click node_lunar_details "https://github.com/cosinekitty/astronomy/blob/master/source/c/astronomy.c"
click node_rotation "https://github.com/cosinekitty/astronomy/blob/master/source/c/astronomy.c"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_c_api,node_cs_api,node_js_api,node_py_api,node_kt_api toneBlue
class node_body_states,node_vectors,node_time,node_magnitudes toneAmber
class node_observer_pos,node_refraction,node_gravity toneMint
class node_rise_set,node_twilight,node_phases,node_eclipses,node_transits,node_season_events,node_planet_events toneRose
class node_jupiter_moons,node_small_bodies,node_constellations,node_lunar_details,node_rotation,node_consumer toneIndigo
```

## Components

### Language APIs

- [C / C++ API](https://github.com/cosinekitty/astronomy/blob/master/source/c/astronomy.c): `source/c/astronomy.c`
- [C# API](https://github.com/cosinekitty/astronomy/blob/master/source/csharp/astronomy.cs): `source/csharp/astronomy.cs`
- [JavaScript API](https://github.com/cosinekitty/astronomy/blob/master/source/js/astronomy.js): `source/js/astronomy.js`
- [Python API](https://github.com/cosinekitty/astronomy/blob/master/source/python/astronomy/astronomy.py): `source/python/astronomy/astronomy.py`
- [Kotlin API](https://github.com/cosinekitty/astronomy/blob/master/source/kotlin/src/main/kotlin/io/github/cosinekitty/astronomy/astronomy.kt): `source/kotlin/src/main/kotlin/io/github/cosinekitty/astronomy/astronomy.kt`

### Astronomical Core

- [Body positions](https://github.com/cosinekitty/astronomy/blob/master/source/c/astronomy.c): `source/c/astronomy.c`
- [Vectors and frames](https://github.com/cosinekitty/astronomy/blob/master/source/c/astronomy.c): `source/c/astronomy.c`
- [Time handling](https://github.com/cosinekitty/astronomy/blob/master/source/c/astronomy.c): `source/c/astronomy.c`
- [Visual magnitudes](https://github.com/cosinekitty/astronomy/blob/master/source/c/astronomy.c): `source/c/astronomy.c`

### Observer Calculations

- [Topocentric positions](https://github.com/cosinekitty/astronomy/blob/master/source/c/astronomy.c): `source/c/astronomy.c`
- [Atmospheric refraction](https://github.com/cosinekitty/astronomy/blob/master/source/c/astronomy.c): `source/c/astronomy.c`
- [Observer gravity](https://github.com/cosinekitty/astronomy/blob/master/source/c/astronomy.c): `source/c/astronomy.c`

### Event Searches

- [Rise and set](https://github.com/cosinekitty/astronomy/blob/master/source/c/astronomy.c): `source/c/astronomy.c`
- [Twilight searches](https://github.com/cosinekitty/astronomy/blob/master/source/c/astronomy.c): `source/c/astronomy.c`
- [Lunar phases](https://github.com/cosinekitty/astronomy/blob/master/source/c/astronomy.c): `source/c/astronomy.c`
- [Eclipse predictions](https://github.com/cosinekitty/astronomy/blob/master/source/c/astronomy.c): `source/c/astronomy.c`
- [Planetary transits](https://github.com/cosinekitty/astronomy/blob/master/source/c/astronomy.c): `source/c/astronomy.c`
- [Seasons](https://github.com/cosinekitty/astronomy/blob/master/source/c/astronomy.c): `source/c/astronomy.c`
- [Planet events](https://github.com/cosinekitty/astronomy/blob/master/source/c/astronomy.c): `source/c/astronomy.c`

### Specialized Results

- [Jupiter moons](https://github.com/cosinekitty/astronomy/blob/master/source/c/astronomy.c): `source/c/astronomy.c`
- [Small-body simulation](https://github.com/cosinekitty/astronomy/blob/master/source/c/astronomy.c): `source/c/astronomy.c`
- [Constellations](https://github.com/cosinekitty/astronomy/blob/master/source/c/astronomy.c): `source/c/astronomy.c`
- [Lunar details](https://github.com/cosinekitty/astronomy/blob/master/source/c/astronomy.c): `source/c/astronomy.c`
- [Body orientation](https://github.com/cosinekitty/astronomy/blob/master/source/c/astronomy.c): `source/c/astronomy.c`

### Other components

- **Library consumer**

## Connections

- Library consumer → C / C++ API: calls
- Library consumer → C# API: calls
- Library consumer → JavaScript API: calls
- Library consumer → Python API: calls
- Library consumer → Kotlin API: calls
- C / C++ API → Body positions: calculates
- C / C++ API → Vectors and frames: converts
- C / C++ API → Time handling: handles
- C / C++ API → Visual magnitudes: calculates
- C / C++ API → Topocentric positions: calculates
- C / C++ API → Atmospheric refraction: corrects
- C / C++ API → Observer gravity: calculates
- C / C++ API → Rise and set: searches
- C / C++ API → Twilight searches: searches
- C / C++ API → Lunar phases: searches
- C / C++ API → Eclipse predictions: predicts
- C / C++ API → Planetary transits: predicts
- C / C++ API → Seasons: predicts
- C / C++ API → Planet events: predicts
- C / C++ API → Jupiter moons: calculates
- C / C++ API → Small-body simulation: simulates
- C / C++ API → Constellations: identifies
- C / C++ API → Lunar details: calculates
- C / C++ API → Body orientation: calculates