aloistr/swisseph

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.