88 lines
3.9 KiB
Markdown
88 lines
3.9 KiB
Markdown
---
|
|
title: Workspace architecture
|
|
summary: The layer structure of the apsis-rs workspace, the crates in each layer, and the dependency rule that keeps them ordered.
|
|
tags: architecture, layers, crates
|
|
---
|
|
|
|
# Workspace architecture
|
|
|
|
`apsis-rs` is a Cargo workspace whose member crates are grouped into layers.
|
|
The grouping is enforced by a rule rather than by convention: a crate in one
|
|
layer may depend on crates in the layers to its left and on no crate to its
|
|
right. The published facade crate `apsis-rs` re-exports the layers and turns
|
|
each one into a Cargo feature.
|
|
|
|
```text
|
|
foundation -> physics -> orbit -> rf -> network -> ops -> sim
|
|
```
|
|
|
|
## The layer rule
|
|
|
|
The rule gives two properties that matter in practice:
|
|
|
|
- **A change does not propagate upward.** A new physical constant or a
|
|
corrected unit conversion is made in one layer and every layer above it
|
|
sees the change without edits.
|
|
- **A layer can be understood alone.** Reading the `orbit` layer requires
|
|
reading `physics` and `foundation`, and requires reading nothing about
|
|
radio links or scheduling.
|
|
|
|
A layer crate declares its dependencies explicitly, so the rule is visible
|
|
in each manifest and a violation fails the build rather than becoming a
|
|
habit.
|
|
|
|
## Layers and crates
|
|
|
|
| Layer | Crates | Responsibility |
|
|
|-------|--------|----------------|
|
|
| foundation | `apsis-core`, `apsis-units`, `apsis-math`, `apsis-macros` | Constants, errors, quantity newtypes, linear algebra |
|
|
| physics | `apsis-time`, `apsis-leap`, `apsis-coord`, `apsis-geodesy`, `apsis-frames` | Time scales, leap seconds, frames, ellipsoids |
|
|
| orbit | `apsis-tle`, `apsis-sgp4`, `apsis-kepler`, `apsis-ephemeris`, `apsis-maneuver`, `apsis-orbit` | Element parsing, propagation, two-body motion, interpolation, maneuvers |
|
|
| rf | `apsis-rf`, `apsis-antenna`, `apsis-doppler`, `apsis-atmosphere`, `apsis-noise`, `apsis-interference`, `apsis-link` | Radio links and antennas |
|
|
| network | `apsis-constellation`, `apsis-coverage`, `apsis-access`, `apsis-topology`, `apsis-isl`, `apsis-routing`, `apsis-handover`, `apsis-mesh` | Constellations and networks |
|
|
| ops | `apsis-resource`, `apsis-task`, `apsis-scheduler`, `apsis-conflict`, `apsis-schedule` | Resources, tasks, schedules |
|
|
| sim | `apsis-sim-engine`, `apsis-scenario`, `apsis-event`, `apsis-output`, `apsis-sim` | Discrete event simulation |
|
|
|
|
## Features of the facade
|
|
|
|
The facade crate has no default features. Each feature enables one layer and
|
|
the features of the layers below it.
|
|
|
|
| Feature | Enables |
|
|
|---------|---------|
|
|
| `foundation` | foundation |
|
|
| `physics` | foundation, physics |
|
|
| `orbit` | foundation, physics, orbit |
|
|
| `rf` | everything above, plus rf |
|
|
| `network` | everything above, plus network |
|
|
| `ops` | everything above, plus ops |
|
|
| `sim` | every layer, including sim |
|
|
| `full` | an alias for `sim` |
|
|
|
|
This service builds against `orbit`, which is the smallest feature set that
|
|
contains the element, propagation, time, and geometry kernels it needs. The
|
|
crate structure graph shown in the interface section is generated from the
|
|
catalog, so it describes the enabled set rather than the whole workspace.
|
|
|
|
## Error strategy
|
|
|
|
Two kinds of error type exist.
|
|
|
|
`apsis-core` defines a general `Error` with a coarse `ErrorKind`. It exists
|
|
so that a function whose failure has no interesting structure can report it
|
|
without inventing a type. It is deliberately **not** the error type of the
|
|
layers.
|
|
|
|
A layer with a domain specific failure defines its own error enum. The
|
|
element parser has `ElementErrorKind` with variants such as `Checksum` and
|
|
`TooShort`; the propagator has `PropagationErrorKind` with variants such as
|
|
`InvalidElements` and `Decayed`. A caller matches on the variant, so the
|
|
variant names name the conditions a caller would want to distinguish. Each
|
|
error also carries optional detail text for a message, and implements
|
|
`Display` and `std::error::Error`.
|
|
|
|
## See also
|
|
|
|
- The service presents this structure as a graph: `GET /api/graph/crates`
|
|
- The interface catalog: `GET /api/api`
|