# aloistr/swisseph architecture

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

- Interactive diagram: https://gitdiagram.com/aloistr/swisseph
- Repository: https://github.com/aloistr/swisseph

## Overview

1. **What this repository is**
   - Swiss Ephemeris is primarily a **C calculation library** for astronomical/astrological ephemerides, not an application server or web app.
   - The repo bundles the **core source code**, **ephemeris data files**, **CLI tools**, **tests**, **documentation**, and **platform bindings**.

2. **Core computation engine**
   - The main library lives in the root C files: `sweph.c`, `swephlib.c`, `swedate.c`, `swehouse.c`, `swemmoon.c`, `swemplan.c`, `swecl.c`, `swehel.c`, `swejpl.c`, and related headers.
   - These modules implement the low-level astronomy logic: date/time conversion, planetary and lunar calculations, house systems, eclipses, coordinate transforms, and JPL ephemeris access.

3. **Public API boundary**
   - `swephexp.h`, `sweph.h`, `swedll.h`, and the other headers define the callable API and exported symbols.
   - The architecture is a classic library boundary: external programs call Swiss Ephemeris functions, which then resolve data files and compute results internally.

4. **Ephemeris data as a separate runtime dependency**
   - The `ephe/` directory is not code; it is the **runtime data store** the library reads from.
   - It contains compressed planetary and lunar files (`*.se1`), asteroid files, star lists, leap-second data, and lookup lists.
   - The README makes clear that the library searches these files through an **ephemeris path** configured at runtime, via defaults, environment variables, or `swe_set_ephe_path()`.

5. **Data flow: from API call to file-backed calculation**
   - A consumer calls a library function with a date/time and target object.
   - The library normalizes the input using the date/time subsystem, then looks up the required ephemeris record in `ephe/` or, when configured, in external JPL files.
   - The result is computed and returned directly to the caller; there is no persistent application state or database layer.

6. **JPL integration**
   - `swejpl.c` and related files provide support for **JPL binary ephemerides** such as DE200, DE406, DE431, and DE441.
   - These files are external downloads from NASA JPL and are treated as optional high-precision runtime inputs.
   - This creates a boundary between Swiss Ephemeris logic and third-party scientific data.

7. **Command-line tools**
   - `swetest.c` is the main interactive/automation CLI for querying calculations from the library.
   - `swevents.c` is a higher-level tool for event searches, built on top of the same calculation engine.
   - `bin/` contains helper launchers/scripts for these executables.

8. **Regression and validation subsystem**
   - `setest/` is a substantial test harness with suites for calculations, fixstars, dates, houses, eclipses, rise/set, and other domains.
   - It includes custom readers, checkpointing, generated fixtures, and shell/perl helpers, indicating the project relies on **data-driven regression testing** against known outputs.
   - This test layer is important for preserving numerical correctness across releases.

9. **Platform-specific integrations**
   - `contrib/android/jni/` contains JNI bindings and Android build files, showing how the C core is exposed to Android applications.
   - `windows/` contains native Windows programs, resources, and VB declaration files for integration with Windows tooling and Excel/VB environments.
   - These are wrappers around the same underlying C engine rather than separate implementations.

10. **Documentation and release packaging**
   - `doc/` contains the user and programmer documentation, including PDFs and HTML.
   - `contrib/` also holds third-party examples, language bindings, and packaged binaries.
   - The repo structure reflects a distribution model where the source library, binary data files, and consumer integrations are shipped together.

11. **Build and distribution model**
   - The top-level `Makefile` and per-subdirectory makefiles indicate a portable C build targeting multiple platforms.
   - There is no single runtime service; instead, the build produces libraries and tools that depend on the ephemeris data files being placed correctly on disk.

12. **Architectural diagram takeaway**
   - A good diagram should show:
     - **Consumers**: CLI tools, tests, Windows apps, Android JNI, and external language bindings.
     - **Core library**: the C calculation engine.
     - **Data inputs**: local `ephe/` files and optional JPL binaries.
     - **Support layers**: tests, docs, and platform-specific wrappers.
   - The key architectural theme is a **file-backed scientific computation library with multiple front ends**.

Main entry points: [`sweph.c`](https://github.com/aloistr/swisseph/blob/master/sweph.c) (Calc engine), [`swephexp.h`](https://github.com/aloistr/swisseph/blob/master/swephexp.h) (Public API), [`Makefile`](https://github.com/aloistr/swisseph/tree/master/Makefile) (Build files), [`doc/README.md`](https://github.com/aloistr/swisseph/blob/master/doc/README.md) (Documentation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Core library"]
  node_api["Public API<br/>headers<br/>[swephexp.h]"]
  node_date["Date/time<br/>core module<br/>[swedate.c]"]
  node_planets["Planets<br/>core module<br/>[swemplan.c]"]
  node_houses["Houses<br/>core module<br/>[swehouse.c]"]
  node_events["Events<br/>core module<br/>[swecl.c]"]
  node_engine(("Calc engine<br/>library core<br/>[sweph.c]"))
  node_support["Support lib<br/>library core<br/>[swephlib.c]"]
  node_jpl["JPL access<br/>optional backend<br/>[swejpl.c]"]
end

subgraph group_data["Runtime data"]
  node_ephe[("Ephemeris files<br/>runtime data")]
  node_jpldata[("JPL binaries<br/>runtime data")]
end

subgraph group_tools["Command-line tools"]
  node_swetest["swetest<br/>CLI query<br/>[swetest.c]"]
  node_swevents["swevents<br/>CLI search<br/>[swevents.c]"]
end

subgraph group_validation["Validation"]
  node_setest["Regression suite<br/>test harness<br/>[setest.c]"]
  node_suites["Test suites<br/>test cases<br/>[suite_01_calc.c]"]
end

subgraph group_platforms["Platform bindings"]
  node_android["Android JNI<br/>binding<br/>[swejni.c]"]
  node_windows["Windows apps<br/>integration<br/>[swewin.c]"]
end

subgraph group_docs["Docs & packaging"]
  node_docsnode["Documentation<br/>docs<br/>[README.md]"]
  node_build["Build files<br/>build system"]
end

node_swetest -->|"calls"| node_api
node_swevents -->|"calls"| node_api
node_setest -->|"validates"| node_api
node_suites -->|"drives"| node_setest
node_android -->|"binds"| node_api
node_windows -->|"wraps"| node_api
node_api -->|"fronts"| node_engine
node_engine -->|"normalizes"| node_date
node_engine -->|"computes"| node_planets
node_engine -->|"computes"| node_houses
node_engine -->|"derives"| node_events
node_engine -->|"uses"| node_support
node_engine -->|"optionally uses"| node_jpl
node_engine -->|"reads"| node_ephe
node_jpl -->|"reads"| node_jpldata
node_build -->|"builds"| node_swetest
node_build -->|"builds"| node_swevents
node_build -->|"packages"| node_android
node_build -->|"packages"| node_windows
node_docsnode -->|"describes"| node_api
node_docsnode -->|"documents"| node_swetest
node_docsnode -->|"documents"| node_setest

click node_api "https://github.com/aloistr/swisseph/blob/master/swephexp.h"
click node_date "https://github.com/aloistr/swisseph/blob/master/swedate.c"
click node_planets "https://github.com/aloistr/swisseph/blob/master/swemplan.c"
click node_houses "https://github.com/aloistr/swisseph/blob/master/swehouse.c"
click node_events "https://github.com/aloistr/swisseph/blob/master/swecl.c"
click node_engine "https://github.com/aloistr/swisseph/blob/master/sweph.c"
click node_support "https://github.com/aloistr/swisseph/blob/master/swephlib.c"
click node_jpl "https://github.com/aloistr/swisseph/blob/master/swejpl.c"
click node_ephe "https://github.com/aloistr/swisseph/tree/master/ephe"
click node_swetest "https://github.com/aloistr/swisseph/blob/master/swetest.c"
click node_swevents "https://github.com/aloistr/swisseph/blob/master/swevents.c"
click node_setest "https://github.com/aloistr/swisseph/blob/master/setest/setest.c"
click node_suites "https://github.com/aloistr/swisseph/blob/master/setest/suite_01_calc.c"
click node_android "https://github.com/aloistr/swisseph/blob/master/contrib/android/jni/swejni.c"
click node_windows "https://github.com/aloistr/swisseph/blob/master/windows/swewin/swewin.c"
click node_docsnode "https://github.com/aloistr/swisseph/blob/master/doc/README.md"
click node_build "https://github.com/aloistr/swisseph/tree/master/Makefile"

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_api,node_date,node_planets,node_houses,node_events,node_engine,node_support,node_jpl toneBlue
class node_ephe,node_jpldata toneAmber
class node_swetest,node_swevents toneMint
class node_setest,node_suites toneRose
class node_android,node_windows toneIndigo
class node_docsnode,node_build toneTeal
```

## Components

### Core library

C ephemeris engine and public API boundary

- [Public API](https://github.com/aloistr/swisseph/blob/master/swephexp.h): headers · Callable surface and exported symbols · `swephexp.h`
- [Date/time](https://github.com/aloistr/swisseph/blob/master/swedate.c): core module · Input normalization and calendar conversions · `swedate.c`
- [Planets](https://github.com/aloistr/swisseph/blob/master/swemplan.c): core module · Planetary and lunar position calculations · `swemplan.c`
- [Houses](https://github.com/aloistr/swisseph/blob/master/swehouse.c): core module · House system calculations · `swehouse.c`
- [Events](https://github.com/aloistr/swisseph/blob/master/swecl.c): core module · Eclipses, rises, and other derived phenomena · `swecl.c`
- [Calc engine](https://github.com/aloistr/swisseph/blob/master/sweph.c): library core · Main orchestration and ephemeris computations · `sweph.c`
- [Support lib](https://github.com/aloistr/swisseph/blob/master/swephlib.c): library core · Shared helpers, tables, and constants · `swephlib.c`
- [JPL access](https://github.com/aloistr/swisseph/blob/master/swejpl.c): optional backend · Binary ephemeris integration for external DE files · `swejpl.c`

### Runtime data

Ephemeris files and lookup tables consumed at runtime

- [Ephemeris files](https://github.com/aloistr/swisseph/tree/master/ephe): runtime data · Local planetary, lunar, asteroid, and star data files · `ephe`
- **JPL binaries**: runtime data · Optional high-precision external ephemeris files

### Command-line tools

Executable front ends built on the library

- [swetest](https://github.com/aloistr/swisseph/blob/master/swetest.c): CLI query · Interactive and scripted calculation frontend · `swetest.c`
- [swevents](https://github.com/aloistr/swisseph/blob/master/swevents.c): CLI search · Event-search tool built on the library · `swevents.c`

### Validation

Regression suites and test harnesses

- [Regression suite](https://github.com/aloistr/swisseph/blob/master/setest/setest.c): test harness · Data-driven validation and checkpointing system · `setest/setest.c`
- [Test suites](https://github.com/aloistr/swisseph/blob/master/setest/suite_01_calc.c): test cases · Calculation, houses, eclipses, rise/set, and related suites · `setest/suite_01_calc.c`

### Platform bindings

Native integrations for Android and Windows

- [Android JNI](https://github.com/aloistr/swisseph/blob/master/contrib/android/jni/swejni.c): binding · JNI bridge and Android build wrappers around the C core · `contrib/android/jni/swejni.c`
- [Windows apps](https://github.com/aloistr/swisseph/blob/master/windows/swewin/swewin.c): integration · Native Windows programs and VB declarations using the library · `windows/swewin/swewin.c`

### Docs & packaging

Documentation and distribution artifacts

- [Documentation](https://github.com/aloistr/swisseph/blob/master/doc/README.md): docs · User and programmer manuals plus HTML/PDF output · `doc/README.md`
- [Build files](https://github.com/aloistr/swisseph/tree/master/Makefile): build system · Portable make-based build and release packaging · `Makefile`

## Connections

- swetest → Public API: calls · CLI invokes the public C API
- swevents → Public API: calls · Event search tool uses library functions
- Regression suite → Public API: validates · Regression harness exercises the API
- Test suites → Regression suite: drives · Suite modules feed the test runner
- Android JNI → Public API: binds · JNI exposes the engine to Android apps
- Windows apps → Public API: wraps · Windows programs and VB declarations target the same core
- Public API → Calc engine: fronts · Public entry points dispatch into the calculation engine
- Calc engine → Date/time: normalizes · Input dates and times are converted before computation
- Calc engine → Planets: computes · Coordinates and positions are derived here
- Calc engine → Houses: computes · House-system results are produced here
- Calc engine → Events: derives · Higher-level phenomena are calculated here
- Calc engine → Support lib: uses · Shared helpers and tables support the main engine
- Calc engine → JPL access: optionally uses · High-precision mode delegates to JPL reader support
- Calc engine → Ephemeris files: reads · Standard calculations load file-backed ephemeris records
- JPL access → JPL binaries: reads · Optional backend consumes external binary ephemerides
- Build files → swetest: builds · Portable build produces CLI tools
- Build files → swevents: builds · Portable build produces CLI tools
- Build files → Android JNI: packages · Android makefiles and JNI sources are part of distribution
- Build files → Windows apps: packages · Windows artifacts and wrappers are distributed with the repo
- Documentation → Public API: describes · Documentation explains the library boundary and usage
- Documentation → swetest: documents · Manuals cover CLI usage and examples
- Documentation → Regression suite: documents · Test harness behavior and workflows are documented