Crate boundaries
What this page is
A map of the workspace: twenty-one crates, how they depend on each other, and what that layering commits the project to.
Everything here is read from the Cargo.toml files rather than from
description, so it stays true as long as the drift check passes.
The dependency graph is a DAG with a single root
The graph has no cycles and exactly one crate with no internal dependencies that
everything else eventually reaches: orbitforge-core.
Edges are simplified above to keep the diagram readable. The binding constraint is the layering, not any individual edge.
What each layer owns
| Layer | Crates | Owns |
|---|---|---|
| Foundation | core | Time, frames, vectors, units |
| Standalone | dsp, econ, resilience | Signal processing, cost models, failure statistics |
| Orbit mechanics | orbits | Propagators, elements, transformations |
| Fleet | constellation, sim | Patterns, satellites, propagated timelines |
| Domain analysis | ca, maneuver, od, coverage, link, scenario, twin, waveform, replan | One analysis discipline each |
| Composed | design, io, trade | Multi-discipline synthesis and serialization |
| Interfaces | cli, api | Argument parsing, routing, presentation |
Three crates depend on nothing else in the workspace: dsp, econ, and
resilience, alongside core itself.
That is a deliberate signal. Signal processing, cost estimation, and failure statistics do not need orbital mechanics, and keeping them unattached means they can be tested and reasoned about without constructing a constellation.
Four capabilities exist only in the API
Counting internal dependencies:
| Interface | Workspace crates used |
|---|---|
api | 19 |
cli | 15 |
The difference is exactly four crates, and the asymmetry runs one way only:
| API-only | CLI-only |
|---|---|
econ | none |
replan | |
resilience | |
trade |
The API is a strict superset of the CLI. There is no capability reachable from the command line that the HTTP interface lacks.
Cost estimation, replanning, resilience analysis, and trade-space sweeps have no CLI equivalent. If you are scripting against those four, the API is not a convenience, it is the only route.
This shows up in the totals the drift check reports: 25 CLI commands against 46 API endpoints. The gap is not duplication, it is those four crates plus the finer-grained analysis routes.
Size is not evenly distributed
Lines of Rust under src, largest first:
| Crate | Lines | Crate | Lines |
|---|---|---|---|
api | 8550 | od | 1878 |
orbits | 8192 | sim | 1288 |
link | 4512 | coverage | 933 |
io | 4420 | twin | 844 |
dsp | 4307 | replan | 825 |
waveform | 3919 | ca | 815 |
cli | 3495 | constellation | 675 |
scenario | 2639 | resilience | 657 |
maneuver | 2590 | econ | 514 |
design | 2012 | trade | 428 |
core | 1976 |
Two observations worth drawing out.
orbits at 8192 lines is the second-largest crate and sits near the bottom of
the graph, so almost everything depends on it. It carries the propagator ladder,
frame chain, and element conversions, and a change there has the widest blast
radius in the workspace.
api at 8550 lines is the largest, and it is an interface crate. That is worth
watching: routing and serialization should be thin. Its size comes from
per-endpoint request and response types, and from validation performed before
dispatch, which is discussed in API architecture.
Reference coverage
The verification gate reports crate coverage on every run:
Crates in workspace: 21. REQ-SRC-3 requires an explicit publish-or-omit
decision for any crate without a reference page.The current decision is omit, and this page is the record of it.
Per-crate reference pages document internal API surface, which is useful to contributors and misleading to everyone else, because a documented internal type reads as a stability promise the project has not made.
The user-facing contract is the CLI and the HTTP API, and both are documented
exhaustively and drift-checked against the source. This page documents the
boundaries; cargo doc documents the types.
That decision is revisitable. If the crates are published to a registry, or if external code starts depending on them directly, they acquire a compatibility surface that needs its own reference.
Rules the layering implies
- A new analysis discipline is a new crate at the domain layer, depending on
simand below. - Nothing below the interface layer may depend on
cliorapi. Presentation does not belong in a domain crate. - A crate that needs two disciplines belongs at the composed layer, as
designandtradedo. coretakes no workspace dependencies, ever. It is the shared vocabulary and a dependency there would create a cycle through the whole graph.
Next steps
- System overview for analysis flow and data ownership.
- API architecture for how the interface layer is put together.
- Decision records.
main (pre-release)